Documenting Django Code in 2022 with Eric Holscher - DjangoCon US 2022

Django

Discover a modern approach to documenting Django code with Diataxis, a markdown-based generator that prioritizes user experience, integrates with Sphinx, and offers features like search bars and dark mode.

Key takeaways

The traditional way of building documentation with Sphinx doesn’t consider user experience, making it hard to read and maintain.
Eric Holscher suggests adopting a more modern approach to documentation using a framework like Diataxis.
Diataxis is a markdown-based documentation generator that integrates with Sphinx and has a built-in link checker.
It’s easier to learn and use Diataxis than to create documentation from scratch.
The speaker encourages the audience to think about the user’s experience when reading documentation.
The Diataxis framework includes features like a search bar, a table of contents, and a dark mode.
The framework also supports markdown and has built-in support for some types of extensions.
There are many extensions available to make documentation more interactive, such as the Furo theme.
The speaker suggests that the user’s experience is more important than the documentation’s aesthetic.
Industry standards are not necessarily followed, and authors may need to mix different documentation styles to create a good user experience.
The speaker encourages the audience to think about verbs and state of the world when creating documentation.
He also suggests that documentation should be interactive and include features like tooltips.
The Diataxis framework has first-class markdown support and is easily extensible.
The framework also integrates with other tools and has a built-in version control system.
The speaker believes that the world needs more innovation and experimentation in documentation.
He encourages the audience to try out new tools and ideas to make documentation more user-friendly.

Documenting Django Code in 2022 with Eric Holscher - DjangoCon US 2022

More talks