Отчет о тематическом исследовании за 2021 год

Примечание. В этом отчете обобщены данные исходных программных заявок и окончательных тематических исследований организаций. Ссылки на полные тематические исследования можно найти на странице результатов сезона «Документация 2021» .

О сезоне «Документации»

Season of Docs — это программа устойчивого развития, управляемая Управлением программ Google с открытым исходным кодом . Цели сезона документации:

• Обеспечить поддержку проектов с открытым исходным кодом для решения проблем проекта с документацией.
• Дайте техническим писателям возможность получить опыт работы с открытым исходным кодом.
• Повышайте осведомленность об открытом исходном коде, документации и технических текстах.
• Собирайте и делитесь информацией об эффективных метриках в документации с открытым исходным кодом.

Более подробную информацию о Season of Docs можно найти на сайте программы.

Обзор программы на 2021 год

Изменения в программе 2021 года

В 2019 и 2020 годах организации и технические писатели подали заявки на участие в программе Season of Docs отдельно, а технические писатели подбирались к организациям администраторами программы Season of Docs. Организации предоставили наставников для работы с техническими писателями, которые получали стипендию за свою работу в зависимости от их местоположения. Программа измеряла, удовлетворены ли технические писатели, наставники и администраторы организации своим участием в программе, но не измеряла результаты документации.

В 2021 году команда Season of Docs внесла существенные изменения в программу, сместив акцент на измерение результатов документирования и предоставив большую гибкость организациям и техническим писателям.

• Организации, подавшие проектные предложения, включая бюджет и предлагаемые показатели.
• Технические писатели больше не подают заявки через Google на подбор организаций, а подают заявки непосредственно в принятые организации.
• Принятые организации получали гранты через Open Collective, которые они использовали для оплаты технических писателей.
• Вознаграждение техническим писателям установили организации
• Организации представили окончательные оценки и тематические исследования, а также ответили на последующие опросы.

Общие выводы за 2021 год

Организации

• Изменения в программе 2021 года привели к тому, что подали заявки меньше организаций (в 2021 году мы увидели на 30% меньше заявок от организаций по сравнению с 2020 годом), но администраторы организаций 2021 года были немного более удовлетворены программой, чем администраторы 2020 года (93% против 91%).

Проблемы, типы документов и метрики

• Большинство проектов были сосредоточены на создании документации для снижения нагрузки на сопровождающего (за счет уменьшения проблем/вопросов) и/или увеличения участия в проекте (как пользователей проекта, так и участников).
  • 50% принятых организаций создали обучающие материалы или практические руководства.
  • Более 50% принятых организаций считали свою текущую документацию недостаточной, неорганизованной или устаревшей.
• Проекты обычно хотели измерить эффективность своей документации посредством взаимодействия, особенно с меньшим количеством поднятых вопросов и большим количеством посетителей документов и участия в проектах.
• По состоянию на ноябрь 2022 года, когда ответили 25 из 30 проектов:
  • 18 проектов заявили, что достигли первоначальных показателей
  • 5 проектов соответствовали пересмотренным показателям
  • В 2 проектах сказали, что еще слишком рано об этом говорить

Участие в программе

• Привлечение, найм и оплата технических писателей были самой сложной частью программы для администраторов организации.
• По состоянию на ноябрь 2022 г. ответили 24 из 30 организаций:
  • 18 организаций все еще работали со своими техническими авторами Season of Docs (либо в качестве постоянных участников, либо в качестве ресурса для ответов на вопросы).
    • 4 организации работали с техническими писателями Season of Docs на оплачиваемой должности.

Основные события 2021 года

• Несколько проектов указали, что их технический писатель намеревался продолжить работу над своим проектом после окончания программы «Сезон документации».
• В Metanorma обратилось так много квалифицированных технических писателей, что они нашли соответствующие средства, чтобы нанять дополнительного писателя для работы вместе с автором, поддерживаемым Season of Docs, во время программы.
• Moja Global обнаружила, что сообщество активно занимается документацией, и создала новую рабочую группу по документации, чтобы позволить большему количеству участников участвовать в проектной документации.

Сводные данные за 2021 год

В 2021 году заявки подали 82 организации и в программу были приняты 30 организаций с открытым исходным кодом. (Критерии отбора см. в руководстве «Создание заявки» .) Полный список участвующих организаций можно найти на сайте Season of Docs . Все 30 принятых организаций представили окончательный отчет о тематическом исследовании для завершения своего участия в программе 2021 года.

Об организациях

Организации, участвующие в Season of Docs 2021, представляли широкий спектр проектов с открытым исходным кодом. В когорту 2021 года вошли:

• Большие языковые проекты, такие как Julia , Perl и R.
• Проекты в сфере образования, климата, финансовых технологий, здравоохранения, библиотечного обслуживания, машинного обучения, масс-спектрометрии, госзаказов и робототехники.
• Проекты, ориентированные на разработчиков, включая инструменты хаос-инженерии, фаззеры, SDK для чат-ботов, конвейеры анализа состава программного обеспечения, инструменты мониторинга производительности и инструменты визуального программирования.
• Проекты документации для инструментов документирования, таких как Redocly и Metanorma.

Проекты экосистемы Python были самой крупной подкатегорией. В когорту 2021 года вошли ArviZ, NumPy, MicroPython, PyMC3, PyTorch-Ignite и SymPy.

Мы не собирали никаких метаданных о проектах (таких как дата основания, географическое распределение участников, количество участников или размер пользовательской базы).

Мы просили проекты указать, какую лицензию с открытым исходным кодом они использовали.

Проблемы с документацией, изложенные организациями 2021 года, являются очень распространенными проблемами как в проектах с открытым исходным кодом, так и в технической документации в целом.

Основные проблемы, которые организации надеялись решить в программе 2021 года, включали:

Обратите внимание, что организации могут сообщать о многочисленных проблемах с документацией. Более подробную информацию можно найти на странице результатов сезона «Документация 2021», где приведены ссылки на полные тематические исследования для каждой организации.

Виды создаваемой документации

Учебные пособия были наиболее часто упоминаемым типом документации в тематических исследованиях 2021 года.

Другие типы документации, упомянутые в тематических исследованиях, включали конвейер «Документы как код», диаграмму, глоссарий, руководство по стилю, часто задаваемые вопросы, интернационализацию, Codelab, модель контента, модули, концептуальную документацию, сообщения об ошибках, исследования пользователей, файлы Readme, базу знаний.

Некоторые из этих категорий нечеткие, и один проект документации может содержать несколько типов документации или функций.

В нескольких проектах специально упоминалось использование платформы Diátaxis в качестве руководства для планирования типов документации.

Более подробную информацию можно найти на странице результатов сезона «Документация 2021», где приведены ссылки на полные тематические исследования для каждой организации.

Бюджеты

В 2021 году средний бюджетный запрос составил 10 200 долларов, а медианный — 10 000 долларов. Только три организации запросили и получили максимально возможный грант (15 тысяч долларов США), а еще три запросили минимально возможный грант (5 тысяч долларов США).

Метрики

В своих тематических исследованиях участники проектов описали показатели, которые они использовали для оценки успеха своих проектов по документированию.

Наиболее популярными предлагаемыми показателями были:

Другие предложенные показатели включали звезды GitHub, время, проведенное на странице, конверсии в списке рассылки, качественное пользовательское тестирование, количество участников на форумах, количество партнеров/добровольцев/интеграций .

Из-за короткого промежутка времени между завершением проектов технического написания и отправкой тематических исследований большая часть когорты 2021 года не смогла собрать достаточно данных, чтобы определить, были ли достигнуты их первоначальные показатели.

Более подробную информацию можно найти на странице результатов сезона «Документация 2021», где приведены ссылки на полные тематические исследования для каждой организации.

Работа с техническими писателями

Самое большое изменение в программе «Сезона документации» в 2021 году коснулось работы проектов с техническими писателями. В предыдущие сезоны технические писатели обращались напрямую в Google, и администраторы программы подбирали им проекты, а также получали фиксированную стипендию непосредственно от Google.

В 2021 году технические писатели подали заявки на проекты напрямую, и проекты установили бюджет вознаграждения технических писателей, выплаты которого осуществлялись через фонд Season of Docs Open Collective .

Большинство проектов, участвующих в программе 2021 года, имели мало или совсем не имели опыта набора технических писателей, и многие проекты назвали эту часть процесса требующей дополнительной поддержки. В ответ на этот отзыв команда Season of Docs добавила в руководство программы документацию по заключению соглашений с техническими писателями .

Рекомендации по найму

Проектам было предложено дать рекомендации другим проектам, заинтересованным в участии в Season of Docs. Наиболее распространенными рекомендациями по найму были:

• Поделитесь материалами по набору технических писателей как можно раньше, даже до того, как вас примут в программу. Попросите ваше сообщество порекомендовать возможных кандидатов.
• Широко распространяйте информацию за пределами каналов проекта. Используйте инклюзивный язык и напрямую поощряйте кандидатов из недостаточно представленных слоев общества подавать заявки.
• Узнайте, какие инструменты необходимы для процесса создания документации, и наймите технических писателей, имеющих опыт использования этих инструментов.
• Создайте четкие ожидания для технического писателя относительно результатов и этапов, каналов связи и проверок, а также процессов и сроков оплаты.
• Рассмотрите возможность инвестирования в членов сообщества и помощи им в развитии как технических писателей, используя технических писателей Season of Docs для наставничества и обучения.
• Выделите больше времени, чем вы ожидаете, на привлечение технических писателей, ответы на вопросы и оказание поддержки во время программы, особенно если технический писатель не имеет предыдущего опыта работы в области вашего проекта.
• Документируйте процесс рекрутинга, найма и адаптации, чтобы использовать его в будущих проектах.

(Примечание: в тематических исследованиях указаны не все проекты, в которых они набирали кандидатов в технические писатели.)

Распространенные проблемы при работе с техническими писателями

Техническим писателям в нескольких проектах пришлось уйти из-за COVID или других заболеваний, а также из-за семейных обязанностей, связанных с пандемией. В некоторых проектах сообщалось о проблемах со связью, связанных с несовпадением часовых поясов или проблемами подключения к Интернету.

Представители проектов обнаружили, что они недооценили трудности, связанные с адаптацией в своих сообществах или с настройкой цепочки инструментов документации своего проекта.

В некоторых проектах были задержки с оплатой технических писателей из-за банковских проблем с Open Collective или из-за того, что в странах происхождения писателей были ограничения на оплату.

В документации программы, касающейся комиссий Open Collective, не было ясности: Google покрыл комиссию за транзакцию Open Collective за первоначальный перевод средств в проекты, но не комиссию за транзакцию, взимаемую некоторыми другими платежными каналами (например, комиссию за конвертацию валюты). Мы поработаем над тем, чтобы прояснить это в документации будущих программ.

Последующие опросы

В рамках программы «Сезон документации» проектам было предложено принять участие в последующих опросах. Три опроса были отправлены в мае, августе и ноябре 2022 года.

В ходе последующего опроса проектам было предложено подтвердить, что ссылки на их предложения и тематические исследования все еще активны. Опрос также включал вопросы об успехе их проектов (согласно показателям, которые они установили в своем тематическом исследовании), а также о продолжающемся участии и вознаграждении технических писателей проекта:

1. Вы все еще работаете со своим техническим писателем Season of Docs?

1. Если ваш технический писатель все еще работает над вашим проектом, получает ли он какую-либо компенсацию?

1. Считаете ли вы, что на данный момент ваш проект документации успешен?

Будущие вопросы

Как всегда, чем больше мы узнаем о документации с открытым исходным кодом, тем больше нам хочется узнать! В будущих сезонах мы надеемся узнать:

• Связаны ли домены проекта с выбором типа документа или выбором метрики
• Какие методы найма и адаптации технических писателей наиболее эффективны для завершения проекта и удержания технических писателей
• Разумные сроки измерения эффективности документации

Хотя есть много вопросов, которые мы хотели бы изучить, мы также хотим уважать время администраторов и сопровождающих проектов с открытым исходным кодом, которые участвуют в Season of Docs. Главным приоритетом программы является поддержка проектов в решении проблем с документацией.