LINUX.ORG.RU
ФорумTalks

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

 


2

1

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

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

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

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

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

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

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

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

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

А я не вижу в этом никаких проблем, в моих ситуациях все было норм.

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

и в особых случаях получить по лицу)

именно поэтому Бог создал удалёнку, чтобы девелоперы по лицу не получали )

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

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

Все так. Существует только одна ситуация, когда можно не описывать архитектуру - когда компактная фирма делает полностью законченный проект/изделие для непрофессионального заказчика. А так это делать все обязательно не только когда сдается проект заказчику, но и когда работа просто передается в соседнее подразделение.

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

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

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

Пример: Байки из склепа (комментарий)

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

Если речь об одноразовой скриптухе, то само собой, часть проекта она и не является.

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

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

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

Нет, не должна, это будет работой в стол. Зачем писать доку которую ни кто не будет читать? Нравится работать в стол?

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

В чём проблема, написать «есть такая джоба, нужна она для того-то»?

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

Зачем писать доку которую ни кто не будет читать?

Если не будут, то ССЗБ. Но если она понадобится, а её не окажется, то мудаком в этой ситуации являться будет тот, кто поленился написать пару предложений.

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

Если не будут, то ССЗБ. Но если она понадобится, а её не окажется, то мудаком в этой ситуации являться будет тот, кто поленился написать пару предложений.

Все верно. Это оценка рисков. Так вот оценивать нужно как профит/затраты и это оценка не обязана быть >1

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

Я даже не знаю как без wiki работать над большим проектом.

Вот выросло...

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

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

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

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

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

Я же тебе скинул ссылку на реальный пример из жизни, прочти.

И в чем мораль? У вас была написана документация? Если да то судя по всему она не помогла? Какие выводы то?

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

Не в коде, а в вики.

Какие выводы то?

Если бы прочитал внимательно, сам бы их сделал. Проблема была не на нашей стороне. У них не было документации и они не знали, что используют наше старое API.

Мораль: пиши документацию, или сядешь в лужу.

WitcherGeralt ★★ ()

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

Какой правильный чувак.

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

УБИТЬ ЭТУ СКОТИНУ!

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

Не в коде, а в вики.

А если в коде удобнее? Почему в вики?

Если бы прочитал внимательно, сам бы их сделал. Проблема была не на нашей стороне. У них не было документации и они не знали, что используют наше старое API.

А с чего ты решил что не было? Может была, но бесполезная, написанная такими же бюрократами как ты. Или была нормальной но про нее даже не вспомнили?

Мораль: пиши документацию, или сядешь в лужу.

деды писали и ты пиши, думать не нужно.

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

В комментариях к задаче в трекере? Оно потеряется.

Нет, в коде удобно оставлять ссылку на таску из которой этот код появился, если это что то разовое.

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

А с чего ты решил что не было?

С того что на официальный запрос, так же повторённый несколько раз неформально, был ответ, что нет, не используется. И с того, что реально не было.

про нее даже не вспомнили?

Такие же раздолбаи как ты?

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

Давай теперь на каждый сих вычитывать 100% кода в поисках документации. Капец у вас порядки в Индии.

Особенно если код отдали во вне, и доступа к вашему трекеры нет.

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

С того что на официальный запрос, так же повторённый несколько раз неформально, был ответ, что нет, не используется. И с того, что реально не было.

А почему ты думаешь что если бы была это помогло?

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

Давай теперь на каждый сих вычитывать 100% кода в поисках документации. Капец у вас порядки в Индии.

Какие 100% кода?) Ты видишь непонятный тебе код, открываешь и видишь там все, что нужно. зачем заставлять людей лезть в вики? потому что деды так делали?

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

Ты все время пишешь «как нужно» но сам же не можешь объяснить зачем и кому это нужно)) Это звоночек.

TDrive ★★★★★ ()

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

Всё просто: заказчику объясняется, что все сроки разработки увеличиваются на 50-100%, при чем, за эту всю радость он будет платить из своего кармана. Если его устраивает — пишешь блок-схемы алгоритмов. Конечно, если это устраивает и тебя тоже. Ну типа лично я не против того, чтобы описывать свою архитектуру словами, но обычно это нахер никому не нужно и люди платят только за работающий код. Обычно когда заказчик узнает, насколько дороже ему обойдется такая разработка, то все басни про «одноразовый код без доков» отходят на второй план.

Вообще, у меня иногда складывается такое впечатление, что распределение по должностям в IT строится таким образом:
 — Писать код умеешь? Будешь разработчиком.
 — Не умеешь писать код? А читал документацию по фреймворку? Будешь техлидом.
 — Не умеешь писать код и не читал доков? Будеш Agile коучем.

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

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

Ну, то есть, логика: ты — идиот, не хочешь писать, а значит все тоже идиоты, не захотят читать. Железно.

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

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

Вот +1 просто.

Но есть еще вопрос - а как у заказчика обстоят дела с требованиями к ПО?

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

Ну, то есть, логика: ты — идиот, не хочешь писать, а значит все тоже идиоты, не захотят читать. Железно.

Ты сам это придумал, я такого не говорил.

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

Какой в жопу непонятный код? Тупая шлангота пошла. Я тебе ситуацию выше дал.

И я тебе выше точно так же дал ситуацию с разовой джобкой.

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

Ты меня не спрашивал.

Тебе нужно задеплоить сервис, ему нужна кафка, мнрга и ещё туча всего, он нетривиально конфигурируется с помощью DSL. Документации нет, читай код, удачи тебе.

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

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

Ещё как откажется.

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

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

И врёшь, обоснование я тебе уже давно дал: работа с рисками. Сегодня ты не знаешь, что понадобится тебе завтра.

И да, деды часто бывают правы, за ними опыт.

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

такие требования бесят. как его правильно послать?

Написать псж и сменить работу. За код (и тем более какое «комплексное решение» с деплоем и прочим) без документации надо расстреливать. У меня есть один такой проект, старых разрабов хочется убить каждый день.

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

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

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

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

но на практике ты этого не делаешь

Harald ★★★★★ ()

на оплате это никак не сказывается.

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

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

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

На практике я из них лично знаю только двоих, и они в другой стране. И они в курсе что я думаю по поводу их кода без единого коммента.

Или ты про «сам не пишешь доку»? Пишу, особенно на интерфейсы и алгоритмы сложнее чем «переложить жсон в базу». Больше всех рад фронтенд, у них больше вообще вопросов не возникает

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

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

У многих бытует мнение, что лучшая документация - это код. У нас так и живут.

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

У многих бытует мнение, что лучшая документация - это код. У нас так и живут.

И на интерфейс тоже? Особенно на rest, gql/protobuf хоть какую-то спеку имеют.

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

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

Любая миграция данных в рамках рефакторинга старой структуры.

И врёшь, обоснование я тебе уже давно дал: работа с рисками.

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

Сегодня ты не знаешь, что понадобится тебе завтра.

Иди сделай себе пирсинг на члене, ты же не знаешь что тебе понадобится завтра.

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

документировать надо это конечно он прав.

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

Если документация нужно прямо красивое и в неких стандартах, то плюс новая штатная еденица и соотв.инфраструктура для ведения документации (да, одной wiki на команду не обойтись)

А в начальных условиях оплаты проекта сие не предусмотрено. Далее «Любой каприз за ваши деньги». Утром деньги, вечером стулья.

MKuznetsov ★★★★★ ()
Закрыто добавление комментариев для недавно зарегистрированных пользователей (со score < 50)