А теперь поднимите руки те, кто документирует свой код, свои приложения, свой проект в полной мере. Как вас мало 🙂 На самом деле терпеть не могу вот такие интерактивы на конфах, особенно когда у некоторых докладчиков частота вопроса вообще выходит за грань разумного. Но если все же представить такой вопрос, то рук действительно было бы мало. Даже при видимой наполненности confluence в проекте "ценность" док очень низка обычно. И как следствие абсолютному большинству участников проекта "это все не надо". Ну или надо из серии "у нас дока г..но надо сделать лучше" и на этом все.

Я для себя особенно выделил некоторые жизненные наблюдения, которые как мне кажется являются определяющими в этом вопросе.

Самое важная характеристика документации это ее ценность. Мы когда сталкиваемся с чем-то неизвестным, то делаем что? Идем гуглить. Потому что знаем что в большинстве случаев найдем свой ответ на наш вопрос. И вот такой же должна быть дока на проекте. Это основная цель, к которой мы должны стремиться при создании документации или не писать ее вовсе (радикально да).

Самые частые отмазы от написания доки какие я слышу: занимает время и нафига это надо. Первая отмаза действительно имеет место быть. И возможно в небольшом проекте из двух человек это было бы даже и верно (но это не точно).

Самое сложное - начать. Поставить работу на поток. Приучить всех к тому что мы это делаем ежедневно также как пишем код. Проверять на код ревью, что разработчик также исправил и доку вместе с кодом. Лучше всего сработают автоматические проверки, если это возможно в рамках конкретного проекта и если хватит скиллов это реализовать (возможно в будущем расскажу как я это сделал на одном из проектов).

Архитектура и соглашения. Звучит казалось бы немного странно, но это должно быть. Как оформляются новые страницы, в каких разделах о чем писать, может даже подготовить шаблоны страниц.

Графика намного упрощает восприятие и создание. Нарисовать в [draw.io](http://draw.io) схему взаимодействия модулей намного понятнее и быстрее воспринимать и запоминать. Также я использую всем известный plantUML. Исходники в xml должны быть обязательно приложены.

В создание документации должны быть вовлечены все члены команды, точно также как в создание продукта. Тестировщики, программисты, прожект менеджеры, продакты и т.д.

Почему это важно?

- Вы сами через 2-4 недели забудете то, что вы делали (в подробностях точно). Добавили себе кучу времени на вспомнить.
- Коллеги не будут вас так часто (но не совсем) дергать если у них будет проектный google. Меньше стресса, выше эффективность.
- Снижается bus factor (о его опасности для проектов написаны тонны текста)
- Новые люди будут входить в разы быстрее. Принятие нового человека не будет таким страданием для него и для вас. Даже если это и бывает нечасто.

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