Wiki style guide - arxanas/git-branchless GitHub 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
• Grammatical voice
• Foreign language friendliness
• Tables of contents
• Headings
• Hyperlinks
• Code formatting

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.

• Good: "You can view the smartlog by running git sl."
• Good: "Use git sl to view the smartlog."
• Bad: "One can view the smartlog by running git sl."
• Bad: "The smartlog can be viewed by running git sl."
• Bad: "The user can view the smartlog by running git sl."

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

• Good: "Prefer the active voice where possible. Remember that you can address the reader directly."
• Bad: "The active voice should be preferred where possible. Remember that the reader can be addressed directly."

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

• Good: "To exit git undo, press control-C."
• Bad: "To get out of git undo, press control-C."
• Very bad: "Check out the documentation here."
  • "Check out" is a phrasal verb, and has an additional technical meaning in the context of Git.
• Good: "This is useful for interactive editing of the commit graph."
• Bad: "This is useful for hands-on editing of the commit graph."
  • The meaning of "hands-on" may not be immediately clear to the reader, even if they can guess what it means from context.

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: (timestamp removed) -->

<!--te-->

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

• Good: "Wiki style guide"
• Bad: "Wiki Style Guide"

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

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.

• Good: "This is a link to the Wiki style guide."
• Bad: "This is a link to the wiki style guide."

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

• Good: "See How do I use Git?."
• Bad: "See How do I use Git?"
• Bad: "See How do I use Git?"

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

• Good: "Use git sl to view the smartlog."
• Bad: "Use git sl to view the smartlog."

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