Re: [PATCH RFC] Documentation: typography refresh

[Randy Dunlap]

Hi Bagas,

On 6/18/25 9:23 PM, Bagas Sanjaya wrote:
> At present, kernel documentation uses system serif font for body text.
> Some people, however, objected to it and instead prefer that the
> typography choice must be legible, consistent, and accessible (after
> all, the audience ranges developers peeking into kernel internals to
> ordinary users that skimmed through Documentation/admin-guide/).
> 
> To tackle the problem, follow Wikimedia's typography refresh [1].
> For the font choices, instead of using web fonts as in previous
> attempt [2], use:
> 
>   * Linux Libertine, Georgia, Times for serif (used in h1 and h2
>     headings)
>   * system font for sans-serif and monospace
> 
> This allows for more readability and consistency without sacrificing

More readability is debatable IMO.

> page load times and bandwidth, as the font choices is most likely
> already available on many platforms.
> 
> The reason why serif fonts is used for headings in complement to sans
> serif in text body is to break up visual monotony of docs page by
> creating contrast between headings (as entry point to docs information)
> and text body, which is important considering that kernel docs are
> quite lengthy with many sections.

It's interesting that mediawiki chose to split the serif and sans serif
usage this way. Newspapers essentially do the opposite: use sans serif
for headlines (mostly, not consistently) and use serif for body text.


Have you read "The Psychology of Computer Programming"?
[https://geraldmweinberg.com/Site/Programming_Psychology.html]
The content is very good but (at least in early editions) it was printed
completely using a sans serif font (probably Helvetica). It's not a
long book and I found the subject very interesting, but it took me
forever to read it because it's (or was, don't know about the later
editions) in sans serif typeface. I hated that part of it.

So I applied this patch and tested it. It works as far as I can tell.
I got tons of sans serif font text instead of serif font text that I
don't care for. (I don't mind that the sidebar text is sans serif.)



> For body text (excluding sidebar), it is set to #252525 on top
> of #FFFFFF background as they have contrast ratio 15.3:1, which
> is rated as AAA according to WCAG 2.0 section 1.4.6. Having slightly
> off-black foreground text on white background can reduce eye strain
> and juxtaposition on dyslexic readers.
> 
> This refresh only applies to default Alabaster theme.
> 
> [1]: https://www.mediawiki.org/wiki/Typography_refresh
> [2]: https://lore.kernel.org/linux-doc/20231102123225.32768-1-bagasdotme@xxxxxxxxx/
> 
> Signed-off-by: Bagas Sanjaya <bagasdotme@xxxxxxxxx>
> ---
>  Documentation/conf.py                      |  5 +-
>  Documentation/sphinx-static/typography.css | 62 ++++++++++++++++++++++
>  2 files changed, 66 insertions(+), 1 deletion(-)
>  create mode 100644 Documentation/sphinx-static/typography.css
> 

Thanks.

-- 
~Randy