Use of letter spacing in DocC

So far I've really been enjoying DocC... except for one thing. I feel like the text can be quite hard to read.

One thing that I've noticed is that the default (core) theme used by swift-docc-render uses the same, very precise letter spacing values as Apple's documentation site. But there's a big difference between them: docc-render uses Helvetica by default, while Apple's documentation has a preferred list of proprietary fonts which it will use instead.

Apple's custom font, at least to my eyes, keeps the spaces between letters more easily discernible at smaller sizes - so even at tighter letter spacing, it's easier to read. Helvetica doesn't seem to appreciate this spacing and some words almost bleed together at comfortable reading distances and even up-close.

There are all kinds of other differences, because they are different fonts (e.g. commas extend further below the baseline, which also makes them easier to read at smaller sizes), but I wanted to point out that using the same values for both can lead to some poor results.

Click the screenshot to open it in Discourse's popup thing, and you can press the left/right arrows to flick between them. One of them clearly has wider letter spacing than the other, despite having the same CSS letter spacing value. (I don't think I need to say which one is which).

This also applies to things like code samples, and the little bits of code containing declaration name, as DocC reduces the default letter-spacing of these things ever so slightly.

Multiply this 10pt text, with too-tight spacing and high contrast, across an entire project, and you get the feeling something is just wrong with DocC's output.


Thanks for the feedback! I generally agree that there are various typographic elements that could be adjusted to improve the readability of text to better fit with the base Helvetica font family. I filed the following Jira issue to track this: Improve legibility of typography elements for base Helvetica font

Also, in your screenshots, I'm seeing text at the end of the first paragraph that is only italicized in one of the screenshots, which may be a possible bug. Can you possibly file an issue for this with information on the environment where the text is not being italicized?


Unless DocC wants to include custom fonts, it might be best to use the system fonts, rather than Helvetica, so that each platform uses the most optimized font as chosen by the browser. StackOverflow recently did the same thing and I appreciate the readability improvements.

Terms of Service

Privacy Policy

Cookie Policy