Red Hat Technical Writing Style Guide

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.

I’m not sure I see the upside. Do you have an example you like?

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.

I tried to do this back when I was content lead for web.dev: https://web.archive.org/web/20230329155818/https://web.dev/h...

Almost everything in there falls under the "best practices" bucket and there is little discussion of "conventions". If I did it again today, I would try to provide lots more justification and evidence for each guideline.

The upside is that authors focus their limited time/energy on the edits with the highest ROI. E.g. if the author only has time to either A) make the content more scannable or B) use Oxford commas everywhere, I would much prefer that they spend their cycles on A. This doc also reduced friction at review time. When some proposed new content didn't meet my quality bar for whatever reason, I would point the author to specific sections of this doc and ask them to revise their draft based on these guidelines.

During a code review, a request to fix a race condition is much higher priority than a name improvement. I'm arguing that TW style guides need a similar type of distinction.

I can pick out specific examples of best practices versus conventions in the Red Hat guide if it's still not clear.

Especially since AI grammar tools automated B for years now.

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".)

I’ve been on both sides of this, and I’ve come to the realization that it depends on the audience of the writing. It seems like this is for Red Hat authors writing miscellaneous docs for a range of users. Consistency is important there, so that Red Hat seem consistent in their messaging, as a single user could be reading material from many authors. It would look sloppy if the small stuff is all over the place.

Many times, a user receives communication from a single writer. This could be a consulting arrangement, or a small company, or any number of cases really. Those users are probably going to be consistent with themselves anyway, so there’s less need to be as specific on the small stuff. In that case a guide is really just trying to knock off the obvious rough edges in someone’s writing to make sure they’re actually communicating the information.