Одним заголовком уже многое сказано. Но все же нужно подробнее расписать, что я имею в виду.
Идея:
Необходимо, не нарушая правила «Необходимое и достаточное», хранить некую документацию в одном месте, мочь легко её находить и просматривать историю. Это будет не основная документация, для неё мы нашли место в предыдущей статье. Тут надо устроить хранение тех документов, которые не требуют целой системы, а достаточно просто места, где они будут лежать.
При этом есть идея использовать для этого версионность (git или аналог) и работу с ветками (по необходимости).
Цель:
- Как можно меньше такой документации и следовательно - меньше траты времени на её ведение.
- Не смотря на первую цель - необходимое для работы качество не должно страдать.
- Актуальность. Документация должна отражать только настоящее. Не допускается вопрос - "из будущего эта информация или из прошлого?".
- Хронология. Необходимо всегда знать - откуда пришла та или иная информация и когда.
- И конечно собранность. Искать информацию в разных источниках - это так себе удовольствие.
План:
План довольно-таки прост
- Поискать готовые решения.
- Если таких не найдется - создать своё.
Реализация:
Конечно, в начале я поискал готовые решения. Посмотрел, что предоставляют Git сервисы. Не удовлетворили, но натолкнули на идею.
Как все же хорошо, если документация будет жить также, как и код. Актуальная - лежит в Master, все не готовые и не внедренные вещи лежат в ветках. Когда приходит их время - они вливаются и все хорошо.
Как это выглядит в моей голове:
В основной ветке всегда только актуальная информация. Тут нет устаревшего, не принятого или еще не вошедшего документа.
Как только есть задача на написание, составление или заполнение документа - создается под это отдельная ветка. И мои излюбленные правила:
1. В названии ветки должен присутствовать номер задачи\эпика\юзерстори.
2. В коммитах также должен присутствовать номер задачи. Нет задачи - нет коммита.
Как только работа по задаче закончилась (вся, включая разработку, если это нужно), она вливается в основную ветку.
Если по каким-то причинам что-то откладывается на потом - ветка продолжает висеть отдельно и никого не трогает. Она не захламляет актуальную документацию, и в то же время не является потерянной.
А для того, чтобы это было легко контролировать и проверять (QA) - можно использовать MergeRequest'ы.
Из более менее похожих решений удалось найти только gitbook.com, но у него почему-то не нашлось веток. Не понимаю почему? Это же git, это одна из его основ. Точнее, там есть ветки, они называются Variants. Но они рассчитаны просто на различные варианты документации, и мерджа я в них не нашел. Может быть в будущем еще вернусь посмотреть на этот сервис, а пока будем экспериментировать.
В целом git и сервисы с репозиториями дают возможность вместе с небольшими проектами там же держать и документацию к ним. К сожалению, документы для лучшего ведения должны быть .md, и верстка их должна быть Markdown, но это может не так и страшно. В том же GitLab есть встроенный редактор таких файлов, а заодно можно посмотреть и изменения, и все что хочешь. Также редактирование .md и визуализация Markdown можно встроить в своё любимое IDE (в мной любимом Rider - через дополнение). А есть и отдельные программы-редакторы .md, например Typora - вполне ничего.
Но я решил все же не смешивать такую документацию с проектами (к технической документации это не относится), а создал просто отдельный репозиторий под это, простую структуру папок для разных типов документов - и в путь.
Итого:
Это конечно будет явно не последняя попытка поэкспериментировать в этом вопросе. В процессе использования будут притираться инструменты и правила, возможно даже меняться.
