Wiki style guide - arxanas/git-branchless Wiki

Good documentation is a first-class goal for git-branchless! Be sure to adhere to the style guide when making changes to Wiki content.

Grammatical person

Prefer the second-person singular to address the reader. The objective of the Wiki is to work with the reader and guide them into a useful workflow. It's not a technical reference.

Grammatical voice

Prefer the active voice where possible. Remember that you can address the reader directly using the second person.

Foreign language friendliness

Some readers are not expert English speakers. Avoid using phrasal verbs and idiomatic terminology, as they may be difficult to understand at first.

Tables of contents

For articles with headings, insert the HTML comment ts followed by te to insert a table of contents. It will be automatically rendered and kept in sync by Github Actions, and look like this:

<!--ts-->
   * [Grammatical person](#grammatical-person)
   * [Grammatical voice](#grammatical-voice)
   * [Foreign language friendliness](#foreign-language-friendliness)
   * [Tables of contents](#tables-of-contents)
   * [Headings](#headings)
   * [Hyperlinks](#hyperlinks)
   * [Code formatting](#code-formatting)

<!-- Added by: runner, at: Fri Jan 14 18:48:03 UTC 2022 -->

<!--te-->

Headings

For article or page titles and headings, use "sentence-case". Capitalize the first word of the title, and leave the rest unchanged.

Use <h2>-level headings as the top-level heading.

Hyperlinks

Link to other content liberally, especially other articles in the Wiki. It's likely that the reader did not read the Wiki from front to back, so they may be missing useful context, or may benefit from being made aware of the existence of other content.

For links to articles, render the title exactly as it appears in the article, including the use of sentence-case.

This includes links to external resources, such as Stack Overflow. If the link title has punctuation at the end, it should be preserved.

Code formatting

For commands which can be run, use inline code formatting. This includes the name of the project, git-branchless, since it's a command.

Exception: the title of a Wiki page is used to form its URL. Don't include inline code formatting in a page title, since it will cause the URL to become unwieldy.

For shell snippets, use code block formatting. Include an empty line between commands. Use $ to indicate the prompt character.

Good:

$ echo Hello
Hello

$ echo World
World

Bad:

$ echo Hello
Hello
$ echo World
World