search

aiven / devportal

Resources for users of the projects on the Aiven platform
https://docs.aiven.io
Creative Commons Attribution 4.0 International
60 stars 53 forks source link

Improve the titles in the `_toc.yml` file (navigation sidebar) #652

Open TibsAtWork opened 2 years ago

TibsAtWork commented 2 years ago

The problem

The _toc.yml file is used to generate the navigation sidebar.

Some of the page titles in the _toc.yml file are specified explicitly in the file, some default to using the (top level) heading of the page itself.

Some of those default titles are quite long, and they may contain words that are not needed in the context of the sidebar (for instance, it may be clear what the product is from the tree structure, but the page heading will want to be explicit).

Also, adding ® marks to many top level titles adds visual clutter to the sidebar. We would rather keep the sidebar simple to read.

The solution

It is probably sensible to just specify page titles explicitly in the _toc.yml file for all pages.

It is definitely needed for longer titles, or titles that contain ® or other marks.

Also, add a section on "creating a new page" to the CONTRIBUTING guide, and explain what needs doing to keep the _toc.yml file up to date.

TibsAtWork commented 2 years ago

See also https://github.com/aiven/devportal/issues/580 which is partially related (Improve the heading text when searching for articles. E.g. adding the service name instead of "Aiven Developer documentation") and also https://github.com/aiven/devportal/issues/652 (Improve the titles in the _toc.yml file (navigation sidebar))