Перевод статьи «How to Write Good Documentation».
В этой статье я расскажу о трех шагах, которые помогут вам не забыть, как работает ваш проект.
Вероятно, вам случалось оставить проект сделанным наполовину, а потом уйти на несколько дней в отпуск. Теперь вы узнаете, что нужно делать, чтобы потом без проблем вернуться к работе.
В командах, где я выступаю в роли тимлида, мы стараемся постоянно все документировать. Документация живет своей жизнью параллельно с кодом, она — равнозначный игрок.
Благодаря этому никому не приходится строить догадки, как работает та или иная вещь. Не приходится проводить длительные совещания для обмена знаниями. Хорошая документация экономит нам много времени и избавляет от нудной рутины.
Вопреки распространенному мнению, самая ценная документация пишется не для других людей. Как я написала в одном твите,
«Секрет хорошей документации в том, что ее надо писать параллельно с написанием кода. Ваша первая аудитория — вы сами. Объясните самому себе, что вы делаете. В будущем вы будете благодарны себе за это».
Итак, переходим к конкретике. Вот три шага, которые нужно сделать для написания хорошей документации.
1. Начните со скрупулезного ведения заметок
Воплощая свои идеи в код, обязательно ведите записи. Это поможет вам не забыть важные детали. Хотя впоследствии вы еще распишете все подробно, короткие пометки способны вместить достаточно деталей и вместе с тем не будут сильно отвлекать вас от написания кода.
Пока пишете код, держите открытым файл, где ведете записи. Вносите в него такие вещи как примененные команды, принятые решения, использованные ресурсы. Вы можете записывать:
- команды, которые вводите в терминале,
- объяснения, почему предпочли один метод другому,
- ссылки, которые посетили в поисках помощи или
кода для копипаставдохновения, - порядок выполнения действий.
На этом этапе не обязательно даже писать полными предложениями. Просто следите за тем, чтобы точно передавать контекст, прикладывать соответствующие отрывки кода и полезные URL. Также будет полезным включить опцию автосохранения для этого файла.
2. Объясните свои решения более подробно
Идеальное время для написания пространных объяснений — перерыв после написания кода и перед уходом на обед или переключением на другую задачу.
Чтобы все хорошо и подробно объяснить себе будущему, вам нужны свежие воспоминания о контексте, идеях и решениях.
Вернитесь к своим коротким заметкам и начните расширять их, придерживаясь разговорного стиля. Побудьте своей резиновой уточкой. Объясните, что вы делаете, как будто вы учите кого-то другого. На этом этапе вы можете раскрыть такие темы как:
- ваши неожиданные решения («Обычно я делаю это вот так, но сейчас решил сделать иначе, потому что…»);
- трудности, с которыми вы столкнулись, и то, как вы их преодолели;
- архитектурные решения, направленные на достижение целей проекта.
Не слишком вдавайтесь в детали, сосредоточьтесь на главном. То, что эти объяснения более многословные, чем ваши короткие заметки, еще не значит, что надо писать так, будто вам платят за каждое слово. Просто используйте полные предложения и пишите так, будто объясняете проект коллеге. В конце концов, вы же для себя пишете.
3. Не забудьте упомянуть о предварительных знаниях
Этот шаг лучше делать после полноценного обеденного перерыва или даже на следующий день (но два дня — это уже пожалуй перебор). Перечитайте написанную документацию и заполните все пробелы, которые стали заметны после некоторого дистанцирования от проекта.
Сделайте дополнительные усилия и напишите, какие предварительные знания и навыки нужны для работы над этим проектом (или хотя бы ссылок набросайте). Особенно это касается случаев, когда вы часто использовали разные языки или инструменты. Даже такая мелочь, как вставка ссылки на документацию используемого API, может в дальнейшем сэкономить часы на поиски.
Напишите или прикрепите ссылки на все нужные README, шаги установки, релевантные запросы в поддержку. Для часто осуществляемых действий в командной строке можно использовать самодокументирующийся Makefile. Таким образом вам не придется открывать man для повторяющихся задач при каждом возвращении к проекту.
Спустя некоторое (даже довольно короткое!) время легко забыть какие-то детали, связанные с проектом, но не являющиеся его непосредственной частью. Записывайте все, что сочтете полезным.
Документируйте всё!
В следующий раз, когда поймаете себя на мысли «Я это точно запомню, нет нужды записывать», вспомните какую-нибудь картинку типа фейспалм.jpg.
Проекты создания программ представляют собой намного больше, чем просто код. Чтобы в будущем сразу успешно начать работать с любым своим проектом, документируйте всё! Будь то установленная вами процедура, инфраструктура как код или мимолетная идея на будущее — записывайте! Когда-нибудь вы поблагодарите себя за это.
[customscript]techrocks_custom_after_post_html[/customscript]
[customscript]techrocks_custom_script[/customscript]
