Swift-DocC sidebar

beatriz · February 10, 2022, 9:02pm

Hi everyone! I’m excited to kick off a new development effort for Swift-DocC-Render — the sidebar. The goal is to create an easy, intuitive way to quickly navigate through documentation.

Below, I’ll share some early designs for this experience. The sidebar will enable you to visualize a technology’s symbol tree, move between pages, and find specific APIs. I look forward to hearing your thoughts on these designs.

The sidebar experience has three main features:

Navigate and filter the symbol tree. You can dive into different levels of hierarchy in the tree. This enables a side-by-side reading experience that lets you effortlessly switch from exploring different symbols, to focusing on a single page.

Two side by side screenshots of the sidebar. The one on the left shows a full, unfiltered symbol tree. The one on the right shows a filtered list of symbols with the word "care" entered in the filter bar.

Filter by text, articles and tutorials. Type in the filter bar to narrow down the content on the sidebar, or select a tag to see a list of a particular type of page. For example, when you select the “tutorials” tag , the API list will only show tutorials.

Adapt the content. Resize the page to optimize for reading or navigating. Make the sidebar bigger to view long API titles, or smaller to focus on the body content.

Karl · February 10, 2022, 9:40pm

This looks basically perfect. I can't wait!

Is the idea that this would show the same content as the sidebar in Xcode's documentation browser?

Xcode's documentation sidebar includes a filter to exclude deprecated symbols. Would the DocC-Render version have the same option? And what are the thoughts on enabling that (and hiding deprecated symbols) by default?

beatriz · February 11, 2022, 12:07am

Thanks Karl!

Yup, you’d see the same content in both.

Excluding deprecated symbols isn’t something we scoped for the first version of the sidebar, but it’s definitely good to know you’re interested in that feature. Do you think it should be enabled by default?

Jon_Shier · February 11, 2022, 3:05am

Please make sure the search is fuzzy! Using a similar algorithm to Xcode would be great, but hopefully one that doesn't break as much.

Personally I don't think filtering is necessary, but it certainly shouldn't be enabled by default. Users can hardly be expected to keep up with deprecations and will wonder where the APIs they see on StackOverflow or these forums aren't coming up in the results. I would like to see deprecated symbols in their own section of the list, like we see in Dash.

More generally, a section in the sidebar for inherited or protocol conformance APIs would be great too. Such a pain in Xcode and Dash that I have to remember that certain things live on UIControl and not UIButton. It would also be nice to separate out my View's specific APIs from the billion that we inherit from View, while still letting us view those APIs if we want.

Karl · February 11, 2022, 11:02am

I asked because that's the only filtering option currently offered by Xcode, and I think they should be consistent if possible. If they are inconsistent, it raises questions about why does Xcode thinks this is an important thing to filter symbols by, but DocC-render considers it unimportant.

More broadly, I would like to see deprecated symbols be less prominent in documentation - after all, whilst a deprecated symbol still exists, its use is no longer recommended. They're unique in that they need to be there, but you also kind of don't want them to be there or to draw attention to themselves.

There are a number of ways to approach that, from toggle switches which show/hide all deprecated symbols, to collecting them at each level of the topic hierarchy in their own little islands (both in topic pages and in the sidebar). But it's fine if that is out of scope for now; the sidebar still adds a lot of value even without it.

ethankusters · February 11, 2022, 7:41pm

Xcode offers a few filtering options beyond "Hide Deprecated". It will filter by a DocC archive's symbol availability (what OS version the symbol is available in and introduced), documentation kind (article, tutorial), and deprecation. (I agree that these other options aren't as discoverable as they ought to be though- if you begin typing an OS version in the filter bar you should be offered autocomplete for a filter option.)

I think all of these filter options are important. Tackling documentation kind first and then investigating how to implement further kinds of filtering seems like a reasonable path forward.

I agree! Would be great to explore how the new sidebar can interact with on-page content to better promote the symbols you, as the framework author, want to guide readers towards.

beatriz · February 16, 2022, 6:53pm

Dobromir Hristov just published a PR with the following features:

New adjustable layout
A sidebar tree navigator
Updated nav layout and breadcrumbs logic
A new Hero for documentation pages

The body content changes and availability will be added on soon. For details on the visual design of these features, check out this post.

Here’s the PR:

https://github.com/apple/swift-docc-render/pull/51

AlexanderM · February 16, 2022, 8:44pm

Can this be implemented in a way that's more Swift-aware?

Something along these lines:

func generateSloth(in: Habitat) throws -> Sloth
func generateSloth(in: Habitat) -> Sloth
func generateSloth(in:) -> Sloth
generateSloth(in:) -> Sloth
generateSloth(in:)
gen...Sloth(in:)

The point being, if you only have a few chars, dropping func, the parameter type, effects like async or throws is more worthwhile than cutting the method name off.

young · February 16, 2022, 9:11pm

If you drop "stuff" but keeping it looking normal is misleading: you don't know parts of it is elided. I think what you suggest is good if there is clear indication some part is elided.

taylorswift · February 16, 2022, 9:13pm

this is very difficult to do using the declaration tokens provided by swift-symbolgraph-extract, because DeclarationFragmentPrinter.cpp does not emit the AST-level information.

ethankusters · February 17, 2022, 12:02am

I’ve built a version of the Swift-Argument-Parser docs on my fork with the version of Swift-DocC-Render from the open PR if anyone is interested in trying out the proposed sidebar and page-design updates: https://ethan-kusters.github.io/swift-argument-parser/documentation/argumentparser.

Karl · February 17, 2022, 12:27am

Yeah, I'm not sure I'm really feeling it as proposed.

Here's a super-quick example of how it would look if we dropped the margins and the removed the hero background. Personally, I think it looks a lot better with fewer visual flourishes. Just MHO.

The body content still feels a bit "off" to me; it feels very narrow. The topics shortcuts give it a weird alignment, and I feel that perhaps the big sidebar is just serving to emphasise how much horizontal space is being wasted.

Also, on an iPad in portrait mode, the sidebar is very annoying. There really needs to be a button to hide it. The narrower width also makes code snippets basically illegible

ethankusters · February 17, 2022, 1:46am

I believe this was the exact rationale for the page design changes being discussed in the other thread: New Swift-DocC content styling. That pitch discusses moving the metadata information that currently occupies the righthand sidebar up into the top of the page to make room for the new navigation sidebar on the left.

When there’s an implementation available for that change, I’ll update the Argument-Parser demo site so we can get a feel for it.

benrimmington · February 17, 2022, 2:45am

It would be useful to have an alphabetical list of all types and protocols:

Could the sidebar have an additional "index" tab?
Or could the filter bar support this use case?
Or could a "site map" page be generated?

Could the sidebar icons also be used as the default favicon?

ethankusters · February 17, 2022, 7:07pm

By default this is essentially what DocC will produce. A documentation author can choose to organize the symbols in their project more specifically by putting them into topic groups: Swift.org: Arrange Top-Level Symbols Using Topic Groups.

The folks working on ArgumentParser have chosen to do this which is why you're seeing symbols grouped into more logical sections in the navigator for the demo I published.

Personally- I think the filter bar supports this use case well. The only time I would want an alphabetical list instead of an author-organized list is when I already know what I'm looking for or know at least part of the name of the symbol I'm looking for. In this case, using the filter bar seems like a faster solution than scrolling an alphabetical list.

From my perspective- the navigator should essentially be a site map. How would you see a more dedicated site map page behaving differently than the navigator?

I love this idea! Maybe the top-level technology star icon could be used? It might be odd for the favicon to change between pages but offering the top-level icon as a default seems like a great improvement.

taylorswift · February 17, 2022, 8:01pm

for me at least, 90% of the time i already do know part of the name of the symbol im looking for, i just need to fill in some blanks in my memory. aside from search, the most useful organization for me would be grouping by:

initializers
static methods (since these are often initializer-like)
instance properties
subscripts
instance methods
static properties
operators

in a well-designed API, the kind of a symbol (e.g., subscript) should already provide some hint as to its role.

if there too many instance methods to sort through, i am usually more interested in what protocol interface they are associated with than what “topic” they fall under. however, this type of organization is hard to implement with the information provided by the symbol graphs.

a site map is a search engine concept, like a robots.txt. unless you are referring to something different?

browsers cache favicons by default, even if no etag is provided. so you can serve a different favicon for each page if you want, but there’s no guarantee the user will see it.

Joseph_Heck · February 17, 2022, 8:36pm

Hi Beatriz,

The design and overall concept of the sidebar looks lovely. I explored it with @ethankusters temporary overlay of ArgumentParser.

Seeing the filtering, I immediately reached for it - and was a little surprised when content was highlighted by the filtering action. Then it was even more awkward as some of the titles that matched the filter value I used weren't easily visible in the sidebar, sort of highlighting the difficulty of the "too much horizontal space used by the sidebar" while also "not enough to be visible". (The article titles were frequently cut off)

I also think that using a tag (for example, to just show an article or tutorial) is completely opaque and if you hadn't called it out in your introduction, I wouldn't have had a clue that was an option. In fact, I'm not even sure today how to trigger the filter to just show articles within the module.

I think the filtering mechanism is important, and even better (and a much more involved implementation) would be a full fuzzy search that returned based on some amount of potential relevance. For either of these cases, I'd like to advocate for the possibility of having a separate result area displayed that shows the results, and leaving the side-bar and it's navigational structure untouched.

Since DocC is leaning into the SPA/javascript driven documentation rather than static rendering, this seems like it could be doable - and it preserves the navigational capability that the sidebar provides, which IMO is its single biggest benefit.

While I love the additional detail being available for the functions in the sidebar, as others have pointed out, it's pretty heavy space-wise, and might suggest that the most valuable thing to display is the symbol's name, followed by arguments. I do like the box to the left indicating the kind of symbol (protocol, struct, enumeration, class, etc), but it's the thing that allows me to disambiguate between two otherwise similar symbols. The cases where I've wanted or needed to that seemed to boil down to the arguments that a function or method took - and often the type associated with the argument - which is probably more than can easily fit in the sidebar.

I don't know who enabled the option-click-disclosure to fully expand a tree downward, but THANK YOU!!!! That's hugely beneficial, and far easier for me to navigate than the scroll-down-click-scroll-down-click sequences.

taylorswift · February 17, 2022, 9:39pm

yes, fuzzy search is a must. also, i noticed the search bar is at the bottom of the sidebar in the desktop layout, but it is at the top of the sidebar in the mobile layout. wouldn’t it be better the other way around?

rauhul · February 17, 2022, 10:12pm

Would it be possible to not have the footer extend under the sidebar? I find it a bit jarring to scroll to the bottom of the content view and have the entire page jump up due to the footer view.

benrimmington · February 18, 2022, 3:18am

Both kinds of navigation are useful: topic groups for new users, and default groups for quick reference.

For example, if we wanted to audit the missing conformances of Never (SE-0319), we'd need a list of all the protocols. We could search either the source code, or the generated documentation.

I'm not sure how it would differ from the navigator. Perhaps the nested hierarchy would be flattened?

(A long time ago, there was a site map page for the Foundation framework.)