Comments 13
В идеальном мире идеальные разработчики пишут идеальную документацию. Идеального мира не существует, если вы хотите жить в нем - вы живете наивными иллюзиями.
Не все, даже очень хорошие, разработчики способны кратко и максимально доступно описать все что нужно (за какое-то конечное время). Не все привлеченные со стороны специалисты по работе с доками способны понять что вообще им нужно писать, пока не прочитают... сюрприз, подробную документацию. А это замкнутый круг, который отжирает огромное количество ресурсов на коммуникациях.
В реальном мире, документация может терять актуальность на каждой итерации, быть неполной, запущеной или вообще отсутствовать... и при этом, проект может двигаться и жить.
Вопрос документации, концептуально, решается на уровне стратегий а не артефактов, например, можно писать код таким образом, чтобы он-же и был документацией. Можно хранить доки там-же, где и код, чтобы у элементов вашей кодовой базы и доков было общее версионирование и использовались общие релизные практики.
В конце концов, документацией могут служить все побочные артефакты разработки: комиты, таски, репорты и т. д.
И все это, пришедший со стороны новичок, может назвать "бардаком" и "отсутствующей документацией".
Это я все говорю, как человек который пишет много доков.
Для таких целей подходят системные агалитики, а не разработчики.
И любая доработка идет по принципу - внесли в доку изменения и пометили желтым. Как разработка на проде, все в обычном цвете.
Так себе практика, когда разработчики ведут доку. По мне дак, это не их обязанность, а как следствие и мотивауия страдает.
В моей практике, мне много раз говорили: "мы дадим тебе человека, ты ему скажи что надо делать, он поможет тебе с документацией". Звали разных технических писателей, аналитиков... В итоге я всегда все писал сам. Ну невозможно не-программисту объяснить что он должен написать, чтобы объяснить что-то программисту, не написав доку за него. И это справедливо и нормально для всех кейсов, когда вы делаете что-то чуть более сложное, чем лендинг очередной. Ну или вы работаете в "крупной компании", где половина работы - это надувание щек и очковтирательство: там можно долго играть в эту игру получая стабильную зарплату...
У вас так вышло, потому что вы пошли от обратного.
Сначало пишут доку и продумывают как делать. Потом вы пишите код по доке. Потом на основе доки ваш код тестируют.
А не наоборот.
Инжиниринг - это цепочка промежуточных решений на пути к решению общей задачи. Невозможно описать эту цепочку до того, как задача будет решена технически, это нонсенс. То, что вы пишите, может работать только в каких-то самых примитивных и притянутых за уши ситуациях.
Похоже вам стоит поработать в компании с нормально выстроенным процессом, а не где есть один герой разработчик - единственный носитель знаний.
Я работал в очень разных компаниях, мелких и крупных, продуктовых и сервисных, международных и локальных. Я следовал разным практикам и строил процессы сам с нуля. Ваша попытка апелляции к отсутствию у меня релевантного опыта вызывает улыбку ))) Но я понимаю, "последний аргумент", куда же без него...
Хорошее мнение, многие проходят путь от "зачем нам инструкция, щас так сделаем" до написания собственных инструкций. Многие не любят писать доки или считают это неудобным. Мы для себя выработали процесс, когда все доки пишутся в .md файлах в репозиторий, а vuepress при выкладке собирает это все в красивый spa сайтик и публикует в gitlab pages, итого мы имеем документацию в репозитории и это позволяет легче и проще поддерживать доки, чем целый пулл статей в каком нибудь конфлюенс или Яндекс Вики.
"... На таком проекте куда проще найти информацию ASIS и реализовывать TODO с меньшими рисками пропустить важную особенность системы..."
Реализовывать TODO - это ТоDo и когда он появился? В мои годы этого не было так явно: было ToBe. И ещё, про "куда проще найти инфу AsIs" - да, если твоё личное обследование. Но, не унаследованное.
ЗЫ: с основным тезисом согласен, что ВСЕ документы важны, но ГОСТ сам регламентирует отсутствие (необязательность наличия) важного документа, например, в части ЕСТД, схемы технологической сборки изделия, которую стопудово встретите в академической отрасли средне-специального и высшего учебного заведения, но никак не в конечной промышленности.
Без актуальной доки любой проект при обрастании функционалом превратится в мерзкое легаси, в котором ковыряться будет больно.
Не каждому нравится изучать логику в коде и пытыться догадаться почему тут надо было вообще это делать, что имел ввиду бизнес, когда писался этот код разработчиком и вообще нужно ли оно до сих пор или можно выпилить часть.
А как дело обстоит сегодня с авто-документированием?
Я имею в виду саммари (и много других), в шарпе, например?
что такое ASIS?
Все документы важны