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 ).
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.
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 ).
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:
-
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.
- 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 )