На мой взгляд, это самый омерзительный случай — страдают все: и те, кто пишет документацию – нудно, скучно, бессмысленно потраченные силы на соблюдение каких-нибудь ГОСТов, и те, кто потребляет ее – обязанность заказать и оплатить документацию по ГОСТу, потому что так надо.

Если делать по ГОСТ "для галочки", то это, конечно, так себе удовольствие.

Но вот если "с душой" :), с чувством, с толком, с расстановкой, то вполне полезные вещи можно обнаружить. Взять, к примеру, милейший документ ГОСТ 19.404-79 ПОЯСНИТЕЛЬНАЯ ЗАПИСКА.

1.2. Пояснительная записка должна содержать следующие разделы:

введение;

назначение и область применения;

технические характеристики;

ожидаемые технико-экономические показатели;

источники, использованные при разработке.

Чем плохо? Можно, конечно, сказать, что "ожидаемые технико-экономические показатели" это "фу", особенно "экономические...". Да все понятно, микросервисы наголо и помчались. Но разве не полезно понимать — а что же бизнес получит от этого всего?

Ну и далее:

2.3. Раздел «Технические характеристики» должен содержать следующие подразделы:

постановка задачи на разработку программы, описание применяемых математических >методов и, при необходимости, описание допущений и ограничений, связанных с выбранным математическим материалом;

описание алгоритма и (или) функционирования программы с обоснованием выбора схемы алгоритма решения задачи, возможные взаимодействия программы с другими программами;

описание и обоснование выбора метода организации входных и выходных данных;

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

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

Your account

Sections

Information

Services