Wow, this is a really terrific guide. It's quite long, but it's long because of it's breadth, not because of being overly verbose (IMHO). I particularly appreciate the clear explanations and large number of examples that really help make the concept more concrete. I think this is quite broadly useful even for people that don't work for Red Hat.
Yeah it reads like one to file away if I ever end up doing a lot of technical documentation. In this case, it's a guide that is aimed at an army of people (dozens? Hundreds? I don't even know, Red Hat has 19.000 employees) writing documentation as their day job. That is, I wouldn't be at all surprised if just the number of people writing documentation for RH is more than the number of engineers we have at my current employer (one of the major energy companies in the Netherlands).
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.
This seems like one of the perfect use cases for AI. Have the AI ingest the style guide, and then comment on your written work to point out where your work does not adhere to the style guide.
That’s the funny part, poorly written technical guides that breaks some of all these rules will be worth its weight in gold because you know a real human wrote it.
The only part that throws me for a loop is in the Grammar section, which contains a mix of best practices (like "Prefer active voice to passive voice") mixed with basic rules about subject-verb agreement. The former is what I would expect to see in a Style Guide, while the latter is, I dunno...what I would expect as a basic requirement for passing high school English?
It just feels like for the level of fluency presumably required for a Technical Writer, basic grammar rules should be well understood and not need to be explicitly stated.
> what I would expect as a basic requirement for passing high school English?
You're making the assumption here that the reader / documentation writer has had high school English; the documentation is written by and for non-English natives, too, and available in 7 non-English languages.
It seems you have a certain hyperfocus on inclusivity being mentioned, which is a shame; did you engage with the rest of the document with as much effort? Or do you have an agenda and/or an irrational emotional response to mentions of inclusivity?
Might be just my ESL self being silly but these examples both read horribly:
> For example, the sentence, "The Developer Center, a site for reference material and other resources, has been introduced to the OpenShift website." reads better than
Even without reading the next bit I just knew that no, this does not read better. The insertion of "a site for reference material and other resources" just makes this sentence horrible to follow period.
> "The OpenShift website introduces the Developer Center, a site for reference material and other resources." Here, the passive voice is better because the important issue ("The Developer Center") is the subject of the sentence.
This reads silly for another reason: websites don't... introduce things. Website owners might. Also, I feel it should say "reference materials" not "reference material".
> This reads silly for another reason: websites don't... introduce things. Website owners might.
That feels overly pedantic, and is incorrect. “Introduce” means “bring a subject to the attention of (someone) for the first time”. It doesn’t need to be done by a person.
It’s perfectly acceptable to say, for example, “The Shining introduced me to the horror movie genre”. That doesn’t leave room for doubt that you mean The Shining was your first horror movie. It would’ve been silly to say “Stanley Kubrick introduced me to the horror movie genre” just because you watched one of his movies.
Parts of this are excellent. I teach a contract-drafting course for 2L and 3L law students. Some aren't good writers. When I mark up their work, I can provide them with links to specific points in the RH guide.
Some parts aren't so great. Example:
> EXAMPLE[:] Remote users can connect to network resources simply by authenticating to their local machine. IMPROVEMENT[:] Remote users can connect to network resources by authenticating to their local machine.
It's not at all obvious that you improve the sentence by omitting "simply." You lose some compressed information: in this case, an implication that alternatives to local authentication might be more complex. This implication might be significant, to some readers and certainly to the writer.
Depending on where the emphasis is (which there is none in written form), it could be read as:
"How to connect to network resources simply? By authenticating to their local machine" (which I think is how you interpreted it)
or "How to connect to network resources? Simply by authenticating to their local machine" (which I think is what was meant)
The ambiguity itself is a good enough reason to not use this form. If the former was meant, say "the simplest way to connect to network resources is ...", otherwise just drop the "simply" as suggested
I think good technical writing is a lot like good interior design.
My brother is an interior designer who has done lots of work for hotels. He says that as an interior designer, people typically only notice your work if you’ve done it badly.
If you use a decently designed hotel room you don’t think much of it, but if it’s got problems like badly laid out space, even if you can’t quite put your finger on it, it feels “off”.
If a reader doesn’t have any opinions on a technical article and got the information they were expecting, then it’s probably well written.
When I write technical documents I aim to avoid anything in them which would detract from providing information as effectively and unemotionally as possible.
Extending the Interior Design metaphor, the context of what's being designed and for who, that is, the doc archetype (manual, tutorial/guide, reference, recipies/demos/samples, audience-specific), is the first important part to get right.
> technical documents I aim to avoid anything in them which would detract from providing information as effectively and unemotionally
why do people read docs ... because they want to achieve something ... you need to work out what problem your reader is trying to solve.
If Dusty wants to put their degree up on the wall, they might want to consult some documentation about how to do it. The documentation Dusty needs to do this would probably not be called "How to Choose a Drill". The documentation Dusty needs is "How to Hang a Picture".
That’s far from exclusive to interior design. Any designer in every discipline will be familiar with that notion, regardless of it being interior design, industrial design, graphic design, …
“Good design is actually a lot harder to notice than poor design, in part because good designs fit our needs so well that the design is invisible” — Donald A. Norman, The Design of Everyday Things (1988)
Pretty solid - I'll add this to my list that I refer to for writing. I often use the Australian Style Manual [0] and Divio Documentation System [1] as a foundation to technical writing and also user documentation.
Jargon. Say exactly what you mean, for example, "the best product in its class" or "the best product of its type". Other alternatives include best, foremost, most advanced, and optimum. The category is usually implied. Be wary of using superlatives without data to back up any claims.
bleeding edge
Do not use.
boil the ocean
Do not use. State exactly what you mean, such as "increase the scope hugely".
It makes sense too when you fully understand your audience isn't exclusively English; expressions will be more difficult to read for ESL, and difficult if not impossible to translate to a non-English language. And the docs site is available in 8 different languages.
With translation tools (from the past... 3 decades, starting with Babelfish) and modern-day documentation processing / retrieval tools (LLMs), simplicity, clarity and consistency are even more important. But it's timeless advice.
Bit weird that correct use of the language is part of a style guide. Perhaps this particular mistake happens often enough they felt the need to codify it?
Why do they have this in the list of examples of 'run-on sentences':
> Bad: To access your programs click the Start button.
> Improvement: To access your programs, click Start.
Sure, the improved version has added a comma, but the initial version is not a 'run-on sentence'; it does not contain 'two or more complete ideas that are joined without punctuation'. The comma here is completely intonational; it would not be needed if the word order was different, as in 'Click Start to access your programs'.
Anyone know why this was removed? It matches my training as a public-school student in the US, including in college while working on my Bsc in the natural sciences.
I was on Red Hat’s informal style committee (Word Nerds) which wasn’t specifically technical writing though we had technical writers on it. A lot was fairly detailed oriented stuff but we also covered more general topics.
33 comments
[ 3.8 ms ] story [ 63.0 ms ] thread* "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.
The only part that throws me for a loop is in the Grammar section, which contains a mix of best practices (like "Prefer active voice to passive voice") mixed with basic rules about subject-verb agreement. The former is what I would expect to see in a Style Guide, while the latter is, I dunno...what I would expect as a basic requirement for passing high school English?
It just feels like for the level of fluency presumably required for a Technical Writer, basic grammar rules should be well understood and not need to be explicitly stated.
You're making the assumption here that the reader / documentation writer has had high school English; the documentation is written by and for non-English natives, too, and available in 7 non-English languages.
> For example, the sentence, "The Developer Center, a site for reference material and other resources, has been introduced to the OpenShift website." reads better than
Even without reading the next bit I just knew that no, this does not read better. The insertion of "a site for reference material and other resources" just makes this sentence horrible to follow period.
> "The OpenShift website introduces the Developer Center, a site for reference material and other resources." Here, the passive voice is better because the important issue ("The Developer Center") is the subject of the sentence.
This reads silly for another reason: websites don't... introduce things. Website owners might. Also, I feel it should say "reference materials" not "reference material".
That feels overly pedantic, and is incorrect. “Introduce” means “bring a subject to the attention of (someone) for the first time”. It doesn’t need to be done by a person.
It’s perfectly acceptable to say, for example, “The Shining introduced me to the horror movie genre”. That doesn’t leave room for doubt that you mean The Shining was your first horror movie. It would’ve been silly to say “Stanley Kubrick introduced me to the horror movie genre” just because you watched one of his movies.
All of these had in-house printshops, so would have had some style guides even if just to provide consistency for internal use.
Some parts aren't so great. Example:
> EXAMPLE[:] Remote users can connect to network resources simply by authenticating to their local machine. IMPROVEMENT[:] Remote users can connect to network resources by authenticating to their local machine.
It's not at all obvious that you improve the sentence by omitting "simply." You lose some compressed information: in this case, an implication that alternatives to local authentication might be more complex. This implication might be significant, to some readers and certainly to the writer.
"How to connect to network resources simply? By authenticating to their local machine" (which I think is how you interpreted it)
or "How to connect to network resources? Simply by authenticating to their local machine" (which I think is what was meant)
The ambiguity itself is a good enough reason to not use this form. If the former was meant, say "the simplest way to connect to network resources is ...", otherwise just drop the "simply" as suggested
My brother is an interior designer who has done lots of work for hotels. He says that as an interior designer, people typically only notice your work if you’ve done it badly.
If you use a decently designed hotel room you don’t think much of it, but if it’s got problems like badly laid out space, even if you can’t quite put your finger on it, it feels “off”.
If a reader doesn’t have any opinions on a technical article and got the information they were expecting, then it’s probably well written.
When I write technical documents I aim to avoid anything in them which would detract from providing information as effectively and unemotionally as possible.
https://github.com/google/opendocs/tree/main/project_archety...
> technical documents I aim to avoid anything in them which would detract from providing information as effectively and unemotionally
https://www.thegooddocsproject.dev/tactic/ia-guide / https://archive.vn/rgt4Y“Good design is actually a lot harder to notice than poor design, in part because good designs fit our needs so well that the design is invisible” — Donald A. Norman, The Design of Everyday Things (1988)
[0] https://www.stylemanual.gov.au/ [1] https://docs.divio.com/documentation-system/
e.g.
best-of-breed
Jargon. Say exactly what you mean, for example, "the best product in its class" or "the best product of its type". Other alternatives include best, foremost, most advanced, and optimum. The category is usually implied. Be wary of using superlatives without data to back up any claims.
bleeding edge
Do not use.
boil the ocean
Do not use. State exactly what you mean, such as "increase the scope hugely".
With translation tools (from the past... 3 decades, starting with Babelfish) and modern-day documentation processing / retrieval tools (LLMs), simplicity, clarity and consistency are even more important. But it's timeless advice.
https://www.google.com/books/edition/The_IBM_Style_Guide/77W...
Bit weird that correct use of the language is part of a style guide. Perhaps this particular mistake happens often enough they felt the need to codify it?
> This book belongs to whomever purchased it last week.
That should be "to whoever", surely? The pronoun is acting as the subject of the verb "purchased".
> Bad: To access your programs click the Start button.
> Improvement: To access your programs, click Start.
Sure, the improved version has added a comma, but the initial version is not a 'run-on sentence'; it does not contain 'two or more complete ideas that are joined without punctuation'. The comma here is completely intonational; it would not be needed if the word order was different, as in 'Click Start to access your programs'.
I tried tracing the history back in Github, and it seems that the intent was to prohibit the use of em dashes in normal prose:
> In technical content, use a dash to show a range. Otherwise, use a colon or other suitable punctuation. Do not use em dashes.
https://github.com/StyleGuides/WritingStyleGuide/pull/618
Anyone know why this was removed? It matches my training as a public-school student in the US, including in college while working on my Bsc in the natural sciences.