Как писать документ библиотеки
Требования к документам этой библиотеки. Общие правила языка и тона — в правилах письма; здесь — что именно должно быть в документе, чтобы им можно было пользоваться.
4 минутыТребования к документам этой библиотеки. Общие правила языка и тона — в правилах письма; здесь — что именно должно быть в документе, чтобы им можно было пользоваться.
Критерий готовности
Документ готов, когда по нему можно выполнить задачу с нуля, не обращаясь к другим источникам и не додумывая шаги. Проверка простая: дайте документ человеку или языковой модели, которые темы не знают, и посмотрите, дойдут ли они до результата. Если на каком-то шаге нужно догадаться — это дефект документа, а не читателя.
Типичное, что теряется и ломает выполнение:
- в какой файл класть показанную конфигурацию;
- в каком порядке выполнять шаги, если один зависит от результата другого;
- что должно быть верно до начала;
- как понять, что шаг удался, а не «вроде прошло».
Обязательные части
Задача и исходное состояние. Что получится в конце и от какого состояния система стартует.
Предусловия с проверками. Не «нужен домен», а команда, показывающая, что домен указывает именно сюда, и ожидаемый результат.
Шаги по порядку, каждый с проверкой. У шага — команда и однозначный ожидаемый результат. Правило для читателя: результат другой — переходить к разбору отказов, а не к следующему шагу. Если порядок шагов принципиален, это указывается явно вместе с причиной.
Связь с соседними этапами. Документ описывает звено цепочки, а не изолированный приём. В начале — короткая таблица «откуда пришли → этот документ → куда ведёт», где названы:
- что предыдущий этап обязан обеспечить (иначе этот не сработает);
- что этот этап оставляет следующему.
Эти документы выросли из практики разворачивания систем, где этапы связаны. Пропущенный стык — это не неполнота текста, а место, где на практике останавливается работа: например, настроенный TLS бесполезен, если приложение слушает все интерфейсы и его дёргают напрямую, минуя шлюз.
Разбор типичных отказов. Таблица «признак → причина → что делать». Признак формулируется так, как читатель его видит: сообщение об ошибке, код ответа, поведение.
Откат и снятие. Как вернуть систему в исходное состояние и что при этом не удаляется само.
Что обязательно для какого жанра
В библиотеке три жанра, и требовать от всех шесть частей бессмысленно: у свода правил нет шагов, у кредо нет отката. Обязательное по жанрам:
| Жанр | Примеры | Обязательно | Неприменимо |
|---|---|---|---|
| Порядок действий — читатель выполняет и получает работающий результат | всё в operations/, process/testing.md | все шесть частей | — |
| Спецификация — задаёт раскладку и инварианты, по которым пишут код | architecture/BM*.md, REUSE.md | задача, связь с соседними этапами, проверки соответствия (как убедиться, что код правилу отвечает), таблица отказов | предусловия, откат |
| Свод правил — по чему сверяются при работе | PRINCIPLES.md, writing-rules.md, design/* | задача, связь с соседними этапами | предусловия, шаги, откат |
Связь с соседними этапами обязательна для всех трёх: документ, из которого не видно, куда идти дальше, обрывает работу независимо от жанра.
Отдельно: карта источников (например, читательская карта книг) документом библиотеки не считается — по ней нельзя выполнить задачу, не обращаясь наружу. Такие файлы держатся в базе как справка и помечаются в первой строке, чтобы читатель не ждал от них исполнимости.
Обезличивание
В библиотеке нет наших доменов, адресов, почт, имён проектов и ключей. Примеры — на example.com и
admin@example.com. Перед публикацией запускается проверка; её
непустой вывод означает, что документ публиковать нельзя.
Одна тема — один документ
Тема закрывается целиком в одном файле. Если по теме есть несколько источников, они сводятся, а не складываются рядом: расхождения разбираются, устаревшее убирается, остаётся один порядок действий с объяснением, когда применим каждый вариант.
Откройте исходник документа по ссылке «Предложить правку» — там же видно, что и когда в нём менялось.