The current DocC generated documentation is very hard to navigate / search due to the lack of full TOC support.
TOC and hierarchical views are very important to create a mental model when reading. It helps to know where you are, which content is available, navigate / search more quickly.
I attached 4 screenshots to illustrate the point:
mkdocs from google which is pretty good, with 2 TOCs: one for the full documentation set on the left, one for the current document on the right. At any time, you know where you are globally and locally plus what's the content.
Xcode which is a little better than DocC with a full hierarchical view which helps to find what you seek.
DocC provides only shortcuts on the right which makes it really difficult to locate APIs, sections and make a mental model as you have to scroll through the whole document to see if there is the content what you are looking for. You also lack awareness of the content globally as you only have the 'breadcrumb' view on the top.
Swift.org which is almost there but lack details in comparison to mkdocs (may be it can be reused).
It would benefit all if the documentation was easier to navigate, understand and search.
As one of the DocC goal is to mix gracefully high-level technical articles with low level APIs documentation, it could be interesting to have 2 different 'modes' when accessing it:
- 'Learning' mode: optimized to see the hierarchy of the documentation on the subject matter like mkdocs.
- 'Developer' mode : optimized for API searching to easily learn / seek / sort all the function signatures and return types (which are usually missing)
It's just an idea as it might be tricky to solve both requirements in one way.
What do you think?