Add a documentation style guide

[mojavelinux]

A documentation style guide would be a useful tool for writers within this community. The guide would help ensure that documentation within this community remains consistent and uniform. It would also make writing easier as it would save writers from having to reinvent solutions for common scenarios that come up, ranging from how to structure navigation, to how to refer to technical terms, to how to define anchors.

The documentation style guide should be just a set of guidelines. While we encourage each project to adopt it, it's up to that project to decide to do so. And a project is free to extend these guidelines with special cases or overrides. The main purpose to provide a common foundation from which we can all start.

[mojavelinux]

I want to start with a few general rules I've been following so far:

• Use ventilated prose (sentence per line arrangement)
• Use url- as a namespace for attributes that store a URL
• Prefer the shorthand syntax for defining an ID on a section or block
• Use title capitalization for the page title (i.e., doctitle)
• Use sentence capitalization for all section titles
• Use imperative language for page and section titles (e.g., Generate HTML)
• Don't use linked text in the navigation file (either let Antora use the page title or set the navtitle attribute to override it)
• ...

[mojavelinux]

From Sarah regarding the use of monospaced text for technical terms:

I try to always mark [a technical term] up as monospace when its the attribute, option, method, etc. when it's in regular text. My personal exceptions to this are when it's in a title (like a section title or listing title) or in linked text, because I think the double formatting, usually with a larger font and additional colors, makes it stand out too much and causes visual distraction. I find it visually distracting to add monospace formatting on top of bold, bigger font, blue underlined text, etc., and therefore don't use it in such circumstances

[ggrossetie]

As you know I'm experimenting with Vale and textlint. Could we agree on a list of terms? I'm asking because the textlint terminology rule comes with built-in terms but some may be debatable, for instance:

• “command line” -> “command-line”
• “file name” -> “filename”
• “ids” -> “IDs”
• “builtin” -> “built-in”
• “pre-release” -> “prerelease”
• “white space” -> “whitespace”
• “re-write” -> “rewrite”
• “regexps” -> “regular expressions”
• “sourcemap” -> “source map”
• “e-mail” -> “email”
• “html” -> “HTML”
• “an URL” -> “a URL”
• “https” -> “HTTPS”

[mojavelinux]

In addition to a style guide, I think this should also be a contributor guide for docs. The contributor section doesn't have to be long, but it should at least address how to submit a change. We're looking for something similar to https://docs.couchbase.com/home/contribute/