I would like to make a series of improvements to the Django documentation, at a structural level.
At Django on the Med in Spain in October 2025 I got started with some work, but it’s only now at the DjangoCon Europe 2026 sprints that I have been able to deliver something.
Documentation home page domains of concern
This first effort is a reworking of the exposition of the contents on the documentation home page. I think the home page is an excellent overview of the territory of Django, and it gives users a great short-cut to building a meaningful mental map of Django, but it needs a little improvement.
Trac ticket, pull request, rendering of the new arrangement
This pull request deliberately doesn’t touch other apparent issues, even with that page – for example, it hasn’t added or removed any topics, just moved existing ones around.
I hope the new arrangement will have a forcing function too – that by making certain things more obvious, it will bring some problems into the light that have been living quietly for too long under peaceful rocks.
Other things I’d like to address
Design of the links
The overview question
A link called “Overview” appears 19 times on that page. It makes perfects sense where it appears in its context, for example:
File uploads: Overview | File objects | Storage API | Managing files | Custom storage
… as long as you are a sighted reader. If you’re using a screen reader, there isn’t anything to tell you that it’s an overview on the subject of file uploads.
I have done some research into this but it’s not conclusive and I would like to proceed on the basis of what kind of solution a screen reader user would actually prefer. I raised a question on StackOverflow, with a possible solution (that uses ARIA) but it might not be the right way.
The | character between each link appears in the HTML content – it shouldn’t, and that whole line should I think be constructed as inline links, marked up as navigation and presented using some CSS.
I think the best way forward is with a custom Sphinx directive that implements the patterns.
Landing pages
For example, How-to guides, Reference, Topics. The first of these has received a little attention recently, and is at least broken into rational sections under headings. The other two are quite uninviting lists.
A landing page like that should look and act something like the way the menu does at a good restaurant. It’s not just a list of what’s on offer, it also provides clue and cues about how those things relate each other, how to relate them to your situation, and in what kind of order it you might want to approach them.
Three-column layout
I think it’s high time the documentation adopted the three-column layout: site navigation on the left, content in the middle and page navigation on the right.
@alexgmin’s proof of concept from Django on the Med:
I hope that bit by bit I’ll be able to advance some of these aims, and get some others involved to help, and that each step will reveal new opportunities to refresh and improve one of the jewels in Django’s crown.