Pick a style guide

[davidjharder]

It would be nice if our docs conformed to a style guide, let's pick an existing one.

@deoxys94 had some good suggestions over on PR #380

• Google
• Microsoft
• I found Redhat, which has guidance for many linux specific topics

[deoxys94]

Hi @davidjharder

I've come across another style guide that's definitely worth considering: the SUSE style guide.

After reading all the style guides, here are my thoughts: For simplicity and ease of use, I believe the Microsoft and Google style guides are the top picks. They cover a wide range of topics and scenarios, including grammar and punctuation (personally, I lean towards Microsoft's guide). Plus, their detailed guidance makes it much easier to follow and implement.

If having guidance on Linux-specific topics is preferred, I think the SUSE guide is the best choice, as they cover grammar and punctuation. True, some extra effort would be required to adapt the formatting to markdown, but I don't see that as a major hurdle.

I love the Red Hat guide. However, it barely covers grammar and punctuation (everything is contained on the IBM guide). If the IBM style guide was available online, I'd choose the Red Hat guide right away.

Here are my thoughts on each guide:

Red Hat

Pros

• This style guide is amazing! It provides clear guidance on how to write documentation that is:
  • Scannable.
  • Easy to understand.
  • User centric.
  • Minimalistic.
• The guidelines on how to use admonitions are fantastic.
• Includes advice on Linux-specific topics, for example, including commands and code snippets in documents.
• Recommends using variables/conrefs/imports/components for the product names and other branding to ensure consistency.

Cons

• Since this is a supplementary style guide, it doesn't include guidance on topics like punctuation and grammar.
• It heavily relies on the IBM Style Guide, which is not available online.

SUSE

Pros

• Just like Red Hat, it provides clear guidance on how to write minimalistic, user-centric documentation.
• Explains how to split documentation into topics.
• The guidelines on how to use admonitions are similar to Red Hat's.
• It also includes Linux-specific topics, and I think this one is slightly more detailed than Red Hat's.
• Bonus topics: Writing SEO-friendly content, and recommendations on structuring topics (articles).
• Includes guidance on punctuation and grammar.
• Recommends using variables/conrefs/imports/components for the product names and other branding to ensure consistency.
• Defaults to Merriam-Webster and Chicago's guides (both available online) for style concerns not covered in the style guide.

Cons

• The guide focuses on how to use DocBook and DocBook elements. Some extra effort would be required to define the equivalents in markdown.

Google

Pros

• It's a friendly, easy-to-use style guide that provides guidance on things like grammar, punctuation, documenting interactions with the UI, and procedures.
• There are lots of examples for each rule/topic they include.
• They also include guidelines that can be applied to documenting interactions with Linux systems.
• Uses HTML/plain English terms to explain the formatting documents should have (they say to use bold/italics/etc.) instead of a specific system (DocBook, AsciiDoc, etc.).
• I really like how they promote writing timeless, easy-to-read documentation.
• Defaults to Merriam-Webster, Chicago, and Microsoft's guides (all available online) for topics not covered in the style guide.

Cons

• The guidelines on how to use admonitions are a mixed bag. On one hand, I like that they recommend keeping admonitions at a minimum at all times. On the other hand, their recommendation on what types of admonitions to use (note, warning, etc.) is a little ambiguous.
• They have some recommendations that can lead to topics with fluff/superfluous sentences. For example:
  • Having introductory sentences in procedures. The type of introductory sentences they recommend is considered fluff by other style guides as they provide no value to the user.
  • Having introductory sentences in some figures/code snippets.

Microsoft

Pros

• It's one of the most popular style guides out there. Some even consider it the gold standard of tech writing.
• Just like Red Hat, it provides clear guidance on how to write minimalistic, user-centric documentation.
• It includes guidance for various aspects (grammar, punctuation, etc.) and scenarios (writing content for chatbots, UX writing, API writing, etc.).
• Their guidelines on writing step-by-step procedures are fantastic; they focus on clarity and simplicity.
• They also include guidance on how to plan and design content.
• Defaults to the Chicago style guide for style concerns not covered in the style guide.

Cons

• No advice or guidance on admonitions.
• Since this style guide covers a wide range of topics, it doesn't include anything Linux-specific.

[davidjharder]

Thanks for summarizing all this

[davidjharder]

Here are my thoughts after staring at some of these for a while:

Our style guide should not be very long and should mostly lean on other style guides. I would propose that we link to one of the more general style guides (Microsoft or Google), then write specific guidance for how we want very particular things done. Fundamentally I want this to be a quick reference for contributors; not a meditation on the English language, as interpreted by a bespoke linux distribution.

Examples of specific guidance:

• The snag deoxys94 hit: how do we style package names, particularly repeated uses, or when they are mixed with short commands (install operations often have this issue).
• Admonition guidance. Here we can crib directly from RH, while also pointing to the Docusaurus docs as syntax reference
• American or British spellings?
• How we name Solus things:
  • Is it "Solus" or "the Solus Project"
  • Do we say "the monorepo" or "the packages repository
  • Short forms: PRs, dev, repo, etc. and other latin
  • and many others

Thoughts on specific guides

• After a closer look, the Red Hat guide is too short and references the IBM guide too much to be useful as a general guide, but:
  • We can borrow their guidance for admonitions though, it is concise.
  • We should point users to their "glossary of terms and conventions" for specific linux terms
• SUSE is much too focused on translating content into their preferred asciidoc formatting, not really useful as a reference we can point contributors to. I don't want to "translate" their docs to markdown. Don't like it, might be a personal taste thing.
• Generally, I prefer the Google guide over Microsoft
  • It is shorter and example focused.
  • It has good one-page summaries for subjects, example: https://developers.google.com/style/text-formatting