Процесс разработки документации#
Этапы процесса:
Сбор информации: Поиск и определение доступных источников информации. Кто ими может стать: разработчики, инженеры, тестировщики или руководитель проекта?
Пользователи документации: Определить аудиторию документации (пользователи продукта, разработчики, администраторы и т.д).
Планирование и структурирование: Какие разделы и подразделы будут включены? Какие темы будут рассмотрены в каждом разделе? Сколько времени уйдет на разработку первой версии документа, финальной?
Создание контента: разработка документа, интервью, согласование.
Редактирование и ревизия: Проверка текста заинтересованными лицами, корректировка по результатам, подготовка финальной версии.
Актуализация документации: Этот этап представляет собой непрерывный итеративный процесс поддержания актуальности и соответствия документации текущим требованиям и изменениям.
Сбор информации#
Пользователи документации#
Планирование и структурирование#
Создание контента#
Редактирование и ревизия#
Актуализация документации#
Этот этап представляет собой непрерывный итеративный процесс поддержания актуальности и соответствия документации текущим требованиям и изменениям. Он включает в себя следующие шаги:
Мониторинг изменений: Ключевым аспектом актуализации документации является постоянный мониторинг изменений в продукте, технологии или проекте. Как технический писатель может отследить такие изменения?
Читайте release notes и changelog продукта.
Получайте обратную связь от пользователей.
Следите за текущими задачами в Jira.
Читайте базу знаний по продукту.
Больше общайтесь с командой, т. к разработчики, аналитики и тестировщики продукта – основные поставщики информации об изменениях, которые следует включить в документацию.
Оценка важности: Не бросайтесь поправить всю документацию сразу! Не все изменения требуют немедленной актуализации документации. На этом этапе необходимо оценить важность и влияние изменений на пользователей и разработчиков. Это позволит определить приоритеты и ресурсы, которые следует выделить на актуализацию.
Планирование актуализации: Всегда планируйте свое время! Определение временных рамок и объема актуализации для конкретных разделов документации. Планирование включает в себя решение, когда и какие изменения будут внесены в документацию. Также можно определить, как часто будут проводиться актуализации и как они будут интегрированы в рабочий процесс. Хорошая практика работы: закладывать время технического писателя в задачу на разработку.
Обновление контента: На этом этапе происходит фактическое внесение изменений в документацию. Технические писатели и команда разработки должны быть вместе, иначе документация получится не полной.
Обратная связь и проверка: После внесения изменений следует предоставить возможность заинтересованным сторонам (пользователям, разработчикам и другим) ознакомиться с актуализированной документацией и предоставить обратную связь. Это позволит выявить дополнительные корректировки и убедиться, что актуализация соответствует ожиданиям аудитории. Помните! Чем больше человек прочитают вашу документацию и оставят свои замечания, тем более понятной она станет. Что касается стилистических правок, тут последнее слово за техническим писателем, считаете, что так писать правильнее, смело отстаиваете свою точку зрения.
Документирование изменений: Каждая актуализация должна быть документирована, чтобы пользователи и члены команды могли отследить, какие изменения были внесены, когда и по какой причине. Это также облегчит последующие аудиты и рецензии.
Процесс актуализации документации один из основных этапов в разработке документации, который обеспечивает пользователей актуальной и точной информацией о продукте или проекте. Регулярная актуализация позволяет избегать путаницы, улучшает опыт пользователей и способствует более эффективному взаимодействию между участниками проекта.
Интеграция процесса документирования с разработкой документации#
В рамках работы над проектом могут быть настроены определенные процессы в системе управления задачами (таск трекере). Эти процессы охватывают различные этапы разработки ПО и технической документации, начиная от выявления требований к ПО и до готовности к релизу. Каждая задача проходит через ряд этапов, отражающих ее текущий статус и прогресс выполнения.
Например, процесс может включать следующие этапы:
Выявление требований: Требования к продукту оформляются в виде задачи. Задача может быть описана кратко, определены приоритеты и ассоциированы с определенным разработчиками (от него вы будете получать актуальную информацию для документации и в первую очередь для Технического задания).
Разработка: Процесс разработки начинается. Разработчики приступают к созданию кода, функциональности или дизайна в соответствии с поставленной задачей. На этом этапе основная информация формируется в Базе знаний.
Тестирование: Завершив разработку, задача передается на тестирование. Команда тестировщиков выполняет проверку задачи на наличие ошибок и соответствие заданным требованиям(тестировщики основные поставщики информации для документа “Программа и методика испытаний”).
Разработка документации: По результатам тестирования задачи, если она успешно прошла проверку, создается документация (более подробное описание этого этапа представлено выше).
Релиз: После успешной разработки, тестирования и документирования, задача считается готовой к включению в следующий релиз продукта.
Важно отметить, что в случае, если один из этапов не завершен или не соответствует ожиданиям, задача не переходит к следующему этапу. Это позволяет обеспечить высокое качество продукта и своевременный выпуск релизов. В реальности, конечно, возможны различные сценарии и исключения, но идея заключается в том, чтобы иметь четкую структуру и процессы, которые обеспечивают прозрачность и эффективность работы над задачами.