Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Bash prompts and single-word heading capitalization #106

Merged
merged 4 commits into from
Apr 20, 2016
Merged

Bash prompts and single-word heading capitalization #106

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2349688
Added note about $ in bash examples
RichardLitt Feb 5, 2016
6ee3e3d
Standardized single word headings capitalization
RichardLitt Feb 5, 2016
0b13a92
Added man attribution to linux
RichardLitt Feb 22, 2016
9f7efd2
Added note about >
RichardLitt Apr 20, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions docs-styleguide.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ This is the documentation styleguide for our natural language descriptions used

* Use `backticks` for every code example inside of a normal description. In the CLI, where you cannot use backticks, use 'single quotes' for commands.
* Default settings should always be specified in a new sentence, not in parentheses, at the end. Default: like this.
* For command line arguments, do not include a `$` or `>` before commands in man pages. Instead, indent. A `$` or `>` may be included in READMEs; prefer `>` over `$`, as it is more universal.

### Acronyms

Expand All @@ -31,6 +32,13 @@ This is the documentation styleguide for our natural language descriptions used
* End phrases with a period. (Like that one).
* Capitalize the first letter of a phrase or sentence.

## Headings

* Single word headings in man pages should be capitalized. They should not be followed by a colon. Enumerated examples:
- `EXAMPLES`
- `NOTES`
- `WARNING`

## Ungendering

Avoid gendering in writing. Do not assume that the user/reader is of a certain gender.
Expand All @@ -54,3 +62,12 @@ Established canon, like Alice and Bob for cryptography, can still be used in the
#### Motivation

Avoiding gendering in community interaction has multiple benefits. Using a male or female pronoun alienates and unfairly prioritizes one gender in favor of another. For instance, saying "the user and his computer" may feel alienating to women, or vice versa. Luckily, in English, the pronoun 'their' can be used as both a singular and a plural form (cf. [Singular they](https://en.wikipedia.org/wiki/Singular_they)). Saying, "the user and their computer" is entirely acceptable and alleviates the issue.

## Changes

This is a living document and may be updated from time to time. Please refer to the git history for this document to view the changes.

## Credit and License
This styleguide is based on the [Linux man-pages manual](http://man7.org/linux/man-pages/man7/man-pages.7.html).

This document may be reused under a [Creative Commons Attribution-ShareAlike License](http://creativecommons.org/licenses/by-sa/4.0/).