Заказчик требует документировать ПО.

Было такое. Обещай что будет сделано, если будет приставать, говори что в процессе. И ничего, ессно, не делай.

Когда-нибудь он сам забудет.

отличный способ потерять всех клиентов и в особых случаях получить по лицу)

самодокументируемого кода

Это индусский буллшит.

Про блок-схемы для алгоритмов уже ответил.

Должна быть описана общая архитектура, диаграммы к ней, интерфейсы, по которым взаимодействуют компоненты, описаны данные, описан стек от и до, внутренняя архитектура приложений тоже должна быть ± описана. Внутри хотя бы чисто формально должны быть откомментированы модули и методы, ибо нет, именование не решает. Программа минимум: интерфейсы, данные, назначение каждого компонента в проекте.

Нифига себе, ленин что-то адекватное написал! Раз в год и палка стреляет.

Это индусский буллшит.

по факту да, а формально вариант документации)

Должна быть описана общая архитектура, диаграммы к ней

Какие диаграммы? Их очень много. сиквенс диаграммы? диаграммы классов? деплоймент диаграммы? стейт диаграмммы? нужны все существующие?

А что делать в случае если это стартап и вся эта документация имеет срок актуальности не более чем на один спринт? (пару недель)

Вплоть до блок-схем алгоритмов. Требует описывать архитектуру словами и картинками

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

А так, при разработке кода вы и так его документируете в коде (если не говнокод), странно, что вас это волнует.

А вы их собрались составлять в нерабочее время?

Работаю в команде разработчиков из пяти человек. Пишем ПО на заказ…

Раньше обходились просто комментариями в коде. А теперь такие требования бесят, учитывая, что на оплате это никак не сказывается.

А вы просто в команде обычным разработчиком работаете или в должности повыше и участвуете в переговорах с заказчиком? Если первое, то вам нужно просто поговорить со своим начальством и объяснить, что от вас требуют сделать дополнительную работу и в прежние сроки вы теперь не укладываетесь, поэтому вам нужно больше времени и соответственно большая оплата за большее время. Обсуждать это с заказчиком бессмысленно. Если же вы участвуете в переговорах с заказчиком, то должны объяснить ему то же самое и потребовать увеличить сроки и конечную оплату. Требования заказчика о документации вполне здравые, но в любом случае делать дополнительную работу бесплатно вы тоже не должны.

Зависит от внутренних и внешних требований. Архитекторы всякое рисовали, я никогда дальше схемки со всеми сервисами в системе (приложения, бд, шины данных, внешние системы etc.) и стрелочками, слава Сатане, не заходил. Мы же с точки зрения разработчика говорим, а если тебе самому нужно диаграммы фигачить приходится, то проект заведомо небольшой и хватит того, что описал я.

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

Раньше обходились просто комментариями в коде

ТС не удосужился рассказать, что такое они пишут, если что-то сложное, ясное дело, нужно составлять документацию не только кода, но и архитектуры.

А может отсутствие документации — своеобразный метод создания постоянных заказчиков в ущерб другим, кто его знает.

Увольняться. Это херовый стартап, ты работаешь с тупорыми обезьянами.

Но, если он хорошо финансируется, а ты в доле, то оставаться и менять ситуацию.

Зависит от внутренних и внешних требований.

Которые должны быть зафиксированы в договоре в случае аутсорса. Собственно вот и ответ, заказчик решает какая именно документация ему нужна.

Увольняться. Это херовый стартап, ты работаешь с тупорыми обезьянами. Но, если он хорошо финансируется, а ты в доле, то оставаться и менять ситуацию.

Зачем менять ситуацию? Все идеально, это стартап, сегодня так завтра иначе.

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

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

Ты же понимаешь что документацию нужно писать не потому что документацию нужно писать, деды писали и мы пишем….

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

Требования от техлида, так что вряд ли там вопрос в формализме.

метод создания постоянных заказчиков

Это job security называется. Так делают не только по отношении к внешнему заказчику. Многие разрабы таким образом добиваются минимального bus factor и завязывают на себе проекты, тем самым повышая свою ценность в компании. Причём технически некомпетентное руководство даже не видит тут подвоха зачастую.

Это уже детали. Некий базовый уровень всё равно есть.

Ты предлагаешь работать по принципу «без лоха и жизнь плоха»? Если заказчик не сечёт, это ещё не повод его кидать.

Если горизонт планирования — две недели, это означает, что все вокруг идиоты.

Ты предлагаешь работать по принципу «без лоха и жизнь плоха»? Если заказчик не сечёт, это ещё не повод его кидать.

Тебе ничего не мешает спросить у заказчика нужна она ему или нет и сколько это будет стоить.

Если горизонт планирования — две недели, это означает, что все вокруг идиоты.

А какой по твоему горизонт планирования в стартапах в которых после каждого спринта идет анализ результатов и следующий спринт строится на этих выводах?

Новые люди вливаются в проекты неизбежно, о чём речь вообще? Ты сам говоришь, у тебя стартап. В стартапах текучка — это раз, у тебя нет времени на то, чтобы новые люди вникали в ваш говнокод месяцами — это два.

Новые люди вливаются в проекты неизбежно, о чём речь вообще? Ты сам говоришь, у тебя стартап. В стартапах текучка — это раз, у тебя нет времени на то, чтобы новые люди вникали в ваш говнокод месяцами — это два.

Вообще нет, команда может существовать годами и не меняться. Особенно если это аутсорс.

В этом случае ты обязан ему пояснить возможные последствия его решения.

да, это будет честно. но решение должен принимать он.

Максимально возможный в конкретной ситуации. Про беклог слышал, про архитектуру? У тебя всё равно майлстоуны по проекту должны быть расписны.

Ты реально описываешь конченых обезьян. Да, таких полно, но это не вовсе не норма.

Особенно если это аутсорс

Значит, кидаем на документацию, заказчика. 👍

Максимально возможный в конкретной ситуации. Про беклог слышал, про архитектуру? У тебя всё равно майлстоуны по проекту должны быть расписны.

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

Ты реально описываешь конченых обезьян. Да таких полно, но это не вовсе не норма.

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

Значит, кидаем на документацию, заказчика. 👍

Я уже объяснил как не кидать заказчика, не шлангуй.

Свои быдлозамашки оставь в подъезде из которого вылез.

Никакой заказчик в своем уме не откажется от исполнителя с кучей рабочего кода да еще и без документации.

Свои быдлозамашки оставь в подъезде из которого вылез.

Сказал человек который предлагает иметь заказчиков, таким как ты место в клетке.

Никакой заказчик в своем уме не откажется от исполнителя с кучей рабочего кода да еще и без документации.

ага, просто машину тебе подожгут.

Я описываю профессиональную разработку, ты описываешь «тяп-ляп».

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

Вопрос был

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

Я рассказал рабочий вариант как. Ты в этом треде что делаешь?

Не шлангую, а сарказмирую. Я даже эмодзи добавил, Шелдон.

Я описываю профессиональную разработку, ты описываешь «тяп-ляп».

Профессионал понимает зачем он что то делает, это основное отличие профессионала.

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

Но эти 20% кто то должен определить и сказать что вот это нам нужно для того что бы….

Требует описывать архитектуру словами и картинками.

Правильно делает.

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

Не надо заказчика посылать.

У вас в команде есть архитектор или и/о архитектора? Кто-то, кто принимает решения о верхнеуровневой структуре вашего решения?

Надо взять, и таки описать верхнеуровневую архитектуру вашего решения. В описании использовать UML. Какие есть модули, каково предназначение (сфера ответственности) каждого из модулей, как модули друг с другом связаны и взаимодействуют в процессе работы системы, каким образом ваша архитектура обеспечивает выполнение ключевых требований заказчика, какие файлы исходного кода соответствуют описанным модулям, какова схема деплоя, какие данные хранятся персистентно (состав данных, схема БД), какие API ваша система предоставляет внешнему миру, какие внешние сервисы ваша система может использовать (и вообще требования к окружению, в котором система работает), какие используются third-party библиотеки. Желательно уточнить у заказчика, какие моменты его больше всего интересуют, и постараться подробнее раскрыть их в архитектурном документе.

Раньше обходились просто комментариями в коде. А теперь такие требования бесят, учитывая, что на оплате это никак не сказывается.

Это не должно сказываться на оплате, это должно сказываться на трудоемкости: подготовка внятного документа - это таки работа. И соответственно на сроках завершения проекта и его стоимости. Ничего драматичного, но в зависимости от сложности системы можно человекодней 10-15 накинуть совершенно спокойно.

Обещай что будет сделано, если будет приставать, говори что в процессе. И ничего, ессно, не делай.
Когда-нибудь он сам забудет.

Детский лепет. Заказчик согласует с тобой конкретный срок завершения этой работы (или её первого этапа - когда будет готов черновик документа), затем действует стандартная практика «поощрений» за нарушение сроков.

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

Иногда этим человеком будешь ты. Если видишь, чтобы всё плохо, берёшь инициативу в свои руки.

Так работает только в твоих влажных постсовково-эсэнгэшных фантазиях. Реальный мир он другой.

Прям буквально каждую функцию описывать нужно?

Документации кода не нужна (за редким исключением), нужна документацию функциональности, бизнес правил, описание алгоритмов от заказчика, т.е. это просто ТЗ фиксированное в wiki, плюс после реализации там же оставить ссылки на места в коде где реализованы те или иные вещи.
Если получает слишком много объектов/состояний то может понадобиться добавить диаграммы (диаграммы классов, последовательностей или marble diagram, etc).
Со временем код меняется, рефакторится, дописываются новые бизнес правила, но в 95% случаев в своем основании он все еще несет изначальную функциональность которая была описана в ТЗ много лет назад и это позволяет новой группе разработки разобраться что там происходит (очень часто выйти на связь с исходными авторами невозможно, или они уже все забыли).

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

А примеры где так пишут доку это наверное в любом «энтерпрайзе» (например жаба и банки). Я кинуть пример не могу, для своих pet проектов так доку не пишу, это бессмысленно и трата времени. Дока нужна для взаимодействия людей/команд, передачи компетенций, в общем там где проект живет дольше трудовых отношений разработчика и нанимателя.

Не «другой», а разнообразный.

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

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

Но далеко не все хипстеры, очень часто документация оформляется отдельными документами и даже проходит приёмку.

Это работа с рисками. Если завтра документация тебе не нужна, это не значит, что она не нужна в принципе. Через год-другой, вместо того, чтобы рвать волосы на жопе и всё переписывать, вы просто прочитаете документацию.

Но далеко не все хипстеры, очень часто документация оформляется отдельными документами и даже проходит приёмку.

Значит я попал в хипстеры еще в 2010. Видел архитектурную доку в docx работая на наш банк в 2020, уродство, не удобно, но хотяб она была, мне помогала.

В общем мы тут на самом деле не спорим а описываем две крайности.

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

Обратите внимание на редкое природное явление - Ленин написал не херню.

Мне кажется, у него угнали аккаунт. За последний месяц он уже как минимум два адекватных комментария написал.

Ну так я не за крайность же, а за здоровый минимум выступаю.

Он может быть 0 в случае врайт-онли кода, а бывает и такой, вполне законно.