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

Фундаментально цикл разработки продукта состоит из следующих шагов:



После добавления документации картина может измениться так:



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

• Модель «Переброс через стену»
  
  • Достоинства
  • Недостатки
• Модель «Тушим ближайший пожар»
  
  • Достоинства
  • Недостатки
• Модель «Я с командой»
  
  • Достоинства
  • Недостатки
• Какая же модель лучше?

Модель «Переброс через стену»

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

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

▍ Достоинства

Преимущества такого подхода в основном касаются организации:

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

▍ Недостатки

Недостатки этой модели отчасти заключаются в пользовательском опыте:

• Не всегда возможно улучшить или изменить продукт в ответ на отзыв отдела документации, поскольку разработка уже завершена. В лучшем случае писатель может сообщить о багах для последующего исправления, если их подтвердят пользователи.
• Несогласованное описание функциональности в документации, потому что в запрос на документирование попадают только те элементы, которые «перебросили через стену». Это ведёт к несоответствию содержания, когда документация в некоторых моментах может не совпадать с продуктом или упускать описание важных функций.
• Задержки между запуском функциональности и публикацией соответствующей документации. В зависимости от того, когда функциональность запускается, могут возникать задержки между этим моментом и публикацией документации. Если такое произойдёт, клиент может не узнать о новой функции или, узнав о ней, не найти вспомогательную документацию на случай затруднений, что вынудит его писать в поддержку. В конечном итоге это зачастую приведёт к недовольству со стороны клиентов.

И несколько пунктов для организации и её технических писателей:

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

Модель «Тушим ближайший пожар»

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

▍ Достоинства

Преимущества этой модели в первую очередь касаются организации:

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

▍ Недостатки

Недостатки наблюдаются как со стороны потребителей, так и со стороны организации:

• Документация пишется с акцентом на функциональности, а не на задачах пользователя. Поскольку писатель не обладает достаточным пониманием того, что из себя представляет проект, зачем он и для кого предназначен, у вас может получиться документация с акцентом на функциональности, описывающая, что было создано, а не то, чего с помощью этого можно добиться.
• Сложно оценить объём работы по документированию из-за накладывающихся друг на друга проектов, а также непредсказуемого влияния постоянной смены контекста. В этом случае больше времени уходит на изменение приоритетов, чем на фактическое написание документации, и писатели быстро перегружаются.
• Для успеха необходима согласованность процессов по всей организации. Если команды проекта не используют в работе одни и те же (или по меньшей мере отчётливо прописанные) методы, то процесс переключения на новый проект или команду может оказываться трудным и медленным, частично поглощая преимущества от самой этой возможности.

Модель «Я с командой»

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

▍ Достоинства

Преимущества такого подхода в основном касаются клиента:

• Документация акцентируется на пользователе, а не на функциональности. Если вы знаете, что создаётся, почему и для кого, будет намного проще написать документацию, ориентированную на задачи пользователя, а не на то, что было создано, и как оно работает.
• Более высокая согласованность в тексте продукта и его повышенное качество. Так как писатель подключён к процессу разработки и дизайна, он может помогать в составлении его текстовых элементов – будь то текст UI или спецификация API.
• Ускоренная разработка контента. Располагая всем контекстом о происходящем и с минимальным переключением между проектами (либо вообще без него), писатель может составлять документацию очень быстро и без лишних задержек до и после завершения разработки/тестирования.

▍ Недостатки

Недостатки в этом случае в основном касаются организации:

• Может потребоваться много ресурсов. Зачастую оказывается излишне затратным загружать писателя вровень с командой разработки, поскольку не все проекты, над которыми трудятся инженеры, требуют документации. Естественно, если они работают над техническим долгом, писатель также может потратить время на ликвидацию долга по документированию или профессиональный рост, но такой роскоши в управлении персоналом я лично не встречал. В зависимости от темпов разработки, оптимальное отношение участия писателя к работе команд должно составлять 1:3, и это всё равно будет больше, чем в других моделях.
• Писатели могут тратить силы впустую и ошибаться, если начинают составлять черновики до того, как продукт будет «достаточно» готов. Если вы документируете каждую итерацию потока разработки функциональности до её завершения, то можете переписывать одну и ту же процедуру по нескольку раз. Иногда такие черновики позволяют повысить эффективность и более сжато объяснить что-либо, но здесь также присутствует риск, что у писателя выработается неверное понимание, и описание процедуры получится недостаточно точным.
• Могут возникать неожиданные сложности. Если каждого писателя подключать к команде разработки, то возникает вероятность, что в случае отпуска или увольнения, никто другой не будет обладать достаточным контекстом для его полноценной замены.
• Писатели могут оказываться изолированы в рамках одного проекта, лишаясь возможности наблюдать происходящее в других проектах компании. Из-за того, что в этой модели составители документации больше времени проводят с командами разработки, чем со своей собственной, этот подход требует дополнительных усилий для поддержания связности внутри команды по документированию и согласованности между используемыми разными писателями стилями документирования.

Какая же модель лучше?

Всё зависит от ваших приоритетов и обстоятельств.

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

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

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

Узнавайте о новых акциях и промокодах первыми из нашего Telegram-канала ????