Формализовали плюсы и минусы трёх основных подходов к документированию на проектах.
Мы тут проводим митап от программного комитета KnowledgeConf. В первой половине записали плюсы и минусы разных подходов к документации и тому, как сохранять знания о проекте.
Часть 3. Самодокументируемый код
+ Документация всегда актуальна
+ Автоматизируется, доставляется в CI/CD
+ Ограничен круг редакторов
+ Мотивирует хорошо писать код
+ Не бывает избыточной
+ Легко передавать
+ Версионность
+ Можно получить обзор архитектуры проекта
+ Пишется сразу вместе с кодом
- Нельзя положить графику и даже схемы в код
- Сложно поддерживать. Как юнит-тесты. Постоянно нужно следить за актуальностью артефактов.
- Ограничения по пост-редактированию. Не можем приставить к каждому программисту техрайтера, который будет редактировать текст.
- Ограничен круг редакторов.
- Разработчик должен уметь писать хороший код и комментарии. Такой разработчик дороже.
- Нельзя так написать проектную документацию: требования, постановку задачи.
- Бизнес-логику очень сложно документировать в коде.
- Давать всем доступ к коду может быть проблематично
Полный конспект тут: https://github.com/NickVolynkin/teamleadconf-19/blob/master/source/km-meetup.md
Мы тут проводим митап от программного комитета KnowledgeConf. В первой половине записали плюсы и минусы разных подходов к документации и тому, как сохранять знания о проекте.
Часть 3. Самодокументируемый код
+ Документация всегда актуальна
+ Автоматизируется, доставляется в CI/CD
+ Ограничен круг редакторов
+ Мотивирует хорошо писать код
+ Не бывает избыточной
+ Легко передавать
+ Версионность
+ Можно получить обзор архитектуры проекта
+ Пишется сразу вместе с кодом
- Нельзя положить графику и даже схемы в код
- Сложно поддерживать. Как юнит-тесты. Постоянно нужно следить за актуальностью артефактов.
- Ограничения по пост-редактированию. Не можем приставить к каждому программисту техрайтера, который будет редактировать текст.
- Ограничен круг редакторов.
- Разработчик должен уметь писать хороший код и комментарии. Такой разработчик дороже.
- Нельзя так написать проектную документацию: требования, постановку задачи.
- Бизнес-логику очень сложно документировать в коде.
- Давать всем доступ к коду может быть проблематично
Полный конспект тут: https://github.com/NickVolynkin/teamleadconf-19/blob/master/source/km-meetup.md