LINUX.ORG.RU
ФорумTalks

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

 


2

1

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

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

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

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

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

Эта уверенность основана на многих годах опыта. Резюме ты видел, денежное выражение (и это уже предыдущая ступень) опыта тоже.

А на чтение ее потом теми, кто ее не писал?

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

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

Эта уверенность основана на многих годах опыта. Резюме ты видел, денежное выражение (и это уже предыдущая ступень) опыта тоже.

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

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

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

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

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

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

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

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

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

Щито делать. Так и пишем: «Что-то странное тут покопалось».

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

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

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

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

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

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

Manhunt ★★★★★
()

думаю стоит брать деньги за час работы. Например написать вот эту фичу будет 6 часов по 3000 р. за час. + документирование этой фичи 3ч по 2000р за час

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

Мракобесие по ГОСТу я, разумеется, в виду не имел.

куча статей в вики, а дальше разбирайтесь сами

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

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

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

Например написать вот эту фичу будет 6 часов по 3000 р. за час. + документирование этой фичи 3ч по 2000р за час

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

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

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

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

«Технический писатель», внезапно, пишет техническую документацию.

А кто пишет документацию для пользователя? Художественный писатель, что ли? :D

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

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

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

Если добавление каждой фичи требует заметных изменений в архитектуре проекта, то это говно, а не архитектура

С этим никто и не спорит)

Я же советую ТСу просто ценить свое время и за документацию тоже брать деньги. Для этого удобнее всего ИМХО использоваться стоимость работы за час и оценить время на задачу

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

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

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

А кто пишет документацию для пользователя?

Кто умеет, тот и пишет ) В одной конторе ее писала девочка-второкурсница, подрабатывающая секретаршей начальника - потому что выяснилось, чрезмерная техничность описания напрягла заказчика

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

В одной конторе ее писала девочка-второкурсница, подрабатывающая секретаршей начальника

Это и есть типичный техпис ) Когда ключевой навык - это владение человеческим языком. Техпис должен узнать от разработчиков, для чего кнопочки в UI предназначены, и донести это до нормальных людей в человекочитаемом виде.

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

Цена документации входит в цену разработки.

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

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

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

ты бы еще по аватаркам начал гадать о способностях к программированию)

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

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

Показывай всем свое творение.

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

Тред не читал, но своё мнение хочется высказать.
Дополню, если по договору и ТЗ в состав сдаваемой документации входит руководство системного программиста, то это можно подтянуть на требования заказчика. Но для этого должны быть явно указаны разделы документа, в названиях которых прямым текстом и написано. Если же такого нет, то любые требования по документации алгоритмов идут нахер. Варианты «мы не примем этап без схем» прорабатывается между руководителями проекта с обоих сторон и тех.дир идёт нахер. Или просто заваливается проект.

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

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

Если тебе заказчик прямо скажет, что документация ему не нужна, ты что будешь делать? По ночам писать ее в свободное время что бы невроз не беспокоил?

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

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

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

Если тебе заказчик прямо скажет, что документация ему не нужна, ты что будешь делать? По ночам писать ее в свободное время что бы невроз не беспокоил?

Если тебе заказчик прямо скажет, что исходные коды ему не нужны, ты что будешь делать? По ночам писать их в свободное время что бы невроз не беспокоил?

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

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

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

TDrive ★★★★★
()

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

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

А что сейчас используют вместо блок-схем? Буду использовать ваш ответ в дискусии с закачиком.

На макроуровне — UML. Хотя бы те же самые диаграммы классов и компонентов.

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

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

сиквенс диаграммы многим нравятся, они удобные.

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

Ещё один.

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

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

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

Разве нет?

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

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

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

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

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

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

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

Вот-вот. Бывают такие. Обычно у меня отношения со всеми норм, рабоче-дружественные. Но тут какой-то феерический абзац.

sparkie ★★★★★
()

Лол.

Всегда по умолчанию писал документацию к коду вместе с блок-схемами в UML и документировал алгоритмы.

Просить было не нужно, я же хочу сделать хорошо, а не один раз и на выброс.

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

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

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

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

TDrive ★★★★★
()

Скажи ему «исходный код - самая лучшая документация, никогда не устареет и не разойдется с реальностью».

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

Этот твой комментарий я видел, он справедливый, но ты сейчас шлангуешь. О написании пользовательской, проектной и любого рода маразматическрой документации по ГОСТу вообще в этом треде речи не идёт. Ты опять обо потерял контекст.

Напоминаю:

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

Тебе дока по архитеркутре не нужна, да? Документация по интерфейсам не нужна? Если действительно не нужна, то лучше тебе не мучаться, а пойти в ближайший ЖЕК, да устроиться дворником. Их блок-схемы алгоритмов подметания дворов рисовать вряд ли заставляют.

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

Скажи, что ваш код ансаппортабл, что с доками что без них.

ya-betmen ★★★★★
()
Ответ на: комментарий от tootsoon

Вы либо работаете с заказчиком и вас всё устраивает, либо не работаете больше никогда. /thread

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

Тебе дока по архитеркутре не нужна, да? Документация по интерфейсам не нужна? Если действительно не нужна, то лучше тебе не мучаться, а пойти в ближайший ЖЕК, да устроиться дворником. Их блок-схемы алгоритмов подметания дворов рисовать вряд ли заставляют.

Заказчик что хочет получить из доки? Ответ на вопрос «как это работает?» и без чтения кода.

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

Улавливаешь?

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

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

Звказчику все это нахрен не нужно.

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

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

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

Только главного ты так и не уловил. Ещё раз: требования в стартпосте, если и не на 100% соответствуют потребностям адекватного разработчика, то сильно с нами пересекаются.

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

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

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

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

TDrive ★★★★★
()

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

Парниша.

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

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

Хорошо.

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

WitcherGeralt ★★
()

Документировать нужно архитектуру верхнего уровня, которая со временем мало изменяется, модель данных и неочевидные хаки, которые обусловлены наличием проблем в каких-то внешних модулях. Если пишете библиотеку для внешнего использования, то нужно документировать публичную часть api. Документировать каждый чих внутренней начинки - пустая трата времени, без чтения исходников и отладки осмысленные правки все равно не получится делать. Хочет блок-схему на каждую функцию - делайте перерасчет сроков, считайте документацию неотъемлемой частью кода, которая изменяется одновременно с правками кода, детализацию можно не добавлять.

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

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

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

ЗЫ sorry за сумбур, пишу на ходу.

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

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

https://studref.com/htm/img/13/10536/62.png
https://intuit.ru/EDI/23_04_17_1/1492899714-28128/tutorial/356/objects/2/files/02_13.gif

можно даже для описания бизнес процессов использовать.

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