Формализовали плюсы и минусы трёх основных подходов к документированию на проектах.
Мы тут проводим митап от программного комитета KnowledgeConf. В первой половине записали плюсы и минусы разных подходов к документации и тому, как сохранять знания о проекте.
Часть 2. Долго готовим документацию, потом пишем код
+ Сохранность
+ Доступность
+ Версионность
+ Ускоряем интеграцию со внешними командами, поставщиками и т.п.
+ Культурный бонус: всех приучили писать доку
+ Устанавливаем общую терминологию
+ Уменьшаем ошибки проектирования, потому что пока пишем, всё продумываем на несколько раз
+ Нетехнические люди могут читать документацию, если она написана человеческим языком
+ Иммунитет к автобусному фактору
+ Разработка быстрее, как от TDD
+ Проще отдавать проект заказчику
+ Проще внедрять
- Дорого по деньгам и времени
- Документация устаревает
- Читать всю доку дольше, чем задать один вопрос эксперту
- Удлиняет релиз, все ждут документацию
- Скучно писать документацию
- Документацию можно потерять! Человек ушёл и забрал все свои файлы.
- Не надо писать красивый и понятный код, потому что документация же всё объяснит
- У разработчика нет свободы выбирать технические решения
- Заказчик вносит коррективы. Если дока не меняется — продукт не попадёт в настоящие требования.
- Если документация и код разделены, появляется расхождение.
Полный конспект тут: https://github.com/NickVolynkin/teamleadconf-19/blob/master/source/km-meetup.md
Мы тут проводим митап от программного комитета KnowledgeConf. В первой половине записали плюсы и минусы разных подходов к документации и тому, как сохранять знания о проекте.
Часть 2. Долго готовим документацию, потом пишем код
+ Сохранность
+ Доступность
+ Версионность
+ Ускоряем интеграцию со внешними командами, поставщиками и т.п.
+ Культурный бонус: всех приучили писать доку
+ Устанавливаем общую терминологию
+ Уменьшаем ошибки проектирования, потому что пока пишем, всё продумываем на несколько раз
+ Нетехнические люди могут читать документацию, если она написана человеческим языком
+ Иммунитет к автобусному фактору
+ Разработка быстрее, как от TDD
+ Проще отдавать проект заказчику
+ Проще внедрять
- Дорого по деньгам и времени
- Документация устаревает
- Читать всю доку дольше, чем задать один вопрос эксперту
- Удлиняет релиз, все ждут документацию
- Скучно писать документацию
- Документацию можно потерять! Человек ушёл и забрал все свои файлы.
- Не надо писать красивый и понятный код, потому что документация же всё объяснит
- У разработчика нет свободы выбирать технические решения
- Заказчик вносит коррективы. Если дока не меняется — продукт не попадёт в настоящие требования.
- Если документация и код разделены, появляется расхождение.
Полный конспект тут: https://github.com/NickVolynkin/teamleadconf-19/blob/master/source/km-meetup.md