[Перевод] Откровения кофеин-зависимого инженера: как писать документацию
Четыре вида документации распределнные по двум осям: практика-теория и обучение-работа.
Недавно вышли два нашумевших поста:
И многие спрашивали: «Кто-нибудь, пожалуйста, научите меня писать хорошую документацию».
Я не претендую на звание эксперта, но думаю, что хорошо с этим справляюсь.
Я выпил достаточно кофе, и я попытаюсь объяснить то, что знаю.
TL; DR: пишите документацию для решения конкретной проблемы для определенной группы людей, а не только для того, чтобы документация была.
Пишите хорошо
Во-первых, вам нужно уметь хорошо писать. Автор «пьяных откровений» явно уже опроверг это утверждение, но для большинства это может не сработать. Вы должны уметь брать темы и выискивать основную суть, показать ключевые детали. Эти детали нужно правильно упорядочить, а затем перевести в четкие предложения.
Навык хорошего письма, конечно, не ограничивается только документацией. Вы можете проверить свои способности в этой области с помощью любого вида письма. Можете ли вы написать, как найти что-нибудь в своем доме? Можете ли вы написать короткую речь? Если вам нужно поработать в этой области, я предлагаю попрактиковаться в написании чего-либо, кроме документации. Пишите сообщения в блогах, пишите короткие рассказы, пишите письма друзьям, что угодно. Если вы не читаете книги регулярно, начните прямо сейчас. Ваш мозг должен быть натренирован на большом количестве хорошо написанного текста, прежде чем вы сможете сказать, что работает, а что нет в вашем конкретном случае. Развивайте и навык редактирования, который сильно отличается от навыка письма (писать становится легче, если вы доверяете своим навыкам редактирования — вы не будете так сильно фильтровать себя).
Самый полезный совет для написания документации — пишите в разговорном стиле. Воспринимать информацию из неформального текста намного проще.
Виды документации
Ладно, теперь вернемся к документации.
Существуют разные виды документации, и люди из себя веревки вьют, пытаясь заставить один вид документации выполнять работу другого. Растяжка идет по двум осям:
- Информация для обучения VS информация для работы.
- Практические шаги VS теоретическая информация.
(Это не моя мысль, я увидел это в https://documentation.divio.com/)
Информация для обучения, содержащая практические шаги, называется учебным пособием (tutorial). Если она не содержит практических шагов, это объяснение (explanation). Оба из них, как правило, больше подходят для начинающих, поэтому им следует сосредоточиться на том, чтобы объяснять концепции и термины (и справочную информацию). Что касается объяснений, действительно полезно иметь краткий конспект вверху.
Можно с уверенностью предположить, что благодаря информации о том, когда вы работаете, кто-то уже имеет общее представление о том, что происходит.
Теоретическая информация, используемая при работе, называется справочной (reference). Сюда входит документация по каждому методу. Справочная документация — совершенно бесполезное место для размещения учебного пособия.
Если это не теория, то это руководство (guide). Руководство в основном похоже на учебное пособие, за исключением двух важных отличий: оно предполагает некоторое знакомство с темой и цель состоит в том, чтобы выполнить конкретную задачу, а не чему-то научить. Контрольный список — это краткое руководство, но он все же может быть полезен, если очень легко забыть о важном шаге. Используйте руководства, когда есть шаги, которые придется повторить. Они особенно ценны, когда человек, выполняющий шаги, не знает, как выполнить задачу (либо кто-то из другой команды, либо вы через год).
Выберите тип документации для написания, исходя из потребностей вашего читателя. Может случиться так, что ваш код на самом деле довольно самодокументирующийся, и чтение сигнатуры метода действительно говорит вам, что делает этот метод. Отлично. Это касается справочной документации. А теперь напишите остальные три вида.
Если все, что у вас есть, — это справочная документация (reference documentation), информация будет бесполезным набором случайных фактов для читателей, не знакомых с основами. Справочная документация — это все равно, что иметь подробное описание перекрестков, когда новые читатели ищут карты автомагистралей.
Я думаю, что на самом деле существует пятый вид документации: breadcrumbs. Это небольшие комментарии в коде или заметки в документах (или даже сообщения об ошибках в пользовательских линтерах), которые указывают читателям на то, что им нужно знать. Вы можете написать небольшой комментарий со ссылкой на тикет Jira, объясняющий, почему этот код необходим, или указать людям, какую команду нужно запустить для устранения ошибки. Breadcrumbs действительно легко добавить в документацию и сэкономить массу времени.
Почему
Очень легко забыть написать о вещах, которые кажутся очевидными. Конечно, как мы создаем микросервис, мне не нужно писать, почему мы это делаем. Но вам нужно.
Это очевидно для вас, но не для читателя. Обоснование решений кажется нам действительно очевидным, потому что мы потратили так много времени на размышления об этом.
Когда вы объясняете почему вы что-то делаете, вы вынуждены мысленно проследить шаги, которые привели к решению. Оказывается, это также отличный способ познакомить с теми или иными темами.
Если вы застряли, пытаясь объяснить почему, просто представьте, каким был бы мир, если бы то, что вы документируете, внезапно исчезло. Кого будет волновать, что они увидят?
Еще лучше, если вы сможете объяснить причину с помощью истории. Люди действительно хорошо обрабатывают и запоминают истории.
Мне нравятся другие комментарии в документации. Например. «мы знаем, что это не очень хорошо, и мы действительно хотим, чтобы это работало, как X, но для этого потребуется команда T обновить свои материалы, а они очень перегружены, поэтому мы пока живем с этим». Это такая информация, которая объединяет все в головах людей и позволяет им чувствовать, что они понимают, что происходит.
Нетехнический темы
Тот факт, что вы документируете техническую тему, не означает, что читателю также не нужно знать некоторые нетехнические вещи. Причина, по которой все обстоит именно так, очень серьезна.
Другие полезные нетехнические детали, включая:
- Процессы, которым необходимо следовать (например, прежде чем обновлять что-то, отправьте электронное письмо в этот список рассылки, чтобы служба поддержки могла подготовиться).
- Командная динамика. «Та команда X действительно беспокоится о том, чтобы произошло Y, так что узнайте у них о Z»
- Информация о пользователях. «У нас много пользователей, которые создали свои собственные штуки, и им не нужно менять свои штуки, поэтому мы делаем это обновление только для пользователей без специальных штук».
- Интересные факты, например «мы называем эту систему Нарнией, потому что …»
Туториалы
Учебные пособия предназначены для ознакомления людей с темой. Это действительно хороший способ сделать это, потому что люди лучше учатся, когда они что-то делают, а не просто читают.
Учебные пособия также требуют больших вложений (по сравнению с другими видами документов). Писать их, вероятно, имеет смысл только в том случае, если многим людям нужно изучить тему. Если это всего лишь несколько человек, встреча с ними лицом к лицу (или с веб-камеры на веб-камеру), вероятно, будет лучшим использованием времени.
Ловушка при написании учебных пособий — попытаться все объяснить. Не поддавайтесь желанию перечислять все технические детали и все исключения из установленных правил. Вы просто хотите, чтобы читатели поняли основную механику. Мелкие детали можно оставить для документации, предназначенной для более опытных людей.
Также очень часто учебные пособия просто не работают, когда кто-то пробует работать с ними. Вам нужно опробовать написанные вами шаги (в идеале на новом компьютере без уже установленных всех компонентов), чтобы убедиться, что они полны и действительно работают. Затем выполните действия в следующий раз, когда кому-то понадобится использовать это руководство, и посмотрите, где они застряли.
Шаги также устареют, поэтому обязательно выслушайте людей, у которых есть проблемы с ними.
Гайды
Руководства, как правило, дают хороший возврат вложенных средств. Если вы потратите 10 минут на перечисление шагов в виде маркированного списка, то сможете сэкономить час на размышления о том, что делать в следующий раз.
Это особенно ценно, когда сложно понять, что это за шаги, или если важный шаг легко пропустить.
Пишите руководства, когда вы только что прошли через этот процесс и у вас есть мотивация, чтобы избежать повторного выяснения всего этого.
Объяснение и справка
Честно говоря, я не уверен в ценности справочной документации в стиле javadoc. Конечно, если миллион человек собирается использовать ваш урок, засучите рукава и задокументируйте все до мельчайших деталей. Но если это просто ваша команда будет читать, они уже будут знать 99% того, что вы можете написать.
Объяснения, как правило, более полезны, особенно когда они сосредоточены на объяснении причин. Если вы объясните пользовательские и технические ограничения, которые приводят к созданию дизайна, вы можете почти забыть об объяснении самого дизайна — вооружившись справочной информацией, кто-то может понять это самостоятельно, прочитав код. Вы можете (в конечном итоге) изучить структуру, просто прочитав код, но трудно или даже невозможно понять причины таким образом.
Практика документации
Написание документации требует времени. Много времени. Потратить это время на документацию не просто по волшебству, потому что кто-то говорит, что «нам нужно больше документации». Вы должны выделить для этого время и потратить часы на написание. Нет, это не самый веселый способ провести вечер в четверг, но ты должен это сделать.
Или нет? Вам следует писать документацию только тогда, когда она полезна. Вы бы не стали писать код только ради того, чтобы написать больше кода (или, может быть, вы бы стали, но я бы не стал). Вы пишете код, чтобы решить какую-то конкретную задачу. Вы также должны написать документацию, чтобы решить какую-то конкретную задачу.
Это «что-то» может быть реализовано для того, чтобы помочь новым людям активизировать команду, уменьшить фактор автобуса в команде, избежать ошибок из-за забывания шагов, сэкономить время людей при выполнении действий, обеспечить контекст, выстроить согласование, записать грубые, но важные детали и т.д. Если вы не знаете, зачем пишите документацию, не делайте этого. Как только вы узнаете зачем, выберите подходящую документацию для решаемой проблемы.
Пожалуйста, во имя всего святого, не пишите такую документацию:
/**
* @param customer The customer
* @param order The order
* @return The price
*/
public Price getPrice(Customer customer, Order order) {}Это бессмысленно и учит читателей мысленно пропускать комментарии. Они пропустят комментарии, которые действительно содержат что-то полезное. Если вам нечего сказать, не говорите этого.
Документацию, как и код, нужно поддерживать. За ее хранение приходится платить. Вы должны выделить время, чтобы поддерживать ее. К счастью, это обычно намного дешевле, чем поддержка кода. Несколько часов в месяц — это все, что вам нужно, чтобы прочитать всю вики и исправить то, что сейчас не так.
Совет: создайте раздел «архив» в своей документации и перемещайте туда устаревшие материалы. Он сохраняет исторический контекст, это лучше, чем просто удаление документации, и при этом не нужно вводить ничего не подозревающих читателей в заблуждение.
Один из способов сэкономить время — превратить другую работу в документацию. Если вам нужно объяснить коллеге, как интегрироваться с вашей системой, скопируйте то, что вы пишете в Slack, в документ. Если вы написали проектную документацию, скопируйте несколько ее разделов в документацию и потратьте 10 минут на ее подготовку. Когда вам нужно что-то объяснить рецензенту в код ревью, объясните это с помощью комментария в коде, а не коммита в Github. Объясняет ли ваш тикет Jira, почему необходимо выполнить задачу? Круто, скопируйте это, и у вас есть документация. (Если это не так, заставьте спрашивающего написать это!)
Сообщите людям, куда обращаться, чтобы задать вопросы. Чтобы написать «если у вас есть какие-либо вопросы, вы можете связаться с нами по адресу #team-channel в Slack», примерно за 15 секунд. Это поможет сэкономить часы, если вы запутаетесь. Довольно хорошая окупаемость на мой взгляд
Итак, кофе кончается, поэтому остановлюсь на этом.
