At the DjangoCon US sprints, I began some work to improve main landing pages. I started with the how-to guides landing page, which right now is a not very useful list in more-or-less alphabetical order by filename.
- pull request, including a link to the original unstructured version
- New structured version
(There will need to be some follow-on work eventually, because one thing this restructuring does is expose some completely different problems within that section, but that’s another story.)
It’s apparent that Django’s use of :doc: to link to pages, rather than using a :ref: to a target placed at the top of the page, makes restructuring and refactoring unnecessarily complex and error-prone.
If we used :ref:, then there would be no need to amend any of the hyperlinks. Using :doc: means that every one has to be hunted down. (An additional complication is that :doc: is used inconsistently - sometimes a relative path is given, sometimes an absolute path.)
It will be necessary though to establish some conventions, to make them more useful (for example, the Advanced testing topic should be labelled topics-testing-advanced).
:ref: has the additional benefit that it can provide a more semantic label than a page’s filename - topics-testing-advanced tells you more than advanced.txt does.
Using :ref: means that links point to labelled information - not just places. It’s harder to merge two pages or to split one if you’re pointing at :doc:s, whereas you simply don’t need to worry about it if the information is labelled.
I don’t suggest a big effort to convert links, but I think that using :ref: should become the standard, and when there’s undisruptive opportunity to change a :doc: to a :ref: we should take it. It’s going to make managing a large documentation set easier.
) using