Где писать документацию

Можно — хоть в физическом блокноте, если дока нужна только вам лично. И здесь мы снова встречаемся с определением целевой аудитории. Поэтому нужно доку писать там и в том, где и в чём ваши читатели ожидают доку увидеть.

Правила хорошего тона

✔️ Не отправлять редактируемые файлы. Вы не можете предсказать, как они откроются у читателя и откроются ли вообще. Размещайте доку онлайн или, если совсем никак, отправляйте pdf.

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

✔️ Делать разные документации для разных версий вашего продукта. Например, если в инструкции к iOs приложению только скрины с Android — это плохо.

✔️ Знать свою ЦА и уровень её подготовки. Если не знаете — пишите как можно проще, объясняя каждый термин.

Fancy онлайн-редакторы

Google docs, Notion
Confluence, Wiki

Языки разметки

Markdown, AsciiDoc

IDE и плагины

Visual Studio Code — популярная и лёгкая IDE, плагин Markdown All in One — полная поддержка Markdown, предпросмотр и синтаксическая подсветка.

IntelliJ IDEA — привычная Java-разрабам среда, плагины AsciiDoc Plugin, Grazi.

И плагин PlantUML для обоих — визуализация диаграмм UML внутри документации.

Классика, от которой уже пора отказаться

MS Office, Libre Office / Open Office etc