Вам кажется, что с вашей документацией что-то не так? Вам не кажется

Меня зовут Семён Факторович, с 2012 года я занимаюсь технической документацией. Последние три года я руковожу собственным агентством documentat.io, помогая российским IT-компаниям создавать качественную документацию.

Мы пишем документацию с нуля (руководства пользователя, справочники API, архитектурную документацию) и поддерживаем уже имеющуюся и проводим консультации по настройке документационных процессов. И почти каждый запрос от наших клиентов начинается с признания: «Кажется, с нашей документацией что-то не так».

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

1) Документация полностью отсутствует.
2) Документацию неохотно пишут.
3) Документацию неохотно читают.
4) Документация есть, ее пишут и читают, но она кажется бесполезной.

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

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

Что такое документация?

Для начала давайте определимся, что мы считаем технической документацией, а что не считаем. Традиционно мы не считаем технической документацией:

• Лицензионные соглашения (EULA), которые мы никогда не читаем при установке софта.
  
• Маркетинговые тексты, описывающие преимущества и функциональность продукта/сервиса на сайте или в магазине приложений.
  
• Тексты в интерфейсе — надписи на кнопках, тексты диалоговых окон и пр.
  

А документацией все чаще всего считают:

• Требования в том или ином виде, например, техзадания или спецификации требований (SRS).
  
• Описание архитектуры программных решений.
  
• Документацию API.
  
• Инструкции по установке или развертыванию.
  
• Руководства пользователя.
  
• README.md к компонентам или библиотекам, которые будут использовать ваши коллеги, соседние команды или другие компании.
  

А теперь давайте зададимся философским вопросом: что такое вообще документация? Для чего она нужна? За сложными вопросами в нашей индустрии лучше идти в серьезные источники, и, как ни странно, очень много о документации можно прочитать в Project Management Body of Knowledge (PMBOK). В главе «Управление коммуникациями» говорится примерно следующее:

Внутри и снаружи проектной команды есть ее значимые участники — стейкхолдеры. Между ними существуют каналы коммуникации.

Если говорить о разработке, то примерная картина стейкхолдеров может выглядеть так:

На картинке также отмечены возможные каналы коммуникации между стейкхолдерами, которые (конкретно в этом случае, так совпало!) реализуются с помощью разных видов технической документации.

• Бизнес-аналитик и системный аналитик согласуют с заказчиком высокоуровневые требования к системе, фиксируя их в документе, который чаще всего называется техническим заданием.
  
• Системный аналитик детализирует техзадание, формируя из него более конкретные постановки задачи разработчику и создавая спецификацию требований (SRS).
  
• Разработчик пишет документацию по API для его пользователя.
  
• Онбординг нового разработчика в команду вполне может включать в себя изучение архитектурного документа на систему.
  
• Техподдержка, консультирующая пользователя, предложит ему прочитать пользовательскую документацию.
  

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

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

• В одной из компаний, где я работал, инструментом архитектурного онбординга были видеозаписи. То есть одному новому сотруднику был проведен онбординг прямо у доски, нарисована архитектура системы и рассказаны ее основные принципы. Это было ловко записано на видео, и всем следующим сотрудникам выдавали эту двухчасовую видеозапись. Безусловно, это способ реализации коммуникации с новым сотрудником. Можно ли это считать документацией — скользкий вопрос, но, наверное, да.
  
• Подслушанный рассказ в кулуарах конференции: «Документация на API у нас хранится в виде пяти телеграм-сообщений, старательно пересылаемых между сотрудниками».
  
• В другой компании люди, занимающиеся DevOps, описывают сетевую инфраструктуру голосовыми сообщениями в WhatsApp. Сообщений этих накопилось уже достаточно много, и только если прослушать их все, то сложится полная картина. Когда новый руководитель этого направления, осознал это, то решил собрать их воедино, но оформить их не текстом (например, статьей во внутренней вики), а подкастом.
  

Кажется, что документацией стоит считать некоторый твердый (текстовый) вариант реализации коммуникации между двумя конкретными стейкхолдерами, который лежит в одном месте, чтобы к нему можно было неоднократно возвращаться. Но такая «твердо-текстовая» коммуникация очень дорогая:

• Ее нужно написать, а это — немалые инвестиции времени;
  
• Ее нужно поддерживать, потому что она быстро устаревает, становясь чуть менее актуальной с каждым коммитом в кодовую базу.
  
• Она должна быть дешевле устного общения — и только в этом случае она «взлетит».
  

Очевидно, что в этих условиях документация создается, только когда другие способы коммуникации обойдутся еще дороже. Например, команда в едином порыве поймет, что если мы онбордим 10 новых людей в месяц, то каждый раз проговаривать одно и то же в Slack слишком накладно — давайте уже наконец напишем на эту тему несколько статей в вики (ну или запишем видео и обзовем его документацией).

С учетом этого вернемся теперь к списку проблем из первого абзаца статьи.

Проблема №1: документация отсутствует

Вы чувствуете, что у вас нет документации. Это классное осознание, которое требует очень серьезной рефлексии и осмысления. Возможно, с каким-то фасилитатором (например, с представителем нашей компании), который будет задавать правильные вопросы и подталкивать вас к правильным ответам.

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

1. Осознайте, что документации нет.
   
2. Нарисуйте то, чего нет: карту стейкхолдеров и недостающие каналы коммуникаций между ними.
   

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

Проблема №2: документацию неохотно пишут

Документация частично есть, но новую не пишут. Обычно жалобы на это мы слышим такие:

• Архитектура новых фич не документируется: наши разработчики не очень любят документировать свои дизайн-решения. Они сделали что-то, но не описали, почему и как это сделали. Информация, конечно, не потеряна (она есть в коде и в головах разработчиков), но ее сложно извлечь.
  
• Изменения в требованиях не фиксируются: мы на старте проекта написали красивое техзадание или спецификацию требований, но требования с тех пор поменялись на 50%, и это нигде не зафиксировано.
  
• Руководство пользователя безнадежно устарело: оно отражает состояние продукта пятилетней давности. Его когда-то написали, и оно было классным, но сейчас устарело, потому что мы никак не можем собраться, чтобы его обновить.
  

Это частые и весьма ощутимые проблемы, но с одной оговоркой: они не только неестественные, но довольно странные.

Представьте, что в параллельной вселенной команда разработки жалуется на совершенно неуправляемые истории: «мы пофиксили баг, но забыли выкатить этот фикс на прод», «новые фичи почему-то не тестируются» или «иногда мы не забываем делать code review».

В нашей вселенной, конечно же, всё не так. У нас с деплоем, тестированием и code review полный порядок, потому что всё это является частью принципиальных активностей разработки — и активности эти обернуты в процессы. Есть люди, которые следят за тем, чтобы эти процессы были исполнены. В самых простых терминах — вы не передвинете карточку на kanban-доске или в Jira в состояние «done», пока она не пройдет состояния «тестирование» или «in review».

Есть ли у вас процессы вокруг документации?

Задайте себе этот вопрос. Он сложный, потому что мы очень слабо представляем, что такое «процессы вокруг документации». Но этот вопрос можно декомпозировать на два более простых:

1. В каких точках других процессов вы пишете или обновляете документацию? То есть, понимаете ли вы, в какой момент разработки, развития фичи нужно сесть и написать (или обновить) документацию, и какую именно документацию?
   
2. Каков жизненный цикл каждого вашего документа? У вашего технического документа (например, описания фичи или руководства пользователя) вообще есть какой-то жизненный цикл? Есть ли ситуации, когда вы его обновляете? Понимаете ли вы, что сейчас его нужно обновить, или всё и так хорошо?
   

Это хорошие вопросы для саморефлексии, и они, скорее всего, вас приведут (или должны привести) к тому, что технический документ — это проектный артефакт. Точно также как код, release notes, новые фичи и весь продукт. А проектный артефакт должен содержать:

• Постановку задачи на его создание. Вы должны четко поставить задачу: «Создайте мне артефакт с такими-то свойствами». Какие свойства должны быть у вашей документации?
  
• Жизненный цикл. У артефакта должен быть жизненный цикл, потому что он делается не единожды, а развивается. Как выглядит жизненный цикл каждого технического документа у вас?
  
• Критерии качества, definitions of done. Когда мы считаем руководство пользователя завершенным? Как мы определяем, качественное ли оно или нет?
  

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

Шаблоны и примеры документов

Тем не менее с definitions of done в документации традиционно сложно, а еще сложнее — с критериями качества. Очень мало компаний умеет объективно и хорошо измерить, качественная у них техническая документация или нет. То же самое происходит и с постановкой задачи: «Давайте опишем архитектуру нового компонента. Но такое «описание архитектуры», как его писать и как определить, что оно написано хорошо — непонятно.

Для таких ситуаций есть очень хороший инструмент — шаблоны, а лучше даже примеры готовых документов, которые заведены в команде (и вы знаете, как они выглядят):

• «Описание архитектуры новой фичи мы делаем по этому шаблону».
  
• «Типовая глава руководства пользователя» — если вы хотите написать главу на новую фичу, просто берите эту главу как пример.
  
• «Образцовый туториал к API» — когда вы делаете новый API, не забывайте не только покрыть его Сваггером, но и написать к нему руководство: как этим API пользоваться, почему этот API такой и что с его помощью можно достичь. По образу и подобию этого документа можно будет писать дальше.
  

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

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

Примеры и шаблоны документации — лучший способ борьбы с документационной прокрастинацией. Как и настроенные процессы работы с документацией.

Проблема №3: документацию неохотно читают

Мы победили прокрастинацию, написали документацию, но ее никто не читает — и это очень обидно для автора этой документации! Но давайте признаемся: чтение документации — не бесплатный процесс: извлечение информации из документации имеет стоимость, поиск документации — тоже. Читать документацию (и вообще читать что-либо) — это тяжело.

Если вы поищете что-то в огромном корпоративном Confluence на 20 тысяч страниц и получите 300 результатов на ваш поисковый запрос, то, скорее всего, вы начнете грустить. Потому что понимаете, что релевантность этих страниц непонятна, а вам нужно прочитать, как минимум, первые 2 страницы выдачи, пролистав каждый из этих документов. При этом нет гарантии, что вы найдете то, что ищете. И, скорее всего, вы закроете Confluence и пойдете за информацией к коллеге.

То же самое происходит, когда вам нужно прошерстить 200-страничный PDF, чтобы найти там ответ на небольшой вопрос. С большой вероятностью вы через пять минут закроете документ и напишете кому-то в Slack.

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

Сделайте чтение дешевым

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

Самое первое, о чем стоит задуматься — это единый документационный портал со стройной структурой. Ваша документация не должна быть рассредоточена по Google Docs, Confluence, Dropbox и переписке. Пусть она лежит в едином месте, например, в Confluence, где есть единая стройная структура разделов и подразделов, соответствующая декомпозиции вашей предметной области. Человек, зашедший туда, будет знать: скорее всего, он найдет то, что ищет, и структура ему в этом поможет.

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

Найдите корпоративного «библиотекаря»

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

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

Проблема №4: документация неполна, неточна, неактуальна

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

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

Кому?

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

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

Что читатель уже знает о предметной области? Он знает, о чем ваш продукт, каковы в нем бизнес-процессы? Или, может, это нужно объяснить? Или есть читатели вашего документа, которые это знают, и есть те, что не знают? Вам нужно писать документацию с учетом этого.

А чего он не знает? Есть ли вещи, которые обязательно нужно объяснить? Или, может быть, есть то, что объяснять не надо? И не стоит тратить время, документируя API, на объяснение читателю, что такое HTTP или каковы принципы REST? А иногда, возможно, такие вещи объяснять нужно?

Зачем?

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

Какая проблема стоит перед читателем? Зачем принимающая сторона вообще нас слушает? Что ей нужно от этого акта коммуникации? В нашем примере про API — что читатели API хотят узнать про API? Структуру методов или свойства каждого метода? Или, может быть, читателю это пока не интересно, но он хочет узнать бизнес-назначение API, что он этим API может сделать? Или он хочет узнать, как реализовывать типовые сценарии, которые ожидает от вашего продукта? И вообще, можно ли те сценарии, которые он хочет, с помощью вашего API реализовать? Совершенно не факт, что типовой справочник методов на эти вопросы ему ответит. Наверное, нужно написать какие-то вводные статьи или туториал.

Кто же нам поможет?

Фронт работ наведения порядка в документации большой:

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

Кто-то должен вам ответить на все эти вопросы. Хорошие новости: на рынке есть люди, которые по определению занимаются именно этими активностями! Это технические писатели.

Технический писатель

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

В нашем опыте очень много компаний говорят: «Мы понимаем, что нам нужен технический писатель, но нанимать его не будем. Потому что он не знает, что именно писать — он же не программист. Он будет просто секретарём, который ходит за нашими разработчиками и пишет за ними слово в слово то, что они говорят. Зачем? Мы уж тогда сами лучше напишем».

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

Но при этом у техписателя действительно есть режим «не писать всё самому». Техписатель может:

• Создать шаблоны и гайдлайны — и отойти в сторону, а дальше будут писать ваши разработчики.
  
• Редактировать и корректировать существующие документы, чтобы, написанное разработчиками читалось легко и не содержало ошибок.
  
• Заниматься «гострайтингом». — создавать полноценный документ по очень нечетким наброскам разработчика на салфетке или на вайтборде (возможно, предварительно собрав дополнительную информацию в устном общении).
  

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

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

Техписатель в итоге может вырасти в knowledge-менеджера— поотому что процесс управления документацией — это неотъемлемая часть, прямое подмножество процесса управления знаниями.

И, конечно, вы можете нанять внешних консультантов, например, у нас в documentat.io. Мы настраивали такие вещи уже не в одной компании и поможем вам с настройкой процессов, выработкой шаблонов, гайдлайнов и наведением порядка в вашей базе знаний. Или просто отдайте нам часть ваших задач по написанию документации в формате аутсорс/аутстафф.

Подытожим

• Документация — это способ коммуникации проектных стейкхолдеров. Они, конечно, могут переписываться в Slack или обмениваться голосовыми сообщениями в WhatsApp, но лучше сделать то же самое через документацию.
  
• Относитесь к документации как к процессу и как к артефакту. Если вы относитесь к документации иначе, вы к ней не относитесь никак, она у вас не создастся сама. Если нет четких требований к проектным артефактам и процессам вокруг них, вы не получите ничего определенного на выходе.
  
• Прокрастинация мешает читать и писать документацию. Снижайте барьеры на чтение и создание документации, уничтожайте документационную прокрастинацию. Если документацию сложно читать, ее не будут читать. Если ее сложно писать и непонятно, куда выкладывать, ее писать не будут.
  
• Наймите или вырастите корпоративного библиотекаря — человека, у которого болит душа за документацию, и кто поможет навести в ней порядок.
  

Если вы уже задумались, что же с вашей документацией не так — вы в начале пути, который обязательно завершится успешно, и с вашей документацией всё обязательно будет хорошо!

Видео моего выступления на Knowledge Conf 2020:

Конференция Knowledge Conf 2022 пройдет 21-22 марта в Москве. Будем говорить об адаптации сотрудников, сохранении знаний внутри компании и личном менторстве. Всё будет на одной площадке с конференцией TeamLead Conf Foundation 2022. Расписание и тезисы докладов уже готовы.

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