Текущая фаза:
Опубликованы тематические исследования. Смотрите хронологию .
Season of Docs — это программа устойчивого развития, управляемая Управлением программ Google с открытым исходным кодом . Цели Season of Docs:
- Обеспечить поддержку проектов с открытым исходным кодом для решения проблем проекта с документацией.
- Дайте техническим писателям возможность получить опыт работы с открытым исходным кодом.
- Повышайте осведомленность об открытом исходном коде, документации и технических текстах.
- Собирайте и делитесь информацией об эффективных метриках в документации с открытым исходным кодом.
Более подробную информацию о Season of Docs можно найти на сайте программы.
Обзор программы на 2022 год
Как работает «Сезон Документов»
В сезоне «Документация» организации подают заявки, отправляя проектное предложение. Проектное предложение включает в себя:
- Информация об организации
- Описание проблемы, с которой сталкивается проект.
- Как проект будет использовать документацию для решения проблемы
- Как проект будет измерять эффективность своей документации (метрики)
- График выполнения работы
- Бюджет проекта
- Любая дополнительная информация, например опыт организации в аналогичных программах или что-либо еще, что поможет администраторам Season of Docs понять их проект и проблему.
После принятия в программу организации нанимают и нанимают собственных технических писателей напрямую. Season of Docs использует Open Collective для финансирования организаций, а организации платят техническим писателям через Open Collective. Бюджеты и платежи проектов прозрачны; budgets are included in the organization project proposals available on the Season of Docs site , and payments are visible in the Season of Docs Open Collective account .
Считается, что организации успешно завершили программу, когда они представляют отчет о тематическом исследовании. Организациям также предлагается проводить ежемесячные оценки в ходе программы и три ежеквартальных последующих опроса в течение года после завершения программы.
Основные события 2022 года
«После выхода нового документа количество ежедневных посещений Casbin и Casdoor увеличилось почти вдвое, а показатель отказов снизился примерно на 30%» — Касбин
«Восхитительным результатом этого проекта стало то, что [наши технические писатели] стали лидерами в нашем сообществе. Оба участника сейчас возглавляют встречи рабочих групп и сообщества, а также вносят свой вклад в разработку и поддержку наших проектов». —moja-global
«[GSoD] помог нам нанять двух талантливых технических писателей, что очень сложно при обычной настройке, которые продолжают активно вносить вклад в ОС OpenMined и с которыми у нас есть большой опыт работы». —OpenMined
«Кроме того, новое руководство намного проще для новичков в вычислительной масс-спектрометрии. Чтобы проиллюстрировать эту мысль: грант CZI также предоставляет стипендии исторически малообеспеченным лицам, а некоторые лауреаты использовали новое руководство OpenMS, чтобы начать шестинедельный период стажировки, и дали положительные отзывы о новом руководстве». —OpenMS
Сводные данные за 2022 год
В 2022 году в программу «Сезон документов» был принят 31 проект из 67 заявок, успешно завершили программу 30 проектов. Из 31 принятой организации 17 организаций подавали повторные заявки.
Для 31 принятого проекта было нанято 58 технических писателей. Более 190 технических писателей выразили заинтересованность в участии в программе, добавив свою контактную информацию и ссылки на свои портфолио в репозиторий Season of Docs на GitHub.
По программе 2022 года:
- 100% организаций получили положительный опыт процесса подачи заявки
- 100% организаций получили положительный опыт работы с документацией/контентом веб-сайта программы.
- 93% организаций имели положительный опыт работы с программой
- 90% организаций считают, что их проект документации был успешным
Об организациях
Организации, участвовавшие в Season of Docs 2022, представляли широкий спектр проектов с открытым исходным кодом. В когорту 2022 года вошли:
- Инструменты разработки, такие как AsyncAPI и SpyderIDE.
- Языки программирования и платформы, такие как Julia , LFortran , R и p5.js.
- Научные проекты, такие как CERN-HSF и SymPy.
- Приложения для конечных пользователей, такие как Mautic , Open Food Facts , Talawa и Ushahidi.
- Проекты в области аппаратного обеспечения и робототехники, такие как ExpressLRS и Open-RMF.
- Проекты данных, такие как GeomScale , GeomStats , OpenMined и Weaviate.
- Облачные и инфраструктурные проекты, такие как cert-manager , NimbleEdge и Cilium.
Мы не собирали никаких метаданных о проектах (таких как дата основания, географическое распределение участников, количество участников или размер пользовательской базы).
Мы просили проекты указать, какую лицензию с открытым исходным кодом они использовали.
О проектах документации
Проблемы с документацией
Основные проблемы, которые организации надеялись решить с помощью документации в программе 2022 года, включали:
Обратите внимание, что организации могут сообщать о многочисленных проблемах с документацией. Более подробную информацию можно найти на странице результатов сезона «Документация 2022» со ссылками на исходные предложения по проектам и полные тематические исследования для каждой организации.
Виды создаваемой документации
Документация с практическими рекомендациями была наиболее часто упоминаемым типом документации в тематических исследованиях 2022 года.
Другие типы документации, упомянутые в тематических исследованиях, включали:
- Быстрый старт
- Глоссарий
- Часто задаваемые вопросы
- База знаний
- Компоненты
- Контент для блога/социальной сети
- Руководство сопровождающего
Некоторые из этих категорий нечеткие, и один проект документации может содержать несколько типов документации или функций.
Более подробную информацию можно найти на странице результатов сезона «Документация 2022» со ссылками на исходные предложения по проектам и полные тематические исследования для каждой организации.
Бюджеты
Средний бюджетный запрос составил 11 679 долларов, а медианный — 12 150 долларов. Пять организаций запросили и получили самый высокий из доступных грантов (15 тысяч долларов США), а три запросили самый низкий (от 5 до 7 тысяч долларов США).
Метрики
В своих тематических исследованиях участники проектов описали показатели, которые они использовали для оценки успеха своих проектов по документированию.
Наиболее популярными предлагаемыми показателями были:
Другие предложенные показатели включали:
- Дополнительные запросы на получение документации/вклады
- Более прямая обратная связь на страницах документации.
- Время, проведенное на странице
- Поднятые вопросы (в качестве прокси для использования)
- Участники форумов
- Количество партнеров/волонтеров/интеграций
- Снижен показатель отказов
- Повышение осведомленности в обществе.
Из-за короткого промежутка между завершением проектов технического написания и отправкой тематических исследований большая часть когорты 2022 года не смогла собрать достаточно данных на момент подачи своих тематических исследований, чтобы определить, были ли достигнуты их первоначальные показатели.
По мере получения ответов на последующие опросы в 2023 году мы обновим этот отчет, добавив информацию о том, какие проекты достигли своих показателей или пересмотрели свои показатели.
Более подробную информацию можно найти на странице результатов сезона «Документация 2022» со ссылками на исходные предложения по проектам и полные тематические исследования для каждой организации.
Работа с техническими писателями
Ожидается, что в рамках программы «Сезон документации» проекты будут нанимать, проводить собеседования, нанимать и платить техническим писателям напрямую. Технические писатели могут добавлять себя в каталог, поддерживаемый Season of Docs, в нашем репозитории GitHub , но сотрудники Season of Docs не проверяют и не рекомендуют технических писателей.
Лучшие практики найма технических писателей для проектов с открытым исходным кодом
Проектам было предложено поделиться своими лучшими практиками подбора, найма и работы с техническими писателями. Главными рекомендациями были:
Рекрутинг
- Проводите собеседования с меньшим количеством кандидатов и используйте живую практику, а не просто просмотр резюме.
- Цените навыки письменного и устного общения выше владения языком или инструментами вашего проекта.
- Задавайте прямые вопросы о том, как технический писатель получит знания предметной области, необходимые для работы с вашим проектом.
- Тот, кто с энтузиазмом относится к миссии вашего проекта и разделяет основные ценности открытого исходного кода, с большей вероятностью сохранит мотивацию на протяжении всего проекта.
- Будьте открыты для кандидатов со всего мира, поскольку разнообразие точек зрения и опыта поможет вашему проекту, но помните, что наличие писателей и наставников в слишком многих конфликтующих часовых поясах может потребовать много дополнительных усилий для поддержания хорошего общения.
Найм
- Используйте контракт, в котором четко прописаны результаты, графики платежей и конкретные временные обязательства.
- Если в вашем проекте много неизвестных, укажите этап открытия или исследования отдельно от создания документации.
Координация и общение
- Ведите журнал собраний, записывая решения, чтобы всем, кто работает над проектом, было легче понять контекст и следующие шаги.
- Четко определите, какое общение ожидается и как часто, будь то еженедельные звонки, ежедневные электронные письма или обновления статуса в канале чата.
- Будьте отзывчивы и давайте четкую обратную связь, включающую в себя «почему», а не только «что».
- Свяжите своих технических писателей с более широким сообществом, чтобы дать им контекст и популяризировать их работу.
Процессы и инструменты
- Создайте процесс документирования, который продлится после завершения программы «Сезон документации» и в который все сообщество сможет внести свой вклад.
- Проверка документации займет как минимум столько же времени и усилий, как и проверка кода; убедитесь, что у вас достаточно времени для этого
Некоторые рекомендации были отредактированы и сокращены для ясности.
Как и в программе 2021 года, большинство технических авторов в сезоне «Документация 2022» обращались напрямую в организации, с которыми они работали.
Распространенные проблемы при работе с техническими писателями
Меньшее количество проектов сообщало о проблемах с техническими писателями в программе 2022 года. Самая большая проблема заключалась в том, что технические писатели не могли завершить программу из-за болезни, работы на полный рабочий день или неспособности уложиться в отведенное время.
Один проект сообщил, что их проект документации зависел от работы, выполняемой в рамках Google Summer of Code , и что этими зависимостями было трудно управлять. Другой проект столкнулся с трудностями, когда оборудование, которое технический писатель должен был документировать, было конфисковано Министерством обороны в стране автора и не могло быть импортировано.
Последующие опросы
Три дополнительных опроса будут разосланы участникам 2022 года в мае, августе и ноябре 2023 года. Мы будем обновлять этот раздел результатами по мере их получения.
Будущие вопросы
Как всегда, чем больше мы узнаем о документации с открытым исходным кодом, тем больше нам хочется узнать!
В будущих сезонах мы надеемся:
- Соберите больше метаданных проекта, чтобы найти корреляцию между возрастом проекта, размером сообщества или потребностями в языке и документации.
- Анализируйте проекты документации, чтобы увидеть, можно ли их обобщить в общие шаблоны.
- Разработайте рубрику для собеседований с техническими писателями в проектах с открытым исходным кодом.
Хотя есть много вопросов, которые мы хотели бы изучить, мы также хотим уважать время администраторов и сопровождающих проектов с открытым исходным кодом, которые участвуют в Season of Docs. Главным приоритетом программы является поддержка проектов в решении проблем с документацией.