Как организовать эффективное сотрудничество между техническими писателями и разработчиками

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

Трудности в написании документации разработчиками и способы их преодоления

Как известно, разработчики неохотно пишут документацию, а заставить их следовать стайлгайдам – задача просто невыполнимая. В первую очередь это связано с тем, что разработчики прежде всего сосредоточены на написании кода и решении технических задач. В условиях сжатых сроков приоритетом является создание и отладка функциональности, а документация может подождать. Это особенно характерно для команд, работающих по методологии agile, в которой главное – создание работающего продукта. Сопровождающая документация при этом вторична.

Вторая причина, тесно связанная с первой, – это недостаток времени. Современные условия работы предполагают строгие дедлайны и быстрый темп разработки. Поэтому если у разработчиков и появляется свободное время, они предпочитают потратить его на улучшение кода или добавление новых функций.

Кроме того, сама задача написания документации представляется разработчикам, мягко говоря, «непрофильной». Действительно, разработчик – это не филолог, не журналист, не контент-райтер – он не имеет отношения к гуманитарной сфере, поэтому работа «не по специальности» не вызывает ничего кроме непонимания и ощущения потерянного времени.

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

И, наконец, главный «камень преткновения» – это скептическое отношение к сопровождающей документации. Многие разработчики считают, что документацию редко читают или используют. Это предположение особенно актуально в условиях, когда на первый план в освоении цифрового продукта пользователями выходит интуитивность. По этим причинам у разработчиков, как правило, отсутствует мотивация тратить время на создание сопровождающих документов.

Что касается стайлгайдов (хотя все это применимо и к написанию документации в целом), то они воспринимаются как лишние трудозатраты и бессмысленные дополнительные требования. Следование стайлгайдам требует дополнительных усилий и времени на изучение. Разработчики могут считать это ненужной бюрократией, особенно если они уже привыкли к своему стилю написания кода.

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

Первое – это интеграция создания текстового контента в процесс разработки: Во многих компаниях написание документации и следование стайлгайдам включено в стандартные процессы разработки (например, как обязательный этап в системе контроля версий). Таким образом, создание документации становится для разработчиков не дополнительной «повинностью», а частью повседневной работы и обязанностей.

Другое направление – это автоматизация, которая широко применяется для создания документации к IT-продуктам. Здесь предполагается использование соответствующего инструментария для автоматической генерации текстового контента и проверки соответствия стайлгайдам. Это может значительно снизить нагрузку на разработчиков. В случае автоматизации их услуги, по сути, потребуются только на уровне технической консультации и «неглубокого» редактирования.

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

1. Для Python популярным выбором является Sphinx, который позволяет создавать документы в самых разных выходных форматах. Также Sphinx интегрируется с reStructuredText. 
2. Еще для Python легковесным и простым в использовании инструментом является pdoc, который генерирует HTML-документацию из аннотаций и комментариев к коду. Он подходит для создания документации для Python-проектов.
3. Javadoc является стандартным инструментом для генерации API-документации в Java. В этом случае HTML-документы создаются из комментариев к коду, что позволяет легко документировать API и создавать подробные справочные материалы.
4. Инструмент Doxygen используется для множества языков, включая C, C++, Java и Python, и позволяет автоматически создавать документацию в различных форматах, таких как HTML, RTF и LaTeX.
5. Для создания документации для RESTful API часто применяются инструменты Swagger и OpenAPI. Swagger (теперь часть OpenAPI) позволяет генерировать документацию и предоставляет интерфейс Swagger UI для интерактивного тестирования API. 
6. Также стоит упомянуть MkDocs, который, хоть и не привязан к конкретному языку программирования, позволяет создавать красивую HTML-документацию на основе Markdown-документов. Этот инструмент совместим с системами контроля версий, такими как Git, и предлагает множество тем и шаблонов оформления текстового контента.

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

Упрощение требований: работа по шаблонам

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

Чтобы сразу «снять» эти вопросы и максимально улучшить взаимодействие с разработчиками в рамках создания документации, предоставьте им четкие и понятные шаблоны. То есть необходимо заранее показать «план ответа» на все вопросы. Шаблоны помогут упростить непривычный для разработчиков процесс документирования программного обеспечения.

Рассмотрим пример, когда разработчику может понадобиться использовать шаблон для описания функций/методов. Допустим, ваша команда разрабатывает новый модуль для управления заказами в веб-приложении. Необходимо задокументировать различные функции и методы этого модуля. При этом требуются не только писательские навыки техрайтеров, но и экспертные знания разработчиков. Последним необходимо будет выполнить следующие шаги:

1. Выбор шаблона: Разработчик выбирает шаблон для описания функций/методов из уже имеющихся в проекте шаблонов.
2. Заполнение описания:Название функции. Например, `create_order`.Описание. Краткое описание, например, «Создает новый заказ в системе».Входные параметры. Перечисление всех параметров, их типы и описания, например, `customer_id` (int, ID клиента), `products` (список продуктов).Возвращаемое значение. Тип данных и описание возвращаемого значения, например, `Order` (заказ пользователя).Пример использования. Здесь разработчик должен привести конкретный пример кода, демонстрирующий вызов функции или метода.Примечания. Разработчик описывает особенности реализации, исключения и другие важные детали. Например, разработчик может спрогнозировать возможные ошибки, сделать их подробное описание и предложить способы их устранения.
3. Использование в документации: разработчик вставляет заполненные шаблоны в общую документацию проекта. Шаблоны помогают другим членам команды или сторонним разработчикам понять, как использовать ту или иную функцию или метод.

Таким образом, использование шаблонов для описания функций и методов помогает не только стандартизировать документацию, но и улучшает её читаемость, доступность и актуальность на протяжении всего жизненного цикла проекта.

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

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

1. Во-первых, необходимо изучение требований и спецификаций. Техническому писателю нужно изучить документацию и спецификации к проекту или компоненту, для которого он создает шаблон. Это поможет понять основные функции и методы, которые требуется описать.
2. Далее следует провести анализ существующей документации. Если проект уже имеет документацию, технический писатель может проанализировать существующие шаблоны описания функций/методов (если они используются), чтобы понять требования существующего стандарта и потребности команды.
3. Третий шаг – это структурирование информации. С технической и архитектурной точек зрения технический писатель собирает информацию о функциях и методах, которые необходимо описать. 

В итоге должна получиться описанная выше структура шаблона, которая затем передаётся разработчикам:

1. Название функции/метода.
2. Краткое описание его назначения и функциональности.
3. Входные параметры: типы данных, ограничения на значения (если есть), их описание.
4. Возвращаемое значение: тип данных и краткое описание того, что возвращается.
5. Примеры использования: простые кодовые фрагменты, демонстрирующие, как использовать функцию или метод.
6. Примечания: особенности реализации, возможные ошибки или исключения.

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

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

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

Участие в процессе разработки

Чтобы научиться говорить с разработчиками на «одном языке», технический писатель должен максимально приблизиться к работе с кодом. В некоторых случаях технические писатели работают непосредственно с API, читают код и тестируют запросы. Это позволяет:

1. Глубже понять систему: вовлеченность в процесс разработки помогает лучше понять систему и оценить её возможности, чтобы затем доступно изложить эту информацию пользователям.
2. Создать точную документацию: понимание кода и логики работы системы позволяет создавать более полезные документы.
3. Быть в курсе изменений: постоянное участие в процессе разработки помогает оперативно реагировать на изменения в продукте и обновлять документацию.

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

1. Во-первых, важно само понимание техрайтером процесса тестирования. Технический писатель может участвовать в планировании тестовых сценариев и сессий, что позволяет понять, какие функции будут тестироваться и какие кейсы будут проверяться.
2. Во-вторых, большое значение имеет наблюдение за тестированием. Присутствие на тестировании позволяет техническому писателю непосредственно видеть, как тестируются функции. Это помогает взглянуть на процесс глазами пользователя и лучше понять, как продукт работает в реальной среде, какие могут возникать затруднения или вопросы у пользователей.
3. Третье – это запись вопросов и наблюдений. Технический писатель может вести своеобразную нотацию процесса, т.е. делать записи о вопросах, возникающих у тестировщиков, и о том, как разрешаются выявленные проблемы. Эта информация может быть полезна для дальнейшего улучшения документации, а также оптимизации обратной связи с пользователями.
4. Документирование тестов – это следующий этап сотрудничества технического писателя с командой разработчиков. Здесь в ответственность техрайтера входит следующее:Тестовые сценарии. Технический писатель описывает каждый тестовый сценарий, включая его цель, предварительные условия, шаги тестирования и ожидаемые результаты. Это позволяет тестировщикам четко понимать, что именно должно быть проверено.Описание методов верификации. Документация также включает описание методов, используемых для проверки функций и обеспечения их корректной работы. Это может быть, например, описание автоматизированных тестов, ручных проверок или специфических инструментов, используемых для тестирования.Примеры использования. Также важно предоставить примеры использования функций в контексте тестирования. Это помогает тестировщикам быстрее разбираться с тем, как использовать функциональность в различных сценариях.

Использование современных инструментов

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

В этом контексте техписам можно порекомендовать активно осваивать инструментарий разработчиков. Учитесь использовать современные инструменты для создания и поддержания документации.

Большое значение имеет совместная работа. Работайте вместе с аналитиками и разработчиками для получения дополнительной информации.

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

Сбор информации от разработчиков

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

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

Такие встречи и интервью должны быть тщательно подготовленными. Задавайте целенаправленные вопросы, чтобы получить максимальное количество нужной информации. Спонтанность не принесёт желаемых результатов. Скорее всего, такое интервью придётся провести заново.

И, конечно, всю информацию необходимо документировать. Записывайте все важные моменты и решения, принятые во время встреч.

Фактически интервью с аналитиков или разработчиком включает следующие важные аспекты:

1. Планирование. Готовьте список вопросов и тем для обсуждения заранее.
2. Запись. Записывайте интервью или ведите подробные заметки, чтобы не упустить важную информацию.
3. Анализ полученной информации. Анализируйте и структурируйте полученную информацию для её последующего использования в документации.

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

* * *

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