←back to thread

Red Hat Technical Writing Style Guide

(stylepedia.net)
186 points jumpocelot | 2 comments | 10 Jul 25 15:01 UTC | HN request time: 0.558s | source
Show context
kaycebasques ◴[10 Jul 25 17:24 UTC] No.44523298[source]▶
Looks solid. My gripe with most technical writing (TW) style guides (this one included) is that they mix best practices with conventions:

* "Best practices": Aspects that tangibly improve docs quality. Usually backed up by experimental data or overwhelming consensus.

* "Conventions": Arbitrary decisions that don't clearly improve docs quality one way or the other, except for the fact that they improve consistency, and consistent docs are easier to use.

When everyone in the room has this shared understanding, TW style guide conversations often go much faster and smoother.

replies(2): >>44523477 #>>44527957 #
lelandfe ◴[10 Jul 25 17:39 UTC] No.44523477[source]▶
I’m not sure I see the upside. Do you have an example you like?
replies(2): >>44523682 #>>44523896 #
1. dsr_ ◴[10 Jul 25 17:56 UTC] No.44523682[source]▶
It's a best practice to set commands that are to be typed literally in a different typeface.

It's a convention that most documents use a monospaced courier or monospaced grotesk as that typeface.

replies(1): >>44527344 #
2. gjm11 ◴[11 Jul 25 00:48 UTC] No.44527344[source]▶
Using a monospaced typeface for that purpose isn't only convention; it reflects the fact that when those commands are typed literally, it will be in a terminal which almost certainly itself uses a monospaced typeface. I think I'd say that setting literal command text in a monospaced face is a best practice.

[EDITED to add:] I agree with the general point about distinguishing best practices from conventions, though. (But there are also intermediate possibilities. "Best practice for us because it fits with conventions we've become used to". "Best practice for us because of some peculiarity of us or our work, even though for other groups it might not be so good".)