Improvement: full support for TOC

Hi,

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:

  1. 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.

  2. Xcode which is a little better than DocC with a full hierarchical view which helps to find what you seek.

  3. 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.

  4. 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:

  1. 'Learning' mode: optimized to see the hierarchy of the documentation on the subject matter like mkdocs.
  2. '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?

8 Likes

It would be better if you could customize the theme.

Thanks Damien, this sort of forum post is exactly what is exciting about now being open source! The specific feature request for a Table of Contents, or other in-page navigation, is something that indeed feels like a great goal.

Curious, could you expound a bit more on your ideas around option #1 and #2? Especially curious how you see #2 as a TOC feature vs. where you would see it as Search features.

3 Likes

Hi Tim!

Thanks for your reply.

For #2 it could be a TOC for the current "Topics".

So you would get a TOC with all the sections (like "working with units", etc), then the full signatures and return types. The current Topics layout is too verbose and doesn't let you scan all the content easily. You have to scroll through everything to know what's in the document making API searching difficult.

For the search in #2, I was thinking more of a "filter" to try to quickly reduce the signatures list to a few you are looking for (ex: I could type "formatter" or "units" in the HealthKit example to filter APIs and/or sections).

1 Like

Ah, a filter is very much in line with how we were thinking about it (at least in this context.)

As for the more compressed list of topics, yes, that is in alignment, too. If you want to file a Jira ticket, we can also track that here in this forum for further discussion. There will likely be a lot of design work ahead, but the idea is definitely a good one that we will want to pursue.

2 Likes