Критерий готовности

Документация не готова до тех пор, пока её не исправил тот, для кого она предназначается.

Важность примеров

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

Это близко к идеалогии github copilot, stack overflow, которые часто критикуют. Но стоит ли критиковать стремление к максимальной эффективности (минимум усилий, максимум результата) и проявления этого стремления, если они приносят результат? Да, мозг ленив, разработчики ленивы, но кто хочет делать рутинную работу (по вдалбливанию информации в свой мозг)?

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

Подходы к программной документации

Код - это объект. Объект в терминах, наверное, квантовой физики больше, в том плане, что он “наблюдаемый” объект или “наблюдаемая система”. Документация, схемы и т.д. - это модель, то есть результат наблюдения.

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

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

Косвенная связь - когда документация генерируется. Она не содержит каких-то инсайтов, типа ответов на вопрос “почему” и как правило довольно скудная, но актуально отвечает на вопрос “как выглядит интерфейс объекта”. Вот как API-доки типа swagger, openapi, sphinx. В целом можно комбинировать 1 со 2 и получится сравнительно терпимо, но ответы на вопросы “почему” автоматически меняться не могут, их могут забывать поправить, потому что они не связаны с объектом строго.

Отсутствие отдельной модели самой по себе - когда система и есть документация. Просто лезешь в код и смотришь что и как сделано. Используешь систему контроля версий для обнаружения дополнительных комментариев по интересующим кускам (git log, git blame), ищешь ссылки на задачи, ищешь ответы на вопросы “почему” в них. К смеси второго и третьего пункта ещё добавлю автотесты. Как их преобразовать в документацию - хз. Но пока они проходят, они по крайней мере актуальны и не врут.

Первичные данные

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

Обычно это и есть программный код, но не всегда.

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