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

Можно проверить достоверность, сличая то, что написано в доке с тем, что отдает софт

Когда мы говорим об актуальности, то речь идёт о триггерах, которые говорят о том, что что-то возможно стало неактуальным. Например, изменилась структура json'а с i18n константами. Возможно, всё и хорошо, а возможно надо что-то доработать. Если всё хорошо, просто говорим Approve. Если нет — дорабатываем документацию и говорим Approve.

Критику хотите услышать по форме или по содержанию?

Проблема понятна, хочется запустить процедуру, которая обеспечит контроль качества документации (на самом деле, и эксплуатируемого изделия). Т.е. хочется включить Исполнителя (естественно, не бесплатно) в процесс, результатом которого будет наличие в документации соответствующего кода. Понятно, что Исполнитель может провести анализ и в техническом проекте (любом другом документа) написать — это невозможно. Заказчик может (1) принять эту точку зрения, (2) убедить исполнителя, что это не так, или найти (3) исполнителя соответствующей квалификации.

обе)

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

Погоди, Ром, сейчас речь идёт только об актуальности. То, что ты говоришь — это верно. Но конкретный кейс, о котором я говорю, — у людей большие проблемы именно с актуальностью

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

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

Про keep with next серьёзно? В 18-м году клялись, что ради этого всё и затевается, уж погодите, вот как выскочим, как выпрыгнем. Ну... нафиг.

А почему в 18-м? Какие-то обсуждения были на эту тему?

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

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

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

По вашим вопросам:

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

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

Основную боль попробую описать так:

- Там документация никакая, ее как сделали n лет назад, так и сдавали. Бардак
- Э.. документация -- нанял техписа, он мне всю документацию за неделю собрал
- Заказчик требует документацию в редактируемом виде в MS Word
- ПМИ, тут требуется согласования С1 и С2, также С3, его это затрагивает. Чтобы С1 подписал, нужны С4 и С5. С5 в отпуске, но не страшно, можно запустить через С6 и С7. А, ну конечно, С8 и С9, иначе потом проблемы будут. Ну и юристы пусть посмотрят, они в двух управлениях, поэтому С10 и С11. Чем больше посмотрят, тем лучше документ будет. С1 уволился. А кто заменяет? Да вроде никто. Но можно дать посмотреть С12 и С13. Теперь хорошо. + качество -- С14 и нагрузочники С15.

> предлагается процедура, в ходе которой исполнитель обязан представить предложения по набору тестов

по моему это утопия уровня «давайте напишем профессиональные стандарты по которым можно будет строго валидировать и принимать хорошую документацию»

В итоге вы на гора получаете нечитаемый хлам, когда на гос заказ специально нанимаются несчастные люди, рождающие по 10 пачек А4 никому ненужной документации

всем привет
хочу описать структуру файлов в vs code в виде раскрывающегося дерева, можете подсказать через какие инструменты лучше сделать?

Всем привет, сейчас занимаюсь проектированием документации для продуктов компании. Интересуют какие-то примеры сайтов с документацией на jekyll с открытым исходным кодом. Что-то, что нравится вам. Буду рад, если подскажете. Либо конкретные примеры скинете, либо подскажете в какую сторону гуглить.

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

"Давайте я как заказчик не будут требовать от вас документацию, которую невозможно поддерживать в актуальном состоянии"

всем привет! коллеги собирают доку на сфинксе в пдф, и вот такая ошибка:

! Package babel Error: Unknown option `russian'. Either you misspelled it
(babel)                or the language definition file russian.ldf was not foun
d.

все языковые пакеты вроде установлены, сама строка из conf.py такая:

'babel': r'\usepackage[english, russian]{babel}',

в чём всё таки проблема?

Судя по "not found", все-таки не хватает пакета.
Пакет "texlive-langcyrillic" точно установлен?

а как его установить? стандартные средства не помогли:

$ sudo yum install texlive-langcyrillic
Last metadata expiration check: 2:17:37 ago on Thu 30 Sep 2021 12:39:49 PM UTC.
No match for argument: texlive-langcyrillic
Error: Unable to find a match: texlive-langcyrillic

Попробуйте так: texlive-lang-cyrillic.
Он в разных ОС по-разному называется.