Red Hat Technical Writing Style Guide

Overall impressions and audience

• Many readers praise the guide as unusually thorough yet concise for its breadth, with clear explanations and plentiful examples.
• Seen as broadly useful beyond Red Hat, but particularly suited to large organizations with many docs authors who need strong consistency.
• Compared to Google’s tech-writing material: Google’s is viewed as a short, “tutorial/how‑to” for beginners; Red Hat’s as a deeper reference for people who already value style systems.
• Some readers plan to cross‑reference it with other style systems (IBM, government style manuals, Divio documentation system).

Red Hat documentation and access

• One commenter claims Red Hat “does not write documentation,” but others strongly disagree, citing its professional distro docs and high‑quality man pages.
• Confusion and frustration around paywalls/regwalls: knowledge-base (KCS) content often needs an active subscription, which some admins don’t personally have despite managing many RHEL systems.
• Others counter that core docs are public and a free developer subscription unlocks the knowledge base, though policies are criticized as adding needless friction.

Best practices vs conventions

• Several participants argue style guides should clearly separate:
  • “Best practices” that measurably improve clarity and usability.
  • “Conventions” that are arbitrary but useful for consistency.
• Example: marking literal commands as distinct text is a best practice; choosing a specific monospaced font is a convention.
• This distinction helps writers prioritize limited editing time and reduces review friction.

AI as style enforcer

• Multiple people see this guide as an ideal target for AI‑based “style linting”: ingest the guide, then flag violations in drafts.
• Others report experiments: best results come from multiple focused passes or fine‑tuned models, but feature engineering and training data are labor‑intensive.
• Skeptics worry about “machine‑mangled slop,” but some maintainers say LLM‑assisted docs are still better than having no docs at all.
• A prototype multi‑pass tool using this guide showed promising but curator‑dependent results.

Debates on specific guidance

• Some dislike mixing basic grammar (who/whom, pronoun agreement, apostrophes) with higher‑level style; others note many engineers and non‑native speakers still need explicit grammar rules.
• Active vs passive voice: guide prefers active, but commenters stress passive can be clearer when the actor is irrelevant or ambiguous; some provided examples in the guide they found awkward or unidiomatic.
• Strong pushback and defense around inclusive language (e.g., avoiding “sanity check,” neurodiversity references, “guru/ninja/rockstar” titles).
  • Critics see some of Section 4.6 as overreach or distracting from the rest.
  • Supporters argue language routinely evolves, inclusive terms can be both more precise and more respectful, and style guides should lead on this.
• Jargon and buzzwords like “best‑of‑breed,” “bleeding edge,” “boil the ocean” are applauded as things to avoid, especially for ESL readers and translation; suggestion to frame this as “use widely understood language” rather than “state exactly what you mean.”
• Several nitpicks on examples (run‑on sentence classification, “reference material(s),” who/whom correctness, em‑dash policy changes), showing that even style guides invite meta‑editing.

Philosophy of technical writing

• One view: good tech writing is like good interior design—mostly invisible; readers just get what they need without friction, neutral and unemotional.
• Counterview: some of the best technical authors use voice and personality; “flair” can make material more engaging but may be harder for localization and inconsistent across large teams.
• Many agree that a baseline of reliable, accurate, and consistent docs is more important for an organizational guide than encouraging individual literary style.