Настоящий CTO: думай как технический директор - Алан Уильямсон

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

11.1. Зачем составлять документацию?

Зачем эти хлопоты? Ведь ваша команда знает, как все устроено, – это знание передается из поколения в поколение. Кроме того, ваш технологический стек так грамотно спроектирован и внедрен, что в нем разберется любой толковый специалист. Если вы так думаете, то, вероятно, еще и уверены, что ваш код не содержит ошибок и, следовательно, не требует тестирования! Звучит абсурдно, но многие действительно так считают.

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

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

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

• Новый сотрудник увидит его, подумает, что можно сделать все проще, переделает – и в итоге что-то сломается.

• Люди будут бояться трогать решение или тем более пытаться его переделать. Оно приобретет мифические свойства и будет считаться слишком сложным или важным, чтобы рисковать и вносить в него изменения.

Оба сценария несут большую опасность, и обоих можно полностью избежать, если оставить краткие пояснения. Как однажды заметил один мудрый разработчик: «Комментарии [в коде] – это любовные записки будущему самому себе».

11.1.1. Целевая аудитория

Документация – это не единая универсальная вещь, подходящая сразу для всех читателей. Это набор документов, предназначенных для разных групп получателей, в зависимости от того, как они взаимодействуют с системой. Вот какими могут быть эти группы:

• Конечные пользователи. Пользователи системы, взаимодействующие с готовым продуктом.

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

• IT/DevOps. Команда, отвечающая за поддержание системы в рабочем состоянии.

• Разработчики. Команда, которая создает и исправляет функционал.

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

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

Составляйте документацию на языке, понятном каждой группе, чтобы информация была более доступной. Например, описание алгоритмов не будет иметь особого смысла для конечного пользователя или сотрудников службы поддержки, но поможет разработчикам развивать и дорабатывать ПО. Точно так же подробные описания интерфейса и последовательности скриншотов не помогут команде IT/DevOps, потому что им на самом деле все равно, как выглядит приложение. Им необходимо знать, как, например, делать резервное копирование. Обращайтесь к конкретной аудитории.

11.1.2. Формат

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

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

Документация в файлах PDF или DOC была актуальна 20 лет назад, но не сейчас. Документ, особенно предназначенный для обучения или описывающий работу платформы, должен быть живым. Его необходимо обновлять с каждым релизом или при появлении новых данных. И такое обновление не должно превращаться в отдельную большую задачу, оно должно делаться быстро и без усилий.

Когда Тим Бернерс-Ли (Tim Berners-Lee) создавал интернет, его целью было обеспечить удобный обмен информацией. Таким образом, логично организовать хранение документов на основе технологий интернета. Такие инструменты, как вики, Atlassian Confluence, Google Docs и Office 365, отлично подходят для работы в браузере. При выборе платформы для документации учитывайте следующее:

• Прямые ссылки на контент. Убедитесь, что пользователь может попасть в нужный раздел по ссылке и не требуется совершать несколько шагов, чтобы найти его.

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

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

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

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

• Обратная связь. Читатели должны иметь возможность оставлять комментарии или примечания, чтобы дополнять текст.

• Вложения. Насколько удобно прикреплять дополнительные файлы (изображения, видео, PDF)? Такие данные лучше хранить вместе с документом, к которому они относятся.

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

11.1.3. Проверка

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

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

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

Особое внимание уделите описанию работы, которую обычно выполняет