New Swift-DocC content styling

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.

This is reproducing for me as well. Thanks for bringing it up! I've filed [SR-15904] Navigator sidebar scrolling is broken on mobile - Swift to track this.

1 Like

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.

For example, here's ArgumentParser's official GitHub pages documentation site: https://apple.github.io/swift-argument-parser/documentation/argumentparser/completionkind/shellcommand(_:)/

And then here's the same page but on the version with the navigator sidebar: https://ethan-kusters.github.io/swift-argument-parser/documentation/argumentparser/completionkind/shellcommand(_:)/.

I've filed [SR-15903] "No overview available" text appears on pages that have a defined abstract - Swift to track this.

1 Like

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.

2 Likes

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.

2 Likes

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.

1 Like

We’re discussing this in the sidebar thread: Swift-DocC sidebar — tldr; yes we are trying this out, I think it’ll be a nice improvement as well.

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.

2 Likes

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.

Hi all,

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.

Symbol pages have a simpler design that optimizes for long titles and establishing more balance with declarations and code snippets.

9 Likes

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?

2 Likes

This is exactly the kind of thing I was hoping for :) Looks great.

3 Likes

Thanks Franklin!

That's a fair concern. I double checked, the labels are accessible with a good ratio (6.61 :1).

3 Likes

I've updated the ArgumentParser demo on my fork with the latest changes @beatriz described above.

This should give a good feel for how those changes affect the documentation browsing experience in practice.

1 Like

Hi @beatriz! Thanks for you amazing work in the DocC so far! I have a small request regardless the color of the color scheme control. It's almost a 100% blue in light mode.
image
The dark mode one is a little more subtle.

image

It would be great if you could tweak it a little!

2 Likes

Hi @mtsrodrigues! Thanks a bunch :)

This blue is a web-safe color which works across all browsers. In dark mode, it needs to be slightly different so it has an accessible contrast ratio.

If you feel strongly about this, you can open a PR with a new color and your rationale behind the change. I’ll be happy to share my feedback.

I recommend you pick colors that are also web safe. Also good to keep in mind this swatch is used for links and buttons across the board in docs, so the new blue should probably work there as well.

Are there any devices supported by Swift (let alone the compiler) which would ordinarily be used with a 256-color display but otherwise could render a DocC page fully featured? Even if there’s the odd exception, I’d optimize for accessibility and aesthetics over that corner case.

3 Likes

You're right @xwu, web safe colors are much less of a concern nowadays. The goal with the initial color choice was to create a brand-agnostic palette that worked for everyone (even on super old computers). Optimizing for accessibility and aesthetics is a solid plan.

1 Like

I'm excited to announce that the new Swift-DocC content styling changes described here have been enabled by default in Swift-DocC-Render with:

I've updated the ArgumentParser demo with the latest changes: https://ethan-kusters.github.io/swift-argument-parser/documentation/argumentparser/.

I've also added instructions for trying out these changes with your own package to a post on the Swift-DocC sidebar thread so I recommend following those if you'd like to see how things look with your own projects.

If you encounter any issues while trying things out, a bug report on bugs.swift.org (and soon GitHub Issues) would be really appreciated.

- Ethan

6 Likes

So I had a bit of time to try this out.

It's nice, and I quite like navigating using the sidebar. I'll be filing issues for some interaction issues I've encountered, but overall I think it can be an improvement.

One thing that I have noticed, though, is that it can be very distracting. You're reading this clean, calm, neatly-structured article, but the sidebar creates quite a lot of distracting noise in your peripheral vision. It doesn't make for a nice reading environment, so I'd like an ability to manually hide the sidebar, even on desktop browsers.

Within the sidebar, I feel that topic headers could be much more distinct. Topics break complex APIs up in to clear sections, and we should be using them to make the sidebar feel less cluttered. Here's an example of what I mean: imagine I'm reading some content, and then I glance at the sidebar shown below to navigate somewhere else. All I see is a wall of text; it's disorientating.

If we underline the topic headers, things actually get a lot better (the full extent may not come through on the screenshot). Just at a glance, I immediately know roughly where I am, and where the islands of content are. It's just a lot easier to navigate.

-

I don't think the underline style specifically is quite "it" (underlining usually implies a link. Ideally, I would like more vertical space, but it appears the vue component needs rows of equal height). But I do think it demonstrates that we can visually reinforce the structure of the content in the sidebar, and in doing so, also make it feel less messy.

The most concerning part of the redesign IMO isn't actually the sidebar, though - it's the topic sections. This is what they look like before (i.e. now/pre-redesign), notice how well they break a complex type up in to clear islands of functionality:

But here's the same page in the redesign:

I'm not sure this is an obvious improvement. Especially on mobile:

The mobile design actually helps highlight some areas of the new content design which do not quite feel balanced:

This is the main "title" element you see everywhere, and previously there was a nice balance between the little "structure" header at the top (called the 'eyebrow'), the title, and the description. But with the redesign, they appear too close together, and the horizontal margins have shrunk, causing what used to be a very professional-looking design to seem somewhat... less refined.

With some adjustments, it is possible to improve the output:

This also affects the regular, non-mobile site. Titles are just not quite as balanced as they used to be, and together with the new topic sections, it still feels like there are rough edges.

Since this is the fist time I've updated my personal fork of DocC-Render, it's worth pointing out again what IMO is the single biggest issue towering over all of these design niggles, which is that font weights and spacing are tuned for Apple's proprietary fonts, not Helvetica, which is what the open-source DocC-Render actually uses. By adjusting the weights to match the same values in Apple's font, and setting all spacing adjustments to 0, you can drastically improve the DocC-Render output. Especially in the sidebar, actually - the current settings squash sidebar items quite severely. It's better to not use any font-spacing adjustments than to use the wrong adjustments. [SR-15567] Improve legibility of typography elements for base Helvetica font - Swift

Example 1:

Example 2:

Anyway, overall it's really nice. Like I said, I can imagine getting used to navigating with the sidebar very quickly! But the design tweaks will need time to settle and to iron out all the wrinkles.

11 Likes