Комментарии 13
Документация бывает разная.
Мне как-то пришлось погружаться в проект, в котором всю документацию писали джуны, собственно 90% коллектива были джуны. Это было что-то типа такого: чтобы провести документ, - нажмите кнопку провести документ, чтобы создать элемент справочника, нажмите кнопку создать, и так 120 страниц.
Толку от такой документации - ноль, такую документацию лучше не писать.
Документацию надо писать всегда, даже когда кажется, что нет смысла. Это дисциплинирует людей. Никто не будет через год писать документацию, если год ее никто не писал.
Например по пунктам:
Когда продукт еще не запущен
Как минимум на середине документация понадобится отделу QA и техписам, чтобы начать писать пользовательскую документацию. А если вы сделаете продукт раньше документации, то вас еще и Support проклянет.
Когда определенная фича или большой раздел находится на этапе проверки гипотезы
А куда делся документ от Product Management? Кто хочет, чего хочет, какие use-case? Где начальная архитектура, чтобы все таки обсудить ее до того, как начать код писать?
Проект или модуль проекта часто переделывается
А как другие отделы узнают, что изменились интерфейсы взаимодействия? Или может быть их модуль теперь вообще не нужен? Как вообще другие программисты узнают, что и почему переделалось?
В больших проектах без документации нельзя. Точка.
Вот чтобы переломить ситуацию и чтобы люди не писали документацию, когда не понимают зачем они в данном конкретном случае её пишут я и написал статью
Насчет того, что через год писать документацию скорее соглашусь, но при этом у меня есть много примеров, когда несколько месяцев и даже лет писали систему и когда стало нужно ее передавать другой команде на сопровождение была написана документация. Так что тут тоже дело в целесообразности -- когда она нужна, её нужно писать, когда не нужна -- не нужно
Насчет документации для отдела QA тоже не соглашусь. Каждая задача, которую делал разработчик и которая передается тестировщику должна быть подробно описана. В таком случае само описание задачи и является куском документации. Тоже самое и с техписами -- если есть потребность на каждую функцию написать пользовательскую документацию, то получается это всего лишь еще один пункт в процессе работы над задачей перед ее завершением
"Куда делся документ от Product Management?" -- тут я тоже глубоко убеждён, что прежде чем разработчик приступает к написанию кода у него должна быть подробно описанная задача в таск трекере. Постановщик может вести для себя какие-то дополнительные документы или просто макеты в фигме с описанием пользовательского пути или всё что угодно. Но у разработчика должна быть декомпозированная и описанная задача, а перед стартом нового блока -- весь перечень задач по новому блоку чтобы спроектировать архитектуру
Насчет сваггеров, по которым взаимодействую 2 отдела, разумеется контракты должны выполняться, но это всё равно не значит, что должна быть написана документация. Есть сваггер -- хорошо, нет сваггера, но договорились как тут надо взаимодействовать и в таске написали сигнатуру метода -- тоже нормально. Сама по себе документация не спасёт от того, что нерадивые смежники изменят API к сожалению, это надо решать на уровне процессов.
А насчет того, как отдел узнает, что их модуль не нужен -- ну тут точно вопрос не в документации, а в управлении выше управления конкретным отделом, это тоже должно делаться на уровне процессов. Будет странно, если разработчик прочитает какой-то кусок документации и узнает оттуда, что его отдел не нужен...
Ещё всегда нравилось, как из пункта аджайл-манифеста по своему желанию люди выбрасывают слово "исчерпывающая" или игнорируют его, делая вывод, что документация в аджайле не обязательна, этакий бантик сверху.
Статья просто бомба) Спасибо автору ✊
Запустить продукт и не иметь документации лучше, чем не запустить продукт, но иметь исчерпывающую документацию.
Лютый популизм! (Продукт без документации -- нонсенс; о какой "исчерпывающей" документации речь, если продукта нет)
И, да, конечно: "программный код -- лучшая документация", -- от пользователей из бухгалтерии отдельное человеческое спасибо!
Ну исчерпывающую документацию по ненаписанному продукту очень даже можно написать еще до того как продукт создан. Компании, работающие с гос заказчиками делают это постоянно, есть даже отдельный этап -- написание исчерпывающего ТЗ и ЧТЗ по ГОСТу.
Так что не согласен с тем, что это популизм, к сожалению это неприятная действительность
А насчет бухгалтерии -- я в начале статьи писал, что рассказываю о всей документации кроме пользовательской, но сам конечно придерживаюсь подхода, что если к интерфейсу нужна документация, то тут всего 2 причины:
1. Либо пользователь недостаточно "опытный пользователь ПК", как он написал в своем резюме
2. Либо интерфейс плохо спроектирован
ТЗ и ЧТЗ, написанные на первом этапе, это не "исчерпывающая" документация! И отнюдь не конечный вариант.
А про отсутствующую документацию Вы в космической или атомной отрасли (ПО) расскажите. (но оно летает и работает)
Ну насчет необходимости документации в производстве ракет и ядерных реакторов думаю никто спорить не будет. Но мы с вами не запускаем ракеты в космос (по крайней мере я не запускаю), в продуктах, которые мы делаем важнее дать пользователям продукт, даже если там будет где-то в глубине один хитрый баг. Самолёт не упадет, реактор не взорвется от этого
Понимаете, чаще у нас есть следующие фазы:
Проект активно развивается, перспективы просто космические, все бегут за морковкой (которая спереди) Но все постоянно меняется, и вот вообще не до документации. Да и зачем писать, все равно все переделаем.
Проект (ну или фаза проекта) близки к завершению. Все забыли про морковку спереди. Все чувствуют морковку сзади. Документация? Какая еще документация! У нас дедлайн на носу! Вот доделаем, и тогда...
Проект (или фаза проекта) доделаны, все выдыхают. Кто с облегчением, а кто, хм.. с иными чувстами. Потому как морковка сзади все-таки настигла.
Пауза? Какая пауза? Мы и так сорвали сроки. Нам и так еще позавчера надо было впрягаться в следующий проект (или фазу). Документация? Ну да... обещали... но вот совсем некогда. И завтра тоже некогда. Да и неинтересно. Да и уже пашем над следующим проектом.
Что, для сдачи проекта документация все-таки нужна? Блин. Ну ладно, щас по-быстрому накидаем. Но совсем по-быстрому. Минимальный объем, чтобы просто "закрыть" этап. Не потому что мы вредные или ленивые. Просто со 100%-й занятостью по новым задачам тратить время (зачастую, уже после рабочего дня) на документацию к уже завершенному проекту - ну такое себе развлечение.
Нужна ли на проекте документация: три признака, что да, ещё три — когда нет