LINUX.ORG.RU
ФорумTalks

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

 


2

1

Привет, комрады.

Работаю в команде разработчиков из пяти человек. Пишем ПО на заказ. Есть три-пять основных постоянных заказчиков. И вот у одного заказчика пришёл новый техлид, который стал требовать документировать ПО. Вплоть до блок-схем алгоритмов. Требует описывать архитектуру словами и картинками.

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

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

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

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

untitl3d
()
Последнее исправление: untitl3d (всего исправлений: 1)
Ответ на: комментарий от TDrive

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

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

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

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

WitcherGeralt ★★
()
Ответ на: комментарий от lenin386

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

WitcherGeralt ★★
()
Ответ на: комментарий от WitcherGeralt

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

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

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

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

TDrive ★★★★★
()
Ответ на: комментарий от WitcherGeralt

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

TDrive ★★★★★
()

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

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

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

fernandos ★★★
()
Последнее исправление: fernandos (всего исправлений: 1)

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

BceM_IIpuBeT ★★☆☆☆
()

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

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

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

hummer
()
Последнее исправление: hummer (всего исправлений: 1)
Ответ на: комментарий от TDrive

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

WitcherGeralt ★★
()
Ответ на: комментарий от WitcherGeralt

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

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

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

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

fernandos ★★★
()
Ответ на: комментарий от TDrive

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

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

WitcherGeralt ★★
()
Ответ на: комментарий от WitcherGeralt

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

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

TDrive ★★★★★
()
Ответ на: комментарий от WitcherGeralt

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

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

TDrive ★★★★★
()
Последнее исправление: TDrive (всего исправлений: 1)

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

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

vazgen05 ★★★
()
Ответ на: комментарий от WitcherGeralt

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

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

TDrive ★★★★★
()
Ответ на: комментарий от fernandos

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

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

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

WitcherGeralt ★★
()
Ответ на: комментарий от TDrive

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

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

WitcherGeralt ★★
()
Ответ на: комментарий от WitcherGeralt

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

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

TDrive ★★★★★
()
Ответ на: комментарий от WitcherGeralt

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

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

TDrive ★★★★★
()
Ответ на: комментарий от TDrive

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

WitcherGeralt ★★
()
Ответ на: комментарий от WitcherGeralt

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

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

TDrive ★★★★★
()
Ответ на: комментарий от TDrive

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

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

WitcherGeralt ★★
()
Последнее исправление: WitcherGeralt (всего исправлений: 1)
Ответ на: комментарий от WitcherGeralt

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

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

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

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

TDrive ★★★★★
()
Ответ на: комментарий от WitcherGeralt

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

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

TDrive ★★★★★
()
Ответ на: комментарий от TDrive

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

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

untitl3d
()
Ответ на: комментарий от untitl3d

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

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

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

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

TDrive ★★★★★
()
Ответ на: комментарий от TDrive

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

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

WitcherGeralt ★★
()
Ответ на: комментарий от TDrive

Вопрос был

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

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

untitl3d
()
Ответ на: комментарий от WitcherGeralt

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

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

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

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

TDrive ★★★★★
()

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

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

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

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

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

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

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

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

Manhunt ★★★★★
()
Ответ на: комментарий от untitl3d

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

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

Manhunt ★★★★★
()
Ответ на: комментарий от TDrive

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

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

WitcherGeralt ★★
()
Ответ на: комментарий от mrdeath

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

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

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

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

Aber ★★★★★
()
Ответ на: комментарий от WitcherGeralt

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

TDrive ★★★★★
()
Ответ на: комментарий от Aber

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

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

WitcherGeralt ★★
()
Ответ на: комментарий от TDrive

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

WitcherGeralt ★★
()
Последнее исправление: WitcherGeralt (всего исправлений: 1)
Ответ на: комментарий от WitcherGeralt

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

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

Aber ★★★★★
()
Ответ на: комментарий от TDrive

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

WitcherGeralt ★★
()
Ответ на: комментарий от pinus_nigra

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

WitcherGeralt ★★
()
Ответ на: комментарий от WitcherGeralt

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

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

TDrive ★★★★★
()
Вы не можете добавлять комментарии в эту тему. Тема перемещена в архив.