Без длинной вводной части. Когда у тебя или коллег возникает вопрос как понятно, полезно и удобной вести документацию в проекте, то возьми на вооружение эти принципы:

1️⃣ Пиши простыми словами  Не перегружай текст терминами и аббревиатурами. Если без них не обойтись — объясни сразу. Сделай так, чтобы даже новичок в теме понял.

2️⃣ Пиши только то, что нужно  Оставь только релевантную информацию. Лишние детали усложняют восприятие и отвлекают.

3️⃣ Упрощай доступ к полезной информации  Думай о структуре: должна быть лёгкая навигация, ссылки на ключевые разделы, оглавление.

4️⃣ Чётко опиши проблему  Если ты решаешь проблему - документация должна начинаться с объяснения этой проблемы. Это важно для понимания контекста.

5️⃣ Используй примеры и иллюстрации  Скриншоты, диаграммы и примеры всегда помогут быстрее понять, как использовать информацию.

6️⃣ Создай структуру перед написанием  Составь структуру документации до наполнения. Это поможет избежать пропусков и сделать документ более организованным.

7️⃣ Разбивай на блоки  Если документация становится слишком большой — разбивай её на отдельные, понятные разделы. Это упрощает поиск нужной информации.

8️⃣Следуй логике  Опиши процесс шаг за шагом. Избегай скачков из одного пункта в другой — так будет легче понять документацию и следовать за её логикой.

9️⃣ Пусть полежит, потом читай снова  Дай документации "отлежаться" пару дней, или покажи её коллегам для обратной связи. Это поможет выявить ошибки и улучшить текст.

🔟 Используй ГОСТы и стандарты  Если есть внутренние стандарты — используй их. Это поможет соблюдать единство стиля. ГОСТ (19,34) поможет организовать документ более формально или сделать/изменить стандарты в своем проекте.

1️⃣1️⃣ Обновляй регулярно  Боль каждого проекта. Документация не должна быть статичной. С развитием проекта старайся обновлять её.

1️⃣2️⃣ Прислушивайся к обратной связи  Не стесняйся получать отзывы. Это поможет улучшить качество документации и сделать её более полезной для всей команды.

Советую почитать первую книгу Ильяхова «Пиши, сокращай». Последнюю версию ещё не читал, но думаю она тоже полезная)

Мой телеграм канал