34 Publishing Documentation: From Manuals to Living Knowledge
Guiding Question: How do technical documents continue growing without becoming unmanageable?
Software changes continually.
New features appear.
Old interfaces disappear.
Programming languages evolve.
Documentation must evolve alongside them.
Unlike printed books, technical documentation is rarely finished.
It is revised.
Expanded.
Corrected.
Versioned.
Republished.
The challenge therefore extends beyond writing.
How can large collections of technical knowledge remain organized, accurate, and easy to maintain?
Over the years, several remarkable publishing systems have answered that question.
Although they serve different communities, they share a common philosophy:
Write in plain text. Publish professionally.
34.1 From Markup to Publishing Systems
Earlier in this primer we explored several markup languages.
DocBook.
reStructuredText.
AsciiDoc.
Markdown.
Those languages provided authors with expressive ways to describe technical documents.
Around them, publishing ecosystems gradually emerged.
The result was more than markup.
It was complete documentation workflows.
34.2 DocBook
One of the earliest comprehensive documentation systems was DocBook.
Built upon XML, DocBook emphasized rich semantic description.
Rather than focusing on appearance, authors described chapters, procedures, warnings, examples, commands, and many other structural elements.
Large software projects adopted DocBook because its detailed vocabulary supported professional technical publishing at considerable scale.
Although newer systems have become popular, DocBook demonstrated that documentation could be treated as structured knowledge rather than formatted pages.
34.3 Sphinx
Within the Python community, Sphinx became one of the defining documentation systems.
Built around reStructuredText, Sphinx introduced powerful capabilities such as:
- automatic tables of contents
- cross references
- API documentation
- searchable documentation
- versioned manuals
Its close integration with Python projects helped establish documentation as an essential part of software development rather than an afterthought.
Many influential projects continue to rely upon Sphinx today.
34.4 AsciiDoctor
The AsciiDoc language inspired a modern publishing ecosystem through AsciiDoctor.
Technical writers appreciated its readable syntax together with its expressive capabilities.
Books.
Manuals.
Reference guides.
Training materials.
Professional documentation became easier to maintain without sacrificing semantic richness.
AsciiDoctor demonstrated that approachable syntax and powerful publishing need not be opposing goals.
34.5 Antora
As documentation projects continued to grow, a new challenge emerged.
How should organizations manage documentation spanning multiple products and multiple software versions?
Antora answered this question by treating documentation as a collection of interconnected components.
Entire documentation portals could be assembled from independently maintained repositories.
Versioned documentation became a first-class feature.
For organizations maintaining large technical ecosystems, this represented a significant advance.
Its setup is more involved than some other systems, reflecting the needs of enterprise-scale documentation, but its architecture has proven valuable for large projects.
34.6 mdBook
Within the Rust community, mdBook became an elegant solution for publishing technical books.
Its philosophy is refreshingly simple.
Write in Markdown.
Organize chapters.
Publish a beautiful online book.
The official Rust documentation demonstrates just how effective this approach can be.
Many developers appreciate mdBook because it allows them to concentrate on technical content while the publishing system manages navigation, search, and presentation.
34.7 Jupyter Notebooks
Documentation is not always static.
Researchers, educators, and developers increasingly combine explanation with executable computation.
Jupyter Notebooks embody this idea by placing narrative, code, visualizations, and results within a single interactive document.
This approach has transformed scientific computing, data science, and education.
Rather than merely describing a computation, the document demonstrates it.
The boundary between publication and experimentation becomes remarkably small.
34.8 Documentation as Living Knowledge
Unlike traditional books, technical documentation rarely reaches a final edition.
Software evolves continuously.
Documentation therefore becomes a living body of knowledge.
Publishing systems embrace this reality.
Version control records history.
Automation regenerates websites.
Search indexes grow.
Cross references remain accurate.
The documentation evolves alongside the software itself.
34.10 Lessons for the Textsmith
Technical publishing reminds us that documentation is not merely supplementary material.
It is part of the software itself.
Well-designed documentation systems preserve knowledge as carefully as source code.
They demonstrate once again that plain text scales remarkably well—from individual notes to documentation spanning thousands of pages.
The tools differ.
The philosophy remains constant.
Write clearly.
Describe structure.
Automate publication.
Allow knowledge to grow.
34.11 Key Ideas
- Technical publishing systems transform markup languages into complete documentation workflows.
- DocBook pioneered semantic technical publishing.
- Sphinx integrated documentation closely with software development.
- AsciiDoctor made rich technical publishing more approachable.
- Antora excels at managing large, versioned documentation portals.
- mdBook provides an elegant workflow for technical books.
- Jupyter Notebooks combine narrative, code, and computation in interactive documents.
- Documentation systems demonstrate that plain text publishing scales from individual manuals to enterprise knowledge bases.
In the next chapter, we discover that publishing extends beyond books and documentation.
Can ideas be presented live while remaining faithful to the plain text philosophy?
There we explore presentations, speaker notes, and interactive dashboards, where structured text becomes one of the most accessible and flexible presentation media available.