Вы пришли на новый проект и что же первым вам выдадут заботливые коллеги для начала погружения? Правильно, несколько документов со словами «Вот, почитай, что не понятно потом спрашивай.». И тут по вашей спине должен пробежать холодок, потому что вы вспомнили как читали такой документ, перечитывая разделы снова и снова успокаивая себя, что дальше будет понятнее, но увы.
Некоторые из вас скажут, что это нормально, и не нужно чувствовать себя никчемным, потому что не поняли документ с первого раза, и для погружения нужно больше времени и документов. И вы будете правы, но я хочу остановиться на документации и почему она так важна для становления специалиста.
Я пришел на свой первый проект и только спустя несколько лет я понял как мне тогда повезло. Отличительной чертой проекта было то, что все процессы были заботливо описаны аналитиками в документации, разработчиками в системе, тестировщиками прописаны все возможные сценарии.
Последующие проекты оказались самыми типичными в отношении к документации. В лучшем случае описано только первое ТЗ по первому MVP, так что по сути потомкам не оставили никаких артефактов.
Подобное не понимание важности документации приводит к некоторым очевидным и не очень последствиям:
Никогда не знаешь ASIS.
Увеличенные трудозатраты на задачи.
Приходится выделять больше времени на поиски информации и тех кто знает и главное готов рассказать то что нигде не описано.«Наша песня хороша начинай сначала»
Выше необходимость снова изучать один и тот же процесс. Высока вероятность что либо ты в прошлый раз не все узнал или за это время кто-то доработал процесс и ты снова не в курсе изменений.Цена ошибки высока.
Некоторые критически важные условия выявляются только на поздних этапах реализации. Что означает высокую стоимость ошибки. И вы никогда не сможете предугадать сколько будет ошибок случившихся, только потому, что о них нигде не было и слова, а люди не могу знать всего.
На выходе мы получаем проект, с частыми багами, выявленными на более поздних этапах, сотрудниками, которые никогда до конца не уверены что предусмотрели все условия поведения системы. И самое печально быстрое выгорание и усталость от такой работы, когда ни в чем нельзя быть уверенным.
В ином случае, когда на проекте присутствует культура ведения документации, то наблюдаются самые неожиданные плюсы:
Есть понимание ASIS
Самостоятельность.
Со временем погружения в проект необходимость консультироваться с коллегами снижается.Рост компетенций
Все больше времени отводится на обсуждение решения интересных задач.Команда с вам надолго.
Наличие качественной документации может стать важной причиной для сотрудника не покидать проект. Ведь в большом и страшном мире он может оказаться на совсем другом проекте и захочет вернуться к вам обратно.Заменяемость.
Знания не распределены по людям и их уход с проекта будет не так чувствителен.
На таком проекте куда проще найти информацию ASIS и реализовывать TODO с меньшими рисками пропустить важную особенность системы. Доступна информация по новым доработкам системы, которые могли внести за то время пока вы не работали с той или иной частью функционала.
Путь пренебрежения к документации начинается со слов «Потом опишем, сейчас не до этого» только вот это "потом" не приходит и все начинает заваливаться. Или так «Да кому нужна эта документация, мы и так тратим много времени на ее описание». Только вот потом будет куда сложнее выделить достаточно ресурсов для актуализации процессов проекта.
Не забывайте о важности документации и не ленитесь ее писать, когда вы нашли что-то не описанное. Поверьте, это окупается и в личном росте и проектной, а значит командной работе.
Комментарии (12)
strokoff
15.01.2023 16:41+2Хорошее мнение, многие проходят путь от "зачем нам инструкция, щас так сделаем" до написания собственных инструкций. Многие не любят писать доки или считают это неудобным. Мы для себя выработали процесс, когда все доки пишутся в .md файлах в репозиторий, а vuepress при выкладке собирает это все в красивый spa сайтик и публикует в gitlab pages, итого мы имеем документацию в репозитории и это позволяет легче и проще поддерживать доки, чем целый пулл статей в каком нибудь конфлюенс или Яндекс Вики.
AzIdeaL
15.01.2023 18:03"... На таком проекте куда проще найти информацию ASIS и реализовывать TODO с меньшими рисками пропустить важную особенность системы..."
Реализовывать TODO - это ТоDo и когда он появился? В мои годы этого не было так явно: было ToBe. И ещё, про "куда проще найти инфу AsIs" - да, если твоё личное обследование. Но, не унаследованное.
ЗЫ: с основным тезисом согласен, что ВСЕ документы важны, но ГОСТ сам регламентирует отсутствие (необязательность наличия) важного документа, например, в части ЕСТД, схемы технологической сборки изделия, которую стопудово встретите в академической отрасли средне-специального и высшего учебного заведения, но никак не в конечной промышленности.
stackjava
15.01.2023 20:05Без актуальной доки любой проект при обрастании функционалом превратится в мерзкое легаси, в котором ковыряться будет больно.
Не каждому нравится изучать логику в коде и пытыться догадаться почему тут надо было вообще это делать, что имел ввиду бизнес, когда писался этот код разработчиком и вообще нужно ли оно до сих пор или можно выпилить часть.
moroz69off
16.01.2023 12:25А как дело обстоит сегодня с авто-документированием?
Я имею в виду саммари (и много других), в шарпе, например?
i360u
В идеальном мире идеальные разработчики пишут идеальную документацию. Идеального мира не существует, если вы хотите жить в нем - вы живете наивными иллюзиями.
Не все, даже очень хорошие, разработчики способны кратко и максимально доступно описать все что нужно (за какое-то конечное время). Не все привлеченные со стороны специалисты по работе с доками способны понять что вообще им нужно писать, пока не прочитают... сюрприз, подробную документацию. А это замкнутый круг, который отжирает огромное количество ресурсов на коммуникациях.
В реальном мире, документация может терять актуальность на каждой итерации, быть неполной, запущеной или вообще отсутствовать... и при этом, проект может двигаться и жить.
Вопрос документации, концептуально, решается на уровне стратегий а не артефактов, например, можно писать код таким образом, чтобы он-же и был документацией. Можно хранить доки там-же, где и код, чтобы у элементов вашей кодовой базы и доков было общее версионирование и использовались общие релизные практики.
В конце концов, документацией могут служить все побочные артефакты разработки: комиты, таски, репорты и т. д.
И все это, пришедший со стороны новичок, может назвать "бардаком" и "отсутствующей документацией".
Это я все говорю, как человек который пишет много доков.
stackjava
Для таких целей подходят системные агалитики, а не разработчики.
И любая доработка идет по принципу - внесли в доку изменения и пометили желтым. Как разработка на проде, все в обычном цвете.
Так себе практика, когда разработчики ведут доку. По мне дак, это не их обязанность, а как следствие и мотивауия страдает.
i360u
В моей практике, мне много раз говорили: "мы дадим тебе человека, ты ему скажи что надо делать, он поможет тебе с документацией". Звали разных технических писателей, аналитиков... В итоге я всегда все писал сам. Ну невозможно не-программисту объяснить что он должен написать, чтобы объяснить что-то программисту, не написав доку за него. И это справедливо и нормально для всех кейсов, когда вы делаете что-то чуть более сложное, чем лендинг очередной. Ну или вы работаете в "крупной компании", где половина работы - это надувание щек и очковтирательство: там можно долго играть в эту игру получая стабильную зарплату...
stackjava
У вас так вышло, потому что вы пошли от обратного.
Сначало пишут доку и продумывают как делать. Потом вы пишите код по доке. Потом на основе доки ваш код тестируют.
А не наоборот.
i360u
Инжиниринг - это цепочка промежуточных решений на пути к решению общей задачи. Невозможно описать эту цепочку до того, как задача будет решена технически, это нонсенс. То, что вы пишите, может работать только в каких-то самых примитивных и притянутых за уши ситуациях.
stackjava
Похоже вам стоит поработать в компании с нормально выстроенным процессом, а не где есть один герой разработчик - единственный носитель знаний.
i360u
Я работал в очень разных компаниях, мелких и крупных, продуктовых и сервисных, международных и локальных. Я следовал разным практикам и строил процессы сам с нуля. Ваша попытка апелляции к отсутствию у меня релевантного опыта вызывает улыбку ))) Но я понимаю, "последний аргумент", куда же без него...
stackjava
Тогда бы вы не стали писать такую глупость: