Как технические писатели документируют будущее

Александр Клименков

кандидат технических наук, Tech Lead Bercut

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

Зачем технические писатели это делают?

Для начала расскажу, зачем мы это делаем. Компания Bercut разрабатывает системы для операторов связи. Например, один из главных продуктов компании — биллинговая система IN@Voice.

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

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

Как технические писатели это делают?

Документацию на систему можно писать двумя способами:

• Последовательно — раздел за разделом, документ за документом. Это очевидный способ — писатель получает готовую систему и начинает шаг за шагом описывать её работу. Например, день за днём добавляет в документацию описание новых окон, полей, алгоритмов, таблиц базы данных, параметров API-интерфейса. В итоге сразу получается готовая документация на систему.
• Параллельно — писатель сразу формирует верхнеуровневый черновой вариант документации по системе, а затем постепенно детализирует все разделы, постоянно добавляя новую информацию.

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

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

Как у технических писателей это получается?

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

• Технический проект (техническое задание). В этом документе аналитик подробно описывает все требования к новому решению. По нему разработчики будут писать код, а тестировщики — составлять тест-кейсы. Технический писатель по этому документу понимает, как будет работать решение, какие в нём будут использоваться интерфейсы, какие изменения будут внесены в существующие системы. Этого вполне достаточно для того, чтобы начать писать документацию.
• Техническое описание. Это документ, который пишут разработчики после завершения разработки. В нём описываются особенности реализации. Иногда (но не очень часто) реализация отличается от того, что было написано в техническом проекте. Кроме того, в документе обычно изложены дополнительные технические подробности реализации. На этом этапе технический писатель уточняет и корректирует уже написанную документацию.
• Результаты функционального тестирования. Тестировщики иногда сами не догадываются, какую пользу они приносят писателям. Во-первых, они находят особенности и ограничения в работе системы, которые не были предусмотрены на предыдущих этапах. Такие особенности обязательно надо вписать в документ. Во-вторых, они подробно изучают новую функциональность и задают очень полезные вопросы аналитикам. Эти вопросы и ответы аналитиков — ценный источник информации для технического писателя. В-третьих, тестировщики подготавливают тестовую среду, которую писатели могут использовать, например, для получения «красивых» скриншотов интерфейса с реальными данными.
• Настройки интеграционного тестирования. На этапе интеграционного тестирования тестировщики проверяют, как будет работать решение в целом, как будут взаимодействовать между собой все новые версии систем. На этом этапе технические писатели вносят в документацию последние правки — завершают работу над архитектурной схемой решения, дополняют список необходимых настроек, добавляют недостающие скриншоты интерфейса и примеры настроек.

Кто проверяет документы?

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

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

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

Какие технологии используют технические писатели?

Технические писатели Bercut разрабатывают документацию с использованием технологии единого источника DITA. Я уже рассказывал об этой технологии. DITA очень помогает нам в работе — мы можем сосредоточиться на содержании и структуре документации и не задумываться над её оформлением. Когда требуется получить PDF-документ, мы собираем его с помощью набора готовых XSLT-преобразований.

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

Какие есть правила у технических писателей?

Приведу несколько негласных правил, которые соблюдают технические писатели Bercut при разработке документации:

1. Постоянная промежуточная готовность документа к сборке. Мы всегда можем собрать черновик документа на любом этапе работы. Это может понадобиться, чтобы отправить его на проверку разработчику или тестировщику.
2. Комментирование всех важных изменений. Мы всегда комментируем все существенные изменения в документах, которые выполняем по результатам проверки или общения с участниками разработки системы. Это позволяет нам найти источники той или иной фразы, которой не было в исходных документах.
3. Постоянное уточнение описания. Мы всегда стараемся как можно раньше добавлять в документацию известные особенности новой системы. Например, если в интерфейс системы добавляется новое окно, мы заранее описываем его поля. В дальнейшем, по окончании разработки, мы сможем добавить снимок этого окна и при необходимости откорректировать названия и описание полей. Исправить всегда легче, чем написать заново.
4. Обратная связь с разработчиками и тестировщиками. Если мы видим, что в системе реализовано не так, как было задумано, мы обязательно советуемся с разработчиками и тестировщиками. Тут есть два варианта — либо это обоснованное изменение логики реализации, либо ошибка. Если это второй вариант, то мы помогаем тестировщикам.
5. Опора на источники. Мы никогда ничего не придумываем сами, не додумываем логику, не изобретаем особенности реализации. Всё, что содержится в документации, должно иметь свой источник — исходный документ, письмо или сообщение от кого-то из участников разработки. Если нам что-то непонятно, мы обязательно задаём уточняющие вопросы. Это позволяет нам избежать ошибок в описании системы.

Вот так мы, по сути, документируем будущее — создаём описание системы параллельно с её проектированием, разработкой и тестированием. Такая методика разработки документации позволяет нам не только сократить time-to-market всего решения, но и уменьшить количество ошибок в документации за счёт постоянного тесного взаимодействия с отделами разработки и тестирования.

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

P.S.: Как раз сейчас мы ищем в нашу команду опытных писателей. Присоединяйтесь, у нас будет очень интересно!