Approaches and best practices¶
In all information usability practice, too much information can be as damaging as not enough. That’s especially the case when it comes to accessibility and non-visual users, for whom ignoring useless information can be even more of an effort.
A sighted reader might be able to skip over unwanted information with the flick of an eye; the screen reader user will often have to pick through it much more laboriously.
Designing your tables of contents¶
It’s worth repeating that sphinx-structured-tocs tables of contents are independent of Sphinx toctrees. They are nothing to do with each other.
Making use of context¶
The job of your table of contents is to present as much information as possible in a small space, in such a way that relationships between pages of information are intuited from the organisation of the table.
This means allowing the context of links to be provided by adjacent headings and markers – the HTML heading before a domain, or the slice name at the start of a line of links.
Longer page titles can be reduced this way. If the domain is “the model layer” and the slice is about querysets, Reference in that slice is clearly about querysets, and not, say, model fields: we don’t need to say “Model queryset reference” in the table, even if that is the actual title of the page we’re linking to.
Thinking non-visually¶
Accessibility means providing the same cues and clues through other mechanisms.
We need to be aware of what the non-visual user loses and of the way information behaves. For example, the user of a screen reader can’t take in a screenful of information in one act. A visually close heading could be much further away for a screen reader.
Approaches¶
sphinx-structured-toc makes some decisions based on best practice, while others are left to the user.
Built-in patterns¶
The accessible link name for a link Reference, that refers to the “Model queryset reference” page, is “Reference, Querysets”. The order is always outwards, from the immediate context to the parent context.
The accessible name always contains the visible name (“Reference”).