Текущая фаза:
Программа «Сезон документации 2021» завершилась 14 декабря 2021 г. См. график .
Вот несколько рекомендаций, которые помогут организациям с открытым исходным кодом эффективно работать с техническими писателями.
Познакомьте технического писателя с миром открытого исходного кода и своим сообществом.
- Устройте техническому писателю «экскурсию» по вашему сообществу. Где они могут задавать вопросы? Какие регулярные встречи им следует посещать или к каким спискам рассылки им следует присоединиться? Какие учетные записи им нужны (Github, Discord, Slack)? Убедитесь, что они понимают кодекс поведения вашего проекта и знают, как сообщить о любых проблемах. Убедитесь, что ваш технический писатель понимает лицензию вашего проекта и соблюдает любые требования других работодателей в отношении подписания CLA, DCO или других соглашений.
- Если возможно, познакомьте их с несколькими людьми в пересекающихся часовых поясах, которые смогут быстро ответить на вопросы о сообществе или проекте.
- Если можете, пришлите им что-нибудь из проекта!
Помогите техническому писателю использовать инструменты и процессы, необходимые для участия в вашем проекте.
- Если ваши процессы плохо документированы, назначьте время, чтобы рассказать техническому писателю о его первом вкладе, проблеме или запросе на включение. Какие шаблоны или теги им следует использовать? Кому необходимо проверять свой вклад, и как и когда они должны следить за отзывами? Если их работа включает примеры кода, как их можно протестировать? Что им нужно знать о вашем процессе или выпусках CI/CD?
Помогите техническому писателю понять ваш проект и его пользователей.
- Подробно объясните свой проект, чтобы технический писатель получил четкое концептуальное представление о продукте. Это может помочь техническому писателю чувствовать себя более уверенно и более авторитетно при написании статей для проекта.
- Опишите потребности людей, которые используют проект. Будьте как можно конкретнее — не просто «разработчики», а «разработчики, создающие веб-сайты» и «разработчики, программирующие промышленных роботов».
- Свяжите технического писателя с необходимыми экспертами в данной области. То есть разработчики или другие участники проекта, ответственные за те аспекты вашего проекта, которые будут охватываться в документации.
- Убедитесь, что технический писатель получает необходимое время и ресурсы от экспертов в данной области и любых других членов сообщества.
Задавайте вопросы!
- Возможно, ваше сообщество или проект раньше не работали с техническими писателями или авторами документации. Воспользуйтесь возможностью учиться и делиться своими знаниями! Попросите оставить отзыв о ваших процессах и инструментах — у вашего технического писателя, скорее всего, есть предложения по улучшению.