documentation

4 статьи

Назад ко всем статьям

Я перестал копировать код в документацию, храня тесты, код и прозу в одном Markdown-файле

Literate programming поддерживает синхронизацию документации, тестов и реализации, делая Markdown-файл единственным источником правды. Вот как реализовать это тридцатью строками на Python.

Ваш тред в Claude уже является документацией. Он просто умрёт через двенадцать часов.

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

Donald Knuth хотел, чтобы программы читались как литература. У компилятора были другие планы.

Literate programming обещала, что код должен писаться в первую очередь для людей, а во вторую — для машин. Четыре десятилетия спустя почти никто так не пишет. Вот почему самая элегантная идея в документировании программного обеспечения не смогла изменить наш способ работы.

Ваша архитектурная диаграмма уже ложь

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