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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Подразумевается, что доку пишет человек знающий. Очевидное условие. Разве нет?

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Ещё один.

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

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

Разве нет?

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

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

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

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

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

Лол.

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

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

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

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

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

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

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

Напоминаю:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Парниша.

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

А уже нельзя удалить, в общем забей

Хорошо.

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

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

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

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

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

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

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

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