Как вести документацию, чтобы она была доступной и понятной?

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Как вести документацию, чтобы она была доступной и понятной? | Сетка — новая социальная сеть от hh.ru
repost

168

input message

напишите коммент

еще контент автора

еще контент автора

войдите, чтобы увидеть

и подписаться на интересных профи

в приложении больше возможностей

пока в веб-версии есть не всё — мы вовсю работаем над ней

сетка — cоциальная сеть для нетворкинга от hh.ru

пересекайтесь с теми, кто повлияет на ваш профессиональный путь