Season of Docs is a sustainability program managed by the Google Open Source Programs Office . The goals of Season of Docs are to:
- Provide support for open source projects to solve project problems with documentation
- Give technical writers opportunities to gain experience in open source
- Raise awareness of open source, documentation, and technical writing
- Collect and share information about effective metrics in open source documentation
More information about Season of Docs is available on the program's website .
Обзор программы 2022 года
Как работает «Сезон врачей»
In Season of Docs, organizations apply by submitting a project proposal. The project proposal includes:
- Информация об организации
- A description of the problem the project is facing
- How the project will use documentation to help solve their problem
- How the project will measure the effectiveness of their documentation (metrics)
- График выполнения работ
- Бюджет проекта
- Any additional information, such as the organization's experience in similar programs, or anything else that would help the Season of Docs administrators understand their project and problem
После принятия в программу организации самостоятельно нанимают и привлекают технических писателей. Season of Docs использует Open Collective для финансирования организаций, а организации оплачивают услуги технических писателей через Open Collective. Бюджеты проектов и платежи прозрачны; бюджеты включены в проектные предложения организаций, доступные на сайте Season of Docs , а платежи видны в учетной записи Season of Docs в Open Collective .
Организации считаются успешно завершившими программу после предоставления отчета по результатам исследования. Кроме того, организациям предлагается проводить ежемесячные оценки в течение программы и три ежеквартальных последующих опроса в течение года после ее завершения.
Основные события 2022 года
“After the new document was released, daily visits to Casbin and Casdoor almost doubled, and bounce rates dropped by about 30%.”—Casbin
«Замечательным результатом этого проекта стало то, что [наши технические писатели] выросли и заняли руководящие должности в нашем сообществе. Оба участника теперь возглавляют рабочие группы и проводят встречи сообщества, а также вносят свой вклад в разработку и поддержку наших проектов». — moja-global
«[GSoD] помог нам нанять двух талантливых технических писателей, что крайне сложно в обычной рабочей среде, которые продолжают активно участвовать в разработке ОС для OpenMined, и с которыми у нас сложились прекрасные рабочие отношения». — OpenMined
«Кроме того, новое руководство гораздо проще для новичков в вычислительной масс-спектрометрии. В качестве примера: грант CZI также предоставляет стипендии лицам, исторически находящимся в неблагоприятном положении, и некоторые лауреаты использовали новое руководство OpenMS для начала своей шестинедельной стажировки и оставили положительные отзывы о новом руководстве». — OpenMS
Сводные данные за 2022 год
В 2022 году программа Season of Docs приняла 31 проект из 67 заявок, и 30 проектов успешно завершили программу. Из 31 принятой организации 17 организаций подавали заявки повторно.
В рамках 31 принятого проекта были наняты 58 технических писателей. Более 190 технических писателей выразили заинтересованность в участии в программе, добавив свою контактную информацию и ссылки на свои портфолио в репозитории Season of Docs на GitHub.
Для программы 2022 года:
- 100% of organizations had a positive experience with the application process
- 100% of organizations had a positive experience with the program website documentation/content
- 93% организаций положительно оценили программу.
- 90% of organizations felt their documentation project was successful
Об организациях
The organizations participating in Season of Docs 2022 represented a diverse range of open source projects. The 2022 cohort included:
- Development tools, such as AsyncAPI and SpyderIDE
- Programming languages and frameworks, such as Julia , LFortran , R , and p5.js
- Научные проекты, такие как CERN-HSF и SymPy.
- End-user applications, such as Mautic , Open Food Facts , Talawa , and Ushahidi
- Hardware and robotics projects, such as ExpressLRS and Open-RMF
- Data projects, such as GeomScale , GeomStats , OpenMined , and Weaviate
- Cloud and infrastructure projects, such as cert-manager , NimbleEdge , and Cilium
We did not collect any metadata about the projects (such as date founded, geographic distribution of contributors, number of contributors, or size of user base).
We did ask projects to indicate which open source license they used.
О проектах по созданию документации
Проблемы с документацией
The top problems that organizations were hoping to solve with documentation in the 2022 program included:
Обратите внимание, что организации могут сообщать о нескольких проблемах с документацией. Для получения более подробной информации см. страницу результатов Season of Docs 2022, где приведены ссылки на оригинальные проектные предложения и полные тематические исследования каждой организации.
Типы создаваемой документации
В тематических исследованиях 2022 года наиболее часто упоминался тип документации, содержащий пошаговые инструкции.
Other documentation types mentioned in case studies included:
- Быстрый старт
- Глоссарий
- Часто задаваемые вопросы
- База знаний
- Компоненты
- Контент для блога/социальных сетей
- Руководство для сопровождающего
Некоторые из этих категорий являются расплывчатыми, и один проект по созданию документации может содержать несколько типов документации или функций.
For more specifics, see the Season of Docs 2022 results page , which links to the original project proposals and full case studies for each organization.
Бюджеты
Средний размер запрашиваемого бюджета составил 11 679 долларов, а медианный — 12 150 долларов. Пять организаций запросили и получили максимально возможный грант (15 000 долларов), а три — минимальный (от 5 000 до 7 000 долларов).
Показатели
В описанных ими проектах тематических исследованиях были указаны показатели, которые они использовали для оценки успеха своих проектов по документированию.
Наиболее часто предлагаемые показатели были следующими:
В число других предложенных показателей вошли:
- Дополнительные запросы на добавление/вклад в документацию
- Более прямая обратная связь на страницах документации.
- Время, затраченное на страницу
- Возникшие вопросы (в качестве косвенного примера использования)
- Участники форумов
- Количество партнеров/волонтеров/интеграций
- Сниженный показатель отказов
- Повышение осведомленности в обществе.
Из-за короткого промежутка времени между завершением проектов по техническому написанию и подачей тематических исследований, большинство участников группы 2022 года не смогли собрать достаточно данных к моменту подачи своих тематических исследований, чтобы определить, были ли достигнуты их первоначальные показатели.
As we receive answers to the followup surveys in 2023, we'll update this report to add information about which projects have achieved their metrics or revised their metrics.
For more specifics, see the Season of Docs 2022 results page , which links to the original project proposals and full case studies for each organization.
Работа с техническими писателями
В рамках программы Season of Docs от проектов ожидается самостоятельный набор, собеседования, найм и оплата труда технических писателей. Технические писатели могут добавить себя в каталог, поддерживаемый Season of Docs в нашем репозитории GitHub , но сотрудники Season of Docs не проводят проверку и не рекомендуют технических писателей.
Рекомендации по найму технических писателей для проектов с открытым исходным кодом.
Участникам проектов было предложено поделиться своими лучшими практиками в области подбора, найма и работы с техническими писателями. Наиболее часто встречающиеся рекомендации были следующими:
Подбор персонала
- Interview fewer candidates, and use a live practice session, rather than just reviewing CVs
- Отдавайте предпочтение навыкам письменной и устной коммуникации, а не владению языком программирования или инструментами вашего проекта.
- Задавайте прямые вопросы о том, как технический писатель получит необходимые знания в предметной области для работы над вашим проектом.
- Человек, увлеченный миссией вашего проекта и разделяющий основные ценности открытого исходного кода, с большей вероятностью сохранит мотивацию на протяжении всего проекта.
- Будьте открыты для заявок со всего мира, поскольку разнообразие точек зрения и опыта поможет вашему проекту, но помните, что наличие авторов и наставников, находящихся в разных часовых поясах, может потребовать значительных дополнительных усилий для поддержания эффективной коммуникации.
Набор персонала
- Use a contract that clearly spells out deliverables, payment schedules, and specific time commitments
- Если в вашем проекте много неизвестных факторов, включите в него отдельный этап для исследования или изучения, не связанный с созданием документации.
Координация и коммуникация
- Ведите журнал совещаний, записывая принятые решения, чтобы всем участникам проекта было проще понимать контекст и дальнейшие шаги.
- Чётко обозначьте, какой уровень коммуникации ожидается и как часто: еженедельные звонки, ежедневные электронные письма или обновления статуса в чате.
- Будьте отзывчивы и давайте четкую обратную связь, в которой указывается «почему», а не только «что».
- Наладьте связь ваших технических писателей с более широким сообществом, чтобы предоставить им контекст и популяризировать их работы.
Процессы и инструменты
- Создайте процесс документирования, который сохранится и после завершения программы «Сезон документации», и в который сможет внести свой вклад всё сообщество.
- Проверка документации займет как минимум столько же времени и потребует таких же усилий, как и проверка кода; обязательно выделите на это достаточно времени.
Некоторые рекомендации были отредактированы и сокращены для большей ясности.
Как и в программе 2021 года, большинство технических писателей, участвовавших в Season of Docs 2022, подавали заявки непосредственно в организации, с которыми они сотрудничали.
Типичные проблемы при работе с техническими писателями
В программе 2022 года меньше проектов сообщали о проблемах во взаимодействии с техническими писателями. Самой распространенной проблемой была невозможность завершения программы техническими писателями по причине болезни, работы на полную ставку или несоблюдения временных обязательств.
В одном проекте сообщили, что их работа по документированию зависела от работы, проводимой в рамках программы Google Summer of Code , и что управлять этими зависимостями было сложно. В другом проекте возникли трудности, когда оборудование, которое должен был задокументировать их технический писатель, было конфисковано Министерством обороны страны писателя и не могло быть импортировано.
Последующие опросы
Участникам исследования 2022 года будут разосланы три дополнительных опроса в мае, августе и ноябре 2023 года. Мы будем обновлять этот раздел по мере получения результатов.
Будущие вопросы
Как всегда, чем больше мы узнаём о документации в проектах с открытым исходным кодом, тем больше нам хочется узнать!
В будущих сезонах мы надеемся:
- Соберите больше метаданных о проекте, чтобы выявить корреляции между возрастом проекта, размером сообщества или языковыми и документационными потребностями.
- Проанализируйте проекты по созданию документации, чтобы определить, можно ли их преобразовать в шаблоны, которыми можно делиться.
- Разработайте критерии для проведения интервью с техническими писателями в проектах с открытым исходным кодом.
Хотя у нас много вопросов, которые мы хотели бы исследовать, мы также хотим уважать время администраторов и сопровождающих проектов с открытым исходным кодом, участвующих в Season of Docs. Главный приоритет программы — поддержка проектов в решении проблем, связанных с документацией.