Как формировать документацию в живом проекте?

Всем привет! 


Хотел бы обсудить сложившуюся ситуация и как то определится с планом действий в этом направлении. Так что буду признателен за ваши советы, ваш интеллект и ваш опыт.

Постараюсь изложить все супер кратко и доходчиво, а уже в комментариях с заинтересованными лицами постараюсь по существу обсудить все более детальней.

Короче говоря — у нас есть проект Х который уже существует более 6 лет.
Он живой, на нем бегает около 200/300к пользователей и в нем идут постоянные доработки и развивается существующего функционал.

Есть большое желание проект Х переписать на новую архитектуру. Возможно даже улучшить или полностью переосмыслить/доработать ранее написаный функционал. Некоторые вещи уже были переписаны и даже живут как отдельные микросервисы.

Но существует проблема с документацией. Она как бы и есть, но проще сказать что её вовсе нет. По сколько в некоторых местах она просто устарела, а в других местах на каком то этапе перестала наполнятся. Можно сказать что ядро проекта хорошо документировано и поддерживается, но это только 15-20% от общего функционала.

Собственно, хотел бы услышать от вам советы, или получить рекомендации работы в этом направлении, возможно какие то best practice ссылочки может.

Лично мои мысли, а возможно в дальнейшем и действия в этом направлении — планирую поверх процесса разработки наложить модель работы с документацией таким образом, что бы если команда сталкивается с написанием нового функционала или доработкой старого, она сперва должна разобрать написаный код или отразить его в документации. Думаю что стоит рассматривать должность technical writer, но я не представляю как его интегрировать в команду, знания по проекту ему можно передавать месяцами. К тому же, хотелось бы интегрировать такого человека более менее безболезненно в плане продуктивности всей команды. 



Ваши мысли/мнения/опыт/best practice по этому поводу?

👍ПодобаєтьсяСподобалось0
До обраногоВ обраному0
LinkedIn
Дозволені теги: blockquote, a, pre, code, ul, ol, li, b, i, del.
Ctrl + Enter
Дозволені теги: blockquote, a, pre, code, ul, ol, li, b, i, del.
Ctrl + Enter

Полезны обзорные документы на основные _крупные_ компоненты, интерфейсы и их взаимодействие. Эти вещи редко меняются.

А всё остальное — смотреть в коде.

Если не пытаться сразу искать решение, а порассуждать как оно впринципе бывает в общем, то выглядит так что есть всего два подхода: документация статическая и динамическая (для простоты можно считать статической ту, под которую нужно подгонять код, а динамической ту, которая подгоняется под код).

1) Статическая либо не меняется вовсе, либо выбрасывается и заменяется новой, с кодом в этом случае все примерно так же. Минусы очевидны: кто-то должен ее писать еще и понятной для всех, без противоречий и прочей фигни, ведь любая ошибка будет очень дорогой, из всех возможных вариантов того кот будет это делать подходит больше всего БА, который раньше был программистом, причем программистом лучше среднего, мне кажется это крайне редкая ситуация, которую достигнуть можно только волей случая, если будет заниматься кто-то другой, то скорее всего получится то, что сейчас у себя на проекте видит каждый: документация это таски в джире, получить какой-то практический толк с такой документации маловероятно. Приходим к тому что этот способ — это компромис между качеством документации и ценой

2) Динамическая документация должна быть написана/отредактирована, после того как код уже готов. Сразу видно что это всевозможные тесты, которые при определенных усилиях со стороны разработчиков будут документацией для всех (по факту bdd). Так же написание/редактирование документации понятным текстом в конфлюенсе, обычно программисты пишут так что ценность такой документации низкая и фактически сделана для галочки. Комментарии в коде, хоть они имеют очень много недостатков и мало кто может написать их правильно, а не прокапитанить, они все же могут быть хоть какой-то документацией, они всегда обязаны быть динамическими или вред от их устаревания может быть очень большим. Ну и автогенерируемая документация, из самых простых примеров это встроенные механизны, позволяющие генерировать на вебсервисе страничку с ее апи. Т.е. тут есть два способа: ручной труд и автоматизация. С ручным все понятно: переваливание ответственности на программиста, и рано или поздно провал с его стороны. С автоматизацией же все выглядит куда перспективней. Тестируемый код, юнит тесты, интеграционные тесты, системные тесты, нагрузочные тесты, секюрити тесты и многие другие могут дать хорошую гарантию того что то что было заложено изначально до сих пор работает как задумывалось. А чтобы получить больше инфы вроде той что генерируется по контрактам вебапи нужно очень тщательно продумывать как писать код. У меня такое получилось ровно один раз, потому что это был круд, я писал все один и ооп головного мозга, так что я рефлексией обошел всесь солюшен вдоль и поперек и из исполняемых команд уже не составило труда сгенерить документацию по значимым операциямю Но чем запущеней проект и чем больше в нем разных штук, тем сложнее это сделать

итого надо самое лучшее из двух подходов выбрать, а не как обычно бывает самое худшее

Возможно даже улучшить или полностью переосмыслить/доработать ранее написаный функционал.

По-моему, это та печка от которой надо танцевать.
Ибо если старый фукнционал должен быть точно сохранен, то скорее всего, пиши пропало.
У меня был опыт, когда пытались финансовые вычисления перевести на новый движок, но из-за того, что новый движок считал точнее, результаты отличались от старых — т.е. нужно было бы признать, что старый софт считал неточно. А потому новый проект похоронили.

Что же касается, собственно, вопроса по документации — то:
1. Комментарии в коде
2. Обширные тесты (тестирующие не только технически отдельный метод, но и business use cases. QuantLib в этом отношении хороший пример — на каждый класс — будь то фин.инструмент, pricing engine, модель — там найдется тест).
3. Интеграция RedMine (или Jira) с репозиторием, чтоб каждый коммит в репозиторий отражался в redmine в соответстующем issue.
4. Project wiki (ни в коем случае не вести документацию в ВОРДе)

Взять разработчика с навыками technical writer. Компромисса не существует (точнее оно не работает). Дополнительная нагрузка на бюджет, но другим образом не получить нормальной эффективности. (на правах думы-думной, то же есть проект многолетний и документированный никак).

Разложить проект на элементы, наложить их на график потенциальных изменений, что бы определить приоритетность. Что реже меняется и чаще используется — с тем работать в первую очередь и далее по «связям» (распутываем клубок). Сможет откомментировать код (или разработать формат и регламент комментирования), сформировать справочную документацию и прочее...

АПД. Лучше всего, если взять архитекта (и скептика), хотя бы на 2-3 месяца. Станет ясно насколько вообще оправдано изменение архитектуры, сколько это будет стоить и если — да, то когда и как все делать.

1. Писал комментарий ниже — dou.ua/...​rums/topic/25830/#1472880
Вопрос остается актуальным)

2. С архитектором мы осбуждали этот момент и пришли к выводу что это очень здравая и рентабельная (в плане будущей инвестиции) идея, по сколько в дальнейшем все будет только усложнятся в этом напралении. Начнутся проблемы с маштабированием, с поиском и интеграцией разработчиков в проект, тестированием проекта (с этим сейчас уже есть сложности), и ряд других вещей. Плюсы разве что только в том, что на это не затрачивается время и деньги, но если честно, это даже не плюс.

3. Как вы справляетесь с проектом без документации?))

Как вы справляетесь с проектом без документации?))

никак. Сейчас развитие проекта слегка в непонятном режиме. Собираются «разгрести завал тикетов» и сесть за описание )) учитывая что с проекта в пользу другого проекта убрали людей... судьбу этого начинания я предсказать не берусь.

Плюсы разве что только в том, что на это не затрачивается время и деньги, но если честно, это даже не плюс.

обычная история, но для компании важно не профукать момент, когда эта «экономия» начинает показывать отрицательный баланс.

... а вообще, если уже задаешься такими вопросами, это — круто. Просто, попробуй представить, что ты — владелец/совладелец софтверной компании и тебе нужно распределять ресурсы. Куда бы ты больше вложил и насколько эффективными были бы эти вложения в краткосрочной и долгосрочной перспективе. Если нужно, пиши в личку, постараюсь проконсультировать по конкретному кейсу.
>>

Хотел бы обсудить сложившуюся ситуация и как то определится с планом действий в этом направлении.

хочешь иметь план, для начала поставь цель

Согласен с двумя предыдущими комментаторами. В Основной мысли. Зависит от того, какую цель нужно достичь. Документация ради документации в принципе не имеет смысла. Как и написание кода только ради написания кода. Саппорт, развитие проекта, эволюшен дизайн. Есть бест пректис для множества конкретных кейсов. Например, если большая команда и тебе нужен самоконтроль над людьми, то себя всегда оправдывает дев тест репорт. Что дев сделал баг-фичу, очень коротко описал как проверил, снял скрин. Примеры можно приводить бесконечно. По улучшению или сетапу процессов. и т.д. не зная конкретный сетап и дальнейшие планы по развитию проекта сказать можно немного.

У нас у каждого были свои «шпаргалки», а много в «головах».
Наиболее частой проблемой была стыковка между разработчиками — много дергали в мессенджерах спрашивая одно и тоже с периодичностью в неделю.
Когда появился свой Gitlab сервер, все перенесли в Wiki, потом начали править друг друга в смежных областях.
Потихоньку опеределились с наиболее частыми вопросами, которые возникают между программистами, вот эти разделы проработали более полно. Это легко определить, если кто-то спрашивает «как у тебя это работает?» значит это нуждается в докуентировании.
Сейчас вопросы если и возникают, то только по самым новым фичам, которые только сделаны и сразу интегрируются для тестирования.
Сейчас, если день не задался или нет напряга, то для расслабления мозга дополняю документацию.

на нем бегает около 200/300к пользователей

Начни с плана эвакуации :)
А если серьёзно, задайся вопросом КОМУ это нужно. Потому что именно им решать, чего они собственно хотят видеть документированным, или хуле им не ясно

Вообще, это мне нужно.
Даже владелец продукта особо не думает по этому поводу и считает что проект нормально себя чувствует. Но я считаю что эффективность управления проектом начинает сильно страдать из за отсутствия документации по проекту, по сколько никто не знает как именно работает определенный функционал.

Даже владелец продукта особо не думает по этому поводу и считает что проект нормально себя чувствует.

Ну тут есть два варианта:
1) Бросай проект. Вероятно он в стагнации, а то и развернул клюв в сторону упадка.
2) Требуй прав собственности и вырази готовность вести проект. В то время как владелец будет просто получать ренту и не особо бебать себе мозги техническими рисками. А остальные риски ты согласуешь или уведомишь.

Критерий выбора: проект тебе нравится, ты готов его вывести в стадию если не звёзд, то звёздочек, чтобы была категория пользователей которые вполне довольны. Иначе говоря, проект будет звездой в твоём портфолио (по крайней мере есть такой шанс).
Если же ты его вытягивать не готов — выкинь каку и уходи в следующий. Можешь остаться как поддержка, с оговоренным объёмом работ и оплатой, или почасовкой.

Если владелец не в курсе дел, он вынужден будет согласиться на любое твоё решение. Или проекту пистец, и маркетинг быстро покажет отток клиентов. Уверен, уже показывает, просто владельцу впадло смотреть и огорчаться. Но если ткунть мордочкой будет более сговорчивым.

Объясню, что не так с документацией: после её появления, чем качественнее она будет — тем проще сделать все части проекта взаимозаменяемыми. Особенно тебя. А чем более стандартны составляющие, тем дешевле они на рынке. Особенно ты. Потому надо сформировать себе цену и уникальную роль ДО ТОГО, как ты сделаешь все остальные издержки более низкими. Тогда, и только тогда, ты получишь доход.

В противном случае доход получит владелец, а тебя просто кинут на бабло — для человека, который нихрена не смыслит, твоя работа покажется простой, все твои решения очевидными, а ты типа нихера не делал. В то время как НАСТОЯЩАЯ твоя работа, все пробы и ошибки, все риски и победы — останутся за пределами документации, там будет только готовый результат на блюдечке. Притом в открытом виде, его владелец может просто отдать какому-нить аутсорсеру за 3 копейки с позволением гробить то что ты создал, и тебя же обвинять.

Решение типа цуг-цванг: ты ведёшь документацию, но делаешь это секретно. За счёт этого выигрываешь время, тратишь его мало, владельцу про то ни слова. Раздуваешь из мухи слона при случае, и так добиваешься бабла.
Но я тебе этого не советую, это де-факто враждебные отношения, грубо говоря если ты владельцу за что-то мстишь, и отношения в дальнейшем разрываешь, или оставляешь в этом положении.
Это НОРМАЛЬНО если ты ведёшь отношения не с физическим лицом, а с юридическим, особенно с бюрократией. С ними отношения всегда строятся по принципу «хочешь мира — готовься к войне».

Мне кажется это заслуживает уже на отдельную ветку и отдельного обсуждения, по сколько мне не особо интересна психология отношений между владельцем продукта и командой, в данном случаи.
Здесь я скорее пытаюсь разобраться или построить какую то свою методологию по формированию документации в сложившихся условиях, по сколько, вижу в этом ряд хороших плюс и дальнейшую перспективу развития проекта в целом.

Всё зависит от того, какую вы преследуете цель при написании документации. Если вы доки пишете для других членов команды, то пишите всё как можно подробнее, вдавайтесь во все мелочи. Очень хорошо, если у вас будет полное описание всех 100500 зависимостей, которые постоянно меняются и куда-то движутся. Прочтение такой документации вызовет глубокое понимание вашей незаменимости в проекте, и стимулирует появление непреодолимого желания повысить вам зарплату. Если вам нужно написать мануал к библиотекам, которые будут юзать какие-то левые люди, то всё должно выглядеть максимально просто и интуитивно понятно. Дока должна быть линейной, очевидной, и умещаться на 3 страницы, или типа того.

Тут треба розібратись про яку саме документацію йде мова:
1. Документація функціоналу продукту (опис всіх фіч на високому рівні абстракції)
2. Документація коду — вхідні вихідні параметри функцій, як використовувати те чи інше API і тому подібне.

Будемо виходити з того, що ви запитували про пункт #2.
1. Максимально коментувати код в форматі Doxygen. Що робить це класс. Які параметри приймає кожен з методів на вхід і які йдуть на вихід, що повертається в результаті, які ексепшини викидаються і в яких кейсах.
2. API, UML діаграм, всілякі описи помістити в папку doc (чи щось подібне) І залити в репозиторій. Є варіант розміщувати це все на Confluence чи подібній системі контролю документів.
3. Писати семпли. Ніщо так не допомагає в розборі коду як хороший приклад, який народний показує що і як.

Да, основное хранилище документации это Confluence.

Скажите, а как грамотно это стояло бы все реализовать в плане структуры документации? Документация должна быть модульной? Как совместить в одну структуру Doxygen + UML + Confluence?

Например, в голове статьи я бы размещал бизнес описание, далее у меня бы был прототип, возможно в inVision, затем я бы описывал front-end часть и после этого back-end с Doxygen + UML?

Какая тогда должна быть глобальная структура такой документации? Возможно вложеность в виде дерева проекта, где каждая ветка эта статья и подстатьи? Но в Confluence это нужно все перелинковать и как бы есть такие вещи которые протянуты через весь проект.

Насчет Confluence... как то наводили порядок с документами службы поддержки, мне конфлюэнс показался «неудобным». То есть до идеала он не дотягивает. Возможно я просто не умею его готовить.

То что ты спрашиваешь называется «как убить проект бебанутой бюрократией». Правильный ответ — никак.

Ключевой вопрос всегда звучит «КТО?» — то есть кому это нужно.
Далее вопрос «ЗАЧЕМ?» — и этот вопрос задаётся только этому самому КОМУ. И никому больше. Включая себя.
Следующий вопрос — В КАКОЙ ФОРМЕ? И этот вопрос ты решишь практически самостоятельно.
Последний вопрос — С КЕМ СВЯЗЫВАЕТСЯ? И здесь придётся документировать всё на уровне черновиков, и навсегда в таком уровне оставаться. Потому что связи должны быть живыми, готовыми к изменениям постоянно. Вплоть до контактов людей с поддержанием их в актуальном состоянии, и списков ответственных за каждую часть.

Заметь, здесь выведены за скобки стимулы и риски. То есть нужно ответственное лицо, которому за это будут так или иначе платить. Это вопрос выживания проекта, и этого лица на проекте.

А почему вы считаете что проект может стать бебанутой бюрократией, вы видете в этом какие то риски как разработчик?
Для вас как для разработчика будет затруднительно следовать какому то воркфлоу который включает в свой процесс и наполнение документации?

Підписатись на коментарі