Hi folks, I have another design update to the new Swift-DocC sidebar experience. We've redesigned the main page body content to optimize spacing and flow better at different sizes and configurations.
The key visual changes here are:
A new title image. This image is automatically generated with new icons based on the content type of the page.
Updated language selector, availability and metadata placement. Since the sidebar occupies at least a full column, we moved the metadata information to optimize space. The language toggle now lives in the local navigation bar, the availability information in the title image and the technology metadata in a ribbon below the title image.
I'm not sure about this, though. The background images feel a bit out of place. Generally DocC-Render has a clean, professional, minimalist aesthetic, and these don't quite feel in keeping with that, IMO.
I like the idea of having this "hero area", but I think the information could be optimised. What we see here are a couple of pieces of information:
What this symbol is: an instance method
What this symbol is called: cornerRadius(_:antialiased)
Where the original declaration of this symbol came from: inherited from View.cornerRadius(_:antialiased)
Which platforms you can use the symbol on: iOS 13.0+, macOS 10.15+, etc.
Which framework the symbol lives in: SlothCreator
Some of that information is necessary to introduce the symbol: I need to know what kind of symbol it is*, what its name is, and its availability. But not all of that information needs to be known as part of an introduction: in particular, the part about being inherited from View.cornerRadius(...) seems like a detail that doesn't need to live in the header, and the "Technology" bar also seems superfluous - I generally already know which package/framework I'm looking at, and if there was any doubt, that information is already prominently displayed at the top of the sidebar (and also generally in the breadcrumb bar).
* Even that could be given a bit less prominence.
IMO, the header should be like a very brief introduction. Like the first sentence you would say when introducing people who have never met.
Also, the header is dark even in light mode. Will it still be dark in dark mode?
It appears there is no PR yet for this change (which is fine). It would be nice if you could post an update when an implementation is available, so we can test it locally and give feedback about how well it applies to our documentation bundles.
Again, very much +1 to the concept. I think some parts could be tweaked, but I really like the direction of these changes and the sidebar.
That PR doesn't have all of the changes proposed here but the demo should still give a pretty good idea of the pitch. I'll try to keep it updated as things develop here.
I totally see your point. By default, we can have have a simple design like the one in these screenshots, though I appreciate your feedback— will continue to investigate whether the default options should be simpler. For example, just a solid color. Eventually, I'm excited for this to be a customizable component.
I agree this information should be optimized. We've decided to remove the technology bar for pages that only belong to one technology and it's clear from the navigator what technology the page belongs to. We'll keep support for the technology bar in to allow for situations where a page might belong to multiple technologies, but this isn't something DocC supports today so we can revisit that decision in the future when it's more relevant.
The text below the page title continues to be the summary for that page. The "Inherited form View.cornerRadius(...)" is a bit of a confusing example, but that's actually content generated by Swift-DocC itself and something we'd like to improve there. For the common-case where you've written a documentation comment for that symbol, the symbol's summary would be rendered here. That's better represented in the other screenshots I shared above, for SlothCreator and Sloth.
For this initial version, the header image looks the same in both modes. Here’s a dark mode screenshot.
I had a quick go at prototyping it using the WebKit inspector. I appreciate you continuing to refine the default options, and customisation would definitely be welcome as well (I understand that's a bigger topic for DocC-Render).
Looking at some of the other pages from Ethan's argument parser demo, I wonder how well this scales. If the summary is small, things work relatively well. But this page, for example, has a 3-line summary.
At that point, you're basically reading the documentation of the symbol as centred text in the header, which doesn't feel very comfortable. Meanwhile, the content space below shows "No overview available".
That's quite unfortunate, because AFAIK there is no way to have the longer overview text without a summary.
I'm not sure if DocC-Render can be smarter about detecting these situations (and perhaps treat a long summary as an overview), or if the documentation just needs to be restructured to account for the new page style. In this case, I think a shorter summary is possible, but perhaps that is not always the case.
Another thing I wonder about with these design changes is what the plan is for the table of contents ("On This Page"). Is the idea to remove it? Will it be replaced with anything?
Not sure if this has been mentioned, but the sidebar is unscrollable on (at least my) iPhone—at least if I’ve scrolled the main content down and back up, although it seems to work inconsistently even without that interaction.
Just wanted to quickly chime in on this specific point and mention that the "No overview available" bit (separately from your overall feedback) is a bug. We should only be rendering "No overview available" if a page is missing a summary entirely.
Can the sidebar be hideable/collapsable? It feels like a distraction when I want to focus on reading a long documentation page.
Additionally, I agree with the opinions expressed upthread that the background image and centered heading creates visual clutter.
I compared my experience on the 2 versions of the linked documentation. When reading in the current/old style, I can get all the information in just one glance. In the new proposed style, I find my eyes wondering about searching for information. This might be because the linked pages have no description in their documentation (my experience with longer description is better (e.g. Documentation and Documentation)). However, there are a lot of APIs with very little description in documentation, and imo they should read as easily as more richly documented ones.
I don't like the hero header design. I think the header background should be much closer in colour to the rest of the page (I don't mind the two-tone palette, but it needs to be far more subtle than stark black vs. white) and the text should all align to the same left margin.
Yup, it’s intentionally removed from these pages. I think we should consider this as an enhancement for the sidebar itself — including in-page links in the tree itself.
There's been quite a bit of feedback in this thread about that element of the page, but I'm grabbing this specific line because it captures the spirit of all the feedback well. I think it's hugely important to have a clear distinction between introductory content (title, availability, meta-data-type information) and docs content, and I agree that this element can be simplified on simpler pages. I think we can also establish a stronger hierarchy between separate pages by reducing the impact of the introductory visuals on symbol pages.
my experience working on swiftinit.org has taught me this doesn’t really scale well because it entirely depends on the package author(s) to correctly split their doccomments into a blurb and longer discussion. for example, from the NIOAny docs:
it’s not reasonable to expect package authors to anticipate this issue, since it’s not really obvious until you build the docs and browse through them. i suspect this is why jazzy does not show introductory blurbs by default.
personally, i feel that overly-long introductory blurbs are better than no blurbs at all, which is why swiftinit still displays them. but i haven’t really come up with a good solution for this.
Thanks again for all the feedback on the documentation page redesign. I have an update on new refined visuals. In order to optimize for different types of content, there now are two different types of header sections. One for symbol pages, such as protocols and functions, and another for non-symbol pages, such as frameworks, articles and API collections.
Non-symbol pages have stronger visuals, and help establish a hierarchy with the pages organized under them. These include frameworks, articles and API collections.
This looks great! I’m in favour of using the stylised header for the framework page and articles, and the regular header for symbol docs. It brings forward the higher-level “conceptual” content, while keeping “reference” content clean and to the point.
The one piece of feedback I have would be regarding the platform tag pills in the stylised header. They don’t seem very accessible since they’re grey on a dark background. Have you considered making them a bit lighter?
