Четыре вида документации распределнные по двум осям: практика-теория и обучение-работа.
Недавно вышли два нашумевших поста:
И многие спрашивали: «Кто-нибудь, пожалуйста, научите меня писать хорошую документацию».
Я не претендую на звание эксперта, но думаю, что хорошо с этим справляюсь.
Я выпил достаточно кофе, и я попытаюсь объяснить то, что знаю.
TL; DR: пишите документацию для решения конкретной проблемы для определенной группы людей, а не только для того, чтобы документация была.
Пишите хорошо
Во-первых, вам нужно уметь хорошо писать. Автор
«пьяных откровений» явно уже опроверг это утверждение, но для большинства это может не сработать. Вы должны уметь брать темы и выискивать основную суть, показать ключевые детали. Эти детали нужно правильно упорядочить, а затем перевести в четкие предложения.
Навык хорошего письма, конечно, не ограничивается только документацией. Вы можете проверить свои способности в этой области с помощью любого вида письма. Можете ли вы написать, как найти что-нибудь в своем доме? Можете ли вы написать короткую речь? Если вам нужно поработать в этой области, я предлагаю попрактиковаться в написании чего-либо, кроме документации. Пишите сообщения в блогах, пишите короткие рассказы, пишите письма друзьям, что угодно. Если вы не читаете книги регулярно, начните прямо сейчас. Ваш мозг должен быть натренирован на большом количестве хорошо написанного текста, прежде чем вы сможете сказать, что работает, а что нет в вашем конкретном случае. Развивайте и навык редактирования, который сильно отличается от навыка письма (писать становится легче, если вы доверяете своим навыкам редактирования — вы не будете так сильно фильтровать себя).
Самый полезный совет для написания документации — пишите в разговорном стиле. Воспринимать информацию из неформального текста намного проще.
Виды документации
Ладно, теперь вернемся к документации.
