Ответ
Техническую документацию следует хранить в системах, обеспечивающих версионность, доступность и совместную работу. Лучшая практика — хранить её рядом с кодом.
Основные подходы и инструменты:
-
В системе контроля версий (Git) вместе с кодом
- Преимущества: Единая версия документации и кода, история изменений, код-ревью для docs.
- Структура в репозитории:
project/ ├── docs/ # Основная документация │ ├── api.md │ ├── architecture.md │ └── testing.md ├── README.md # Точка входа └── src/ # Исходный код - Формат: Markdown (.md), AsciiDoc. Для API — OpenAPI/Swagger спецификации (.yaml/.json).
-
Внутренние Wiki-системы
- Инструменты: Confluence, Notion, Wiki в GitLab/GitHub.
- Преимущества: Удобный редактор, мощный поиск, навигация, интеграции (Jira, Slack).
- Недостаток: Документация может "отставать" от кода, если не синхронизирована.
-
Специализированные инструменты
- TestRail, Zephyr: Для хранения тест-кейсов и отчетов.
- Swagger Hub, ReadTheDocs: Для публикации API и технической документации.
Ключевой принцип: Избегайте хранения критической документации в изолированных файлах (Google Docs, локальные .docx) без контроля версий и четкого процесса обновления.
Ответ 18+ 🔞
А, вот это интересный вопрос, блядь! Про то, куда девать эти ваши бумажки, чтобы потом не рыдать, как Герасим над Муму. Слушай сюда, я тебе сейчас такую простыню разложу, что ты офигеешь, но всё по делу, ёпта.
Значит, смотри. Вся эта ваша писанина — архитектуры, API, инструкции «как не сломать продакшн» — это не просто буквы. Это, блядь, такой же код, только для людей. И хранить её надо не абы где, а с умом, чтобы потом не получилось, как в том анекдоте: «документация есть, но она устарела, а новая — в голове у Васи, а Вася в отпуске». Пиздец, а не работа.
Так куда же её, эту ману, пихать?
Первое и самое главное — прямо в гите, рядом с кодом, сука! Это не я придумал, это лучшая практика, проверенная временем и слезами. Представь: у тебя есть версия кода 1.2.3. И рядом, в той же ветке, лежит документация, которая точно описывает, как этот код 1.2.3 работает. Красота же? Никаких «ой, а это для какой версии?». Всё в одном месте, как яйца в одном тазу.
- Что хорошего? История изменений на хуй. Сделал пул-реквест — там же и правки в
README.mdпосмотрел. Всё прозрачно, как слёзы ребёнка. - Как выглядит в репо? Обычно вот так, просто и понятно:
project/ ├── docs/ # Тут вся основная муть │ ├── api.md # Кто, кому и как может позвонить │ ├── architecture.md # Из каких палок и верёвок всё собрано │ └── testing.md # Как бить, чтобы не сломалось ├── README.md # Святая святых, точка входа. Что это, как запустить, куда бежать └── src/ # А вот тут уже сам код, священная корова - В чём писать? Markdown (.md) — наш всему голова. Для API — OpenAPI (эти ваши
swagger.yaml), чтобы можно было наглядненько.
Второй вариант — разные вики-конторы типа Confluence или Notion. Тут, конечно, редактор покрасивее, поиск поумнее, можно красивые таблички лепить. Но здесь таится, блядь, главная подстава! Документация в вики имеет волшебное свойство отставать от реальности, как поезд, ушедший вчера. Код уже десять раз переписали, а в вики всё ещё инструкция для первого коммита. И все делают вид, что так и надо. Хуйня полная.
Ну и есть спецтулы для особых случаев. Хранилища для тест-кейсов (TestRail), красивые генераторы документации (ReadTheDocs). Это уже по обстоятельствам.
А теперь, внимание, главный принцип, который надо выжечь на жопе раскалённым гвоздём:
Избегай как чумы хранения критичной документации в изолированных помойках. Эти ваши гугл-доки, локальные specification_final_final_2.docx на рабочем столе, скриншоты в общем чате — это прямой путь в ад. Нет контроля версий, непонятно, кто последний правил, и в один прекрасный день всё это благополучно накроется медным тазом. И ты останешься с кодом, который нихуя не понятно как работает.
Короче, суть в чём: документация должна жить там же, где и код. Вместе родились, вместе меняются, вместе идут на прод. Всё остальное — от лукавого и ведёт к беспорядку, волнению ебать и терпения ноль ебать. Всё, лекция окончена, можешь идти применять.