Aside and Header presentation in swift-docc-render (warning: images)

There are 2 style issues I'd like to raise with the current default docc-render theme.

These are both cases where I feel the docc-render output is significantly worse than what is available in Xcode's documentation viewer or the Apple developer website.

Now, it seems clear that Xcode and Apple's developer website like to maintain some distinctive style elements for differentiation (such as a custom font), and that's all well and good. I'm not advocating for simply copying Apple's style in its entirety -- but there are instances where I feel the differences skew too far towards penalising the docc-render presentation. And I don't think anybody wants that.

So I'd like to start a discussion about whether these changes are intentional, whether we agree that the difference is negative for legibility, and whether the docc-render team would be open to changes.

Aside presentation

Asides are the little boxes that appear when you write > Note:, > Tip:, > Warning: sections, etc. In the Xcode documentation viewer and Apple's website, they present as nice colourful boxes:


....

....

But with Docc-render, they are all grey boxes with little in terms of visual differentiation :frowning:

This makes it more difficult to author content, as a sequence of [code snippet, tip, throws] (throws always comes last, so you couldn't move it even if you wanted to) presents as 3 very distinct sections in Xcode's documentation viewer, but as 3 bland, cluttered boxes on the web:


....

...

Personally, I think the flat design used by Xcode and Apple's website is more in keeping with the rest of docc-render's aesthetic - but regardless, we need the colours!

Header presentation

Currently, swift-docc-render uses normal font weights for headers (with larger sizes).

This can be important - I try to make sure that my documentation is not too messy visually, and a big part of that is making sure that bodies of text which are likely to occupy more than one screen are broken up in to easily-digestible chunks. I sometimes go back and tweak code-snippets just so that they present as a more visually harmonious whole.

Headers in DocC-render do not have a lot of blank space around them, which means a normal-weight header does not have the same presence in the text as a weightier font. In larger articles, they almost blend in to the body.

The Apple documentation site uses semi-bold weights for its custom font. I've tweaked the font weights in a fork I'm using (not quite as weighty as Apple's site, because I'm using Helvetica, but heavier than normal), but I've found the results to be really transformative.

(Note: This may be related to Use of letter spacing in DocC)


2 Likes

FWIW, I've tweaked these things in a fork (along with one other thing - see if you can spot it :upside_down_face:). Unfortunately, I can't host 2 copies to show the difference, but I can link to some sections which I think really benefit.

WebURL.binaryFilePath - Has the aforementioned [snippet, tip, throws] sequence at the end. The tip now has colour! And looks more welcoming and positive!

(and yes, I spotted the typo on that page. I would also love a spelling & grammar checker in DocC :heart_eyes:)

IPv6Address - The overview sections, like "Connecting to an Address", are much more easily discernible with weightier h3 headers. It really turns this section from "amorphous block of text" to "small, clearly structured islands of information".

Additionally, the fork removes the tighter spacing for body and code text mentioned in the previous thread. So that's why that might look different. But I think the result of these 2 tweaks in particular makes the result so much more readable. I'd love to hear what you think about making those tweaks to the default style, too.

3 Likes
Terms of Service

Privacy Policy

Cookie Policy