As I am starting to contribute to the docs, I find that one of the major areas for improvement is the separation of essential information from additional information (or lack thereof).
Some pages of the docs (such as shortcuts, which I am currently looking at) hit you with a wall of information which can be a bit intimidating. A more gradual approach, where users can uncover more advanced concepts as they become familiar with the more basic ones would be beneficial.
To this end, I would argue that sprinkling the docs with sections hidden behind <details> tags could be beneficial.
However, the guidelines for contributors state that:
All content should be authored in plain markdown without shortcodes and HTML should be kept to an absolute minimum, if used at all
So before going ahead and adding some <details> I wanted to check if this would be frowned upon.
The idea is to allow people to go through the main points and then decide which aspects to explore in more detail. For example, if you don’t have an external controller you don’t need to read how to use them to set shortcuts.
I do not. We’ve had a few suggestions to move away from pure markdown for various reasons and I’m currently resisting them. We used to have a more complex markup language for the documentation and it was a pain. The point of markdown is its simplicity.
Thanks to markdown, converting to other formats is really easy. We use to have PDF versions of the manual (in a quick check, link to pdf Spanish version was broken).
I’d rather implement hugo’s page ToC on the page rather than hide things behind the details element. Then we can still write markdown and you get a persistent on-page table of contents that shows all the headers.
The table of contents for the information page sounds a good compromise for complex pages. For myself I find skipping sections based upon heading structure within the page is sufficient. Having multiple links from the page would not improve readability for me.
@Masterpiga thanks for supporting the documentation.
