Меня зовут Семён Факторович, с 2012 года я занимаюсь технической документацией. Последние три года я руковожу собственным агентством documentat.io, помогая российским IT-компаниям создавать качественную документацию. Мы пишем документацию с нуля (руководства пользователя, справочники API, архитектурную документацию) и поддерживаем уже имеющуюся и проводим консультации по настройке документационных процессов. И почти каждый запрос от наших клиентов начинается с признания: «Кажется, с нашей документацией что-то не так». Когда мы начинаем углубляться, разбираясь, что с ней не так, то очень часто причины довольно одинаковы и повторяются от компании к компании. Если свести их в один список и отсортировать по частоте озвучивания, то получится такой хит-парад проблем: 1) Документация полностью отсутствует.
2) Документацию неохотно пишут.
3) Документацию неохотно читают.
4) Документация есть, ее пишут и читают, но она кажется бесполезной. Последний пункт требует уточнения: чаще всего за словом «бесполезна» кроется ощущение, что документация не очень хорошо выполняет свою задачу. Потому что она либо не полна, то есть описывает не все аспекты, которые хотелось бы в ней найти. Либо не точна, то есть то, что в ней написано, не полностью соответствует истине. Либо не актуальна, то есть соответствовала истине в прошлом, а сейчас программная система или внешний мир изменились, и документация перестала этому соответствовать. Эти проблемы я и хочу сегодня обсудить: посмотрим их симптомы и как их интерпретировать, а самое главное — что с ними делать. Предлагаю вам некую методичку по самодиагностике и самолечению проблем с вашей документацией. Всё, приведенное ниже, опробовано на нескольких десятках IT-компаний. Для начала давайте определимся, что мы считаем технической документацией, а что не считаем. Традиционно мы не считаем технической документацией: А документацией все чаще всего считают: А теперь давайте зададимся философским вопросом: что такое вообще документация? Для чего она нужна? За сложными вопросами в нашей индустрии лучше идти в серьезные источники, и, как ни странно, очень много о документации можно прочитать в Project Management Body of Knowledge (PMBOK). В главе «Управление коммуникациями» говорится примерно следующее: Если говорить о разработке, то примерная картина стейкхолдеров может выглядеть так:  На картинке также отмечены возможные каналы коммуникации между стейкхолдерами, которые (конкретно в этом случае, так совпало!) реализуются с помощью разных видов технической документации. То есть техническую документацию стоит рассматривать как способ реализации канала коммуникации между проектными стейкхолдерами. Но это не единственно возможный способ коммуникации между ними. Например, заказчик может общаться с бизнес-аналитиком голосом, онбординг тоже можно проводить в устном виде (что в большинстве случаев и происходит):  На деле есть и множество других способов, например: письма, переписка в мессенджерах, телефонные звонки. Три совершенно реальных истории из моей практики: Кажется, что документацией стоит считать некоторый твердый (текстовый) вариант реализации коммуникации между двумя конкретными стейкхолдерами, который лежит в одном месте, чтобы к нему можно было неоднократно возвращаться. Но такая «твердо-текстовая» коммуникация очень дорогая: Очевидно, что в этих условиях документация создается, только когда другие способы коммуникации обойдутся еще дороже. Например, команда в едином порыве поймет, что если мы онбордим 10 новых людей в месяц, то каждый раз проговаривать одно и то же в Slack слишком накладно — давайте уже наконец напишем на эту тему несколько статей в вики (ну или запишем видео и обзовем его документацией). С учетом этого вернемся теперь к списку проблем из первого абзаца статьи. Вы чувствуете, что у вас нет документации. Это классное осознание, которое требует очень серьезной рефлексии и осмысления. Возможно, с каким-то фасилитатором (например, с представителем нашей компании), который будет задавать правильные вопросы и подталкивать вас к правильным ответам.  Чаще всего отсутствие документации значит, что какие-то, абсолютно конкретные, стейкхолдеры не связаны каналом коммуникации. Или этот канал коммуникации устный, в Slack, через голосовые сообщения. Если вы еще не можете сформулировать, какой именно документации нет, и не можете понять, что с этим делать, то мой совет будет совершенно «дзенским»: Это довольно простое упражнение, не требующее нескольких дней работы. Но, нарисовав такую карту коммуникаций, вы многое поймете о том, как можно улучшить ситуацию с коммуникациями и документацией в вашем проекте. Документация частично есть, но новую не пишут. Обычно жалобы на это мы слышим такие:  Это частые и весьма ощутимые проблемы, но с одной оговоркой: они не только неестественные, но довольно странные. В нашей вселенной, конечно же, всё не так. У нас с деплоем, тестированием и code review полный порядок, потому что всё это является частью принципиальных активностей разработки — и активности эти обернуты в процессы. Есть люди, которые следят за тем, чтобы эти процессы были исполнены. В самых простых терминах — вы не передвинете карточку на kanban-доске или в Jira в состояние «done», пока она не пройдет состояния «тестирование» или «in review». Задайте себе этот вопрос. Он сложный, потому что мы очень слабо представляем, что такое «процессы вокруг документации». Но этот вопрос можно декомпозировать на два более простых: Это хорошие вопросы для саморефлексии, и они, скорее всего, вас приведут (или должны привести) к тому, что технический документ — это проектный артефакт. Точно также как код, release notes, новые фичи и весь продукт. А проектный артефакт должен содержать: Умение задавать эти вопросы, отвечая на них, и означает, что вы относитесь к вашей документации, как к проектному артефакту. Тем не менее с definitions of done в документации традиционно сложно, а еще сложнее — с критериями качества. Очень мало компаний умеет объективно и хорошо измерить, качественная у них техническая документация или нет. То же самое происходит и с постановкой задачи: «Давайте опишем архитектуру нового компонента. Но такое «описание архитектуры», как его писать и как определить, что оно написано хорошо — непонятно. Для таких ситуаций есть очень хороший инструмент — шаблоны, а лучше даже примеры готовых документов, которые заведены в команде (и вы знаете, как они выглядят): Созданные гайдлайны, шаблоны и примеры документов значительно снимают проблему чистого листа, которой обычно подвержены все люди, создающие документацию. Эта проблема есть не только у технических писателей, но и у художественных писателей и инженеров, которые самостоятельно документируют то, что они делают. Менеджер ставит задачу описать архитектуру нового компонента, а мы открываем новый чистый документ и не знаем, с чего начать. Это большая проблема, потому что подсознательно у нас формируется достаточно высокий барьер входа в эту активность. Что, в свою очередь, рождает прокрастинацию: «Я не знаю, как начать эту задачу, поэтому отложу ее на завтра или на послезавтра, или на послепослезавтра, когда я сделаю все другие задачи в проекте». То есть никогда. И прокрастинация, скорее всего, и есть та самая причина, почему документация у вас не пишется. Лучший способ с ней бороться — привести примеры и шаблоны готовой документации и не забыть обернуть это всё в процессы.  Мы победили прокрастинацию, написали документацию, но ее никто не читает — и это очень обидно для автора этой документации! Но давайте признаемся: чтение документации — не бесплатный процесс: извлечение информации из документации имеет стоимость, поиск документации — тоже. Читать документацию (и вообще читать что-либо) — это тяжело.  Если вы поищете что-то в огромном корпоративном Confluence на 20 тысяч страниц и получите 300 результатов на ваш поисковый запрос, то, скорее всего, вы начнете грустить. Потому что понимаете, что релевантность этих страниц непонятна, а вам нужно прочитать, как минимум, первые 2 страницы выдачи, пролистав каждый из этих документов. При этом нет гарантии, что вы найдете то, что ищете. И, скорее всего, вы закроете Confluence и пойдете за информацией к коллеге. То же самое происходит, когда вам нужно прошерстить 200-страничный PDF, чтобы найти там ответ на небольшой вопрос. С большой вероятностью вы через пять минут закроете документ и напишете кому-то в Slack. Проектная коммуникация всегда идет по пути наименьшего сопротивления и наименьшей энергии. Если вашу документацию сложно читать — люди реализуют каналы коммуникации другим способом. Сделайте так, чтобы документацию было если не приятно, то хотя бы дешево читать. Самое первое, о чем стоит задуматься — это единый документационный портал со стройной структурой. Ваша документация не должна быть рассредоточена по Google Docs, Confluence, Dropbox и переписке. Пусть она лежит в едином месте, например, в Confluence, где есть единая стройная структура разделов и подразделов, соответствующая декомпозиции вашей предметной области. Человек, зашедший туда, будет знать: скорее всего, он найдет то, что ищет, и структура ему в этом поможет. Во вторых, вам поможет хорошо структурированный текст, а также грамотный и ясный язык. Грамотно изложенная информация с хорошей структурой сподвигнут людей дочитать документ до конца. Простыни текста с без разбиения на главы или даже на абзацы, с орфографическими ошибками и трехэтажным канцеляритом, скорее всего, бросят читать где-то посередине и пойдут узнавать информацию устно. Снижению стоимости чтения может поспособствовать особая проектная роль. Мы у себя ее называем «корпоративным библиотекарем». Это некоторый владелец документации, но не в смысле, что он ее всю написал или прочитал. Нет, он просто знает общую карту всей документации, которая есть в проекте и где она лежит. Точно так же, как библиотекарь в обычной библиотеке вряд ли сам прочитал все находящиеся в ней книги, но может подсказать в какой книге (или хотя бы на какой полке) найти то, что вам нужно. Следя за порядком в Confluence, он может переструктурировать структуру сообразно предметной области проекта, отсекая старые и устаревшие статьи и напоминая автору статьи пятилетней давности вовремя ее обновить. Библиотекарь также может подсказать автору нового документа, куда его положить. Это очень важно, потому что тем самым он может снижать стоимость написания документов, подсказывая разработчикам, к какому разделу относится то, что они написали, и тем самым снижая барьер входа в написание документации. Библиотекарю можно просто можно отправить статью, и он сам ее выложит куда нужно. Эта проблема волшебным образом сводится к предыдущим трем. Если вы забываете обновлять документацию — значит, вы не учли это в процессах разработки. Если документация не полна или не точна, то, наверное, вы не очень хорошо проверяете ее качество или не очень четко ставите задачу.  Нужно хорошо подумать о том, как выглядят ваши процессы разработки документации и ее поддержки. Но прежде чем вы начнете их формировать, задайте себе два вопроса: кому мы пишем и зачем? Первым вопросом при написании любого технического документа будет: кто принимающий стейкхолдер в этом канале коммуникации? Кому мы хотим что-то рассказать? А дальше этот вопрос распадается на много вопросов, и самые важные из них следующие. Вы уверены, что на той стороне один стейкхолдер? Может быть, их несколько, и они разные? Если вам кажется, что вы пишете документацию для разработчиков (например, для пользователей вашего API), то, скорее всего, выяснится, что пользователей API несколько видов, и документация должна быть написана для каждого вида. Отличаться они могут, например, по уровню знакомства с вашей предметной областью или по уровню своего профессионального опыта. Что читатель уже знает о предметной области? Он знает, о чем ваш продукт, каковы в нем бизнес-процессы? Или, может, это нужно объяснить? Или есть читатели вашего документа, которые это знают, и есть те, что не знают? Вам нужно писать документацию с учетом этого. А чего он не знает? Есть ли вещи, которые обязательно нужно объяснить? Или, может быть, есть то, что объяснять не надо? И не стоит тратить время, документируя API, на объяснение читателю, что такое HTTP или каковы принципы REST? А иногда, возможно, такие вещи объяснять нужно? Второй вопрос: зачем мы связываем коммуникацией этих стейкхолдеров? Этот вопрос тоже распадается на несколько. Какая проблема стоит перед читателем? Зачем принимающая сторона вообще нас слушает? Что ей нужно от этого акта коммуникации? В нашем примере про API — что читатели API хотят узнать про API? Структуру методов или свойства каждого метода? Или, может быть, читателю это пока не интересно, но он хочет узнать бизнес-назначение API, что он этим API может сделать? Или он хочет узнать, как реализовывать типовые сценарии, которые ожидает от вашего продукта? И вообще, можно ли те сценарии, которые он хочет, с помощью вашего API реализовать? Совершенно не факт, что типовой справочник методов на эти вопросы ему ответит. Наверное, нужно написать какие-то вводные статьи или туториал. Фронт работ наведения порядка в документации большой: Кто-то должен вам ответить на все эти вопросы. Хорошие новости: на рынке есть люди, которые по определению занимаются именно этими активностями! Это технические писатели. Это не шутка. Опытный технический писатель, помимо того, что пишет документацию сам, может помочь вам создать процесс документирования, чтобы получить на выходе документацию как артефакт. Но, так как он не создает процессы, а помогает их создавать, то в одиночку, скорее всего, он их не реализует. Потому что ему нужен довольно сильный административный рычаг, чтобы создавать новые процессы и менять существующие — менеджеры-союзники, внедряющие и меняющие процессы по его рекомендации. В нашем опыте очень много компаний говорят: «Мы понимаем, что нам нужен технический писатель, но нанимать его не будем. Потому что он не знает, что именно писать — он же не программист. Он будет просто секретарём, который ходит за нашими разработчиками и пишет за ними слово в слово то, что они говорят. Зачем? Мы уж тогда сами лучше напишем».  Короткий ответ — это не так. Технический писатель, особенно имеющий базовое образование в сфере IT, сможет быстро разобраться в вашей предметной области и говорить с разработчиками на одном языке, потому что его профессия — быстро разбираться во всем новом. Но при этом у техписателя действительно есть режим «не писать всё самому». Техписатель может: Откуда брать технических писателей? Во-первых, эти люди есть на рынке и их можно нанять. Техписатель с несколькими годами опыта, сильным техническим бэкграундом и IT-образованием, скорее, всего, сможет настроить вам все нужные процессы или здорово в этом поможет. Во-вторых, техписателя можно вырастить внутри вашей команды — из разработчика, аналитика или менеджера. Скорее всего, в вашей инженерной команде есть люди, думающие о документации чуть больше, чем все остальные. У них болит душа за эффективную коммуникацию между стейкхолдерами и они хотят, чтобы она реализовывалась лучше. Если ситуация позволяет, то пусть они и станут теми самыми корпоративными библиотекарями или техническими писателями. Техписатель в итоге может вырасти в knowledge-менеджера— поотому что процесс управления документацией — это неотъемлемая часть, прямое подмножество процесса управления знаниями. И, конечно, вы можете нанять внешних консультантов, например, у нас в documentat.io. Мы настраивали такие вещи уже не в одной компании и поможем вам с настройкой процессов, выработкой шаблонов, гайдлайнов и наведением порядка в вашей базе знаний. Или просто отдайте нам часть ваших задач по написанию документации в формате аутсорс/аутстафф. Если вы уже задумались, что же с вашей документацией не так — вы в начале пути, который обязательно завершится успешно, и с вашей документацией всё обязательно будет хорошо! Видео моего выступления на Knowledge Conf 2020: Технический писатель