docs_are_hard.md

Docs are easy(ish) to write, but hard to maintain

from a rant on the Sanic Community Discourse

The situation gets even worse where there are "too many cooks in the kitchen". In long-lived projects (many years, many versions) where there are lots of contributors, keeping docs current is a nightmare. As trust in the docs fails, so does confidence in the project ( cough >jenkins< cough ).

How do the big kids do it?

By way of example, allow me to present a few project we're all familiar with, because they are similar to Sanic and because we don't hear people complaining about the docs:

• Ansible Doc Home ( view source )
• Celery Doc Home ( view source )
• Django Doc Home ( view source )
• Flask ( view source ) Ok, you have been so generous with your experience that I just *have to take a brief break from my insane deadline to touch on the doc subject.

Docs are easy(ish) to write, but hard to maintain

The situation gets even worse where there are "too many cooks in the kitchen". In long-lived projects (many years, many versions) where there are lots of contributors, keeping docs current is a nightmare. As trust in the docs fails, so does confidence in the project ( cough >jenkins< cough ).

How do the big kids do it?

By way of example, allow me to present a few project we're all familiar with, because they are similar to Sanic and because we don't hear people complaining about the docs:

• Ansible Doc Home ( view source )

• Celery Doc Home ( view source )

• Django Doc Home ( view source )

• Flask ( view source )

• SqlAlchemy Beautiful handling of complex and interrelated content. Thanks @vltr

• SqlAlchemy Beautiful handling of complex and interrelated content. Thanks @vltr

• Because Sanic has a global audience, we may want to observe Nikola and Lektor , two projects that address L10n and I18N in their core.

What makes these docs so special?

• These docs need to be version specific because the code details may change from one release to the next.
• They also need to be elastic enough that you avoid repeating material that has not changed.
• There are many cross references because the same info can be relevant to different contexts (eg. Tutorial, Reference, Release Note)
• If you look at the source you'll notice the use of symbols like :doc: (which resolves to a URL at compile time) and :term: (which resolves to a glossary entry ).
• They keep the content and presentation separate, because sometimes the HTML needs to look like a web page and the PDF needs to look like a book.... or ePub, man page, or even a fancy presentation

---

By popular demand, here are a few of my favorites:

• Unit Test the code blocks in your docs using the doctest module ! (example) (tutorial)
• Build diagrams from plain text markup using UML or Mermaid.js ( PlantUML module ) ( mermaid extension )
• versionadded:: came in handy when I when I had to write release notes.

I'm excited to try this new Swagger/OpenAPI extension ( example )