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?

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.