From 23496884da997e74d3e0f01dd72daef92e732f0b Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Fri, 5 Feb 2016 10:36:16 -0500 Subject: [PATCH 1/4] Added note about $ in bash examples --- docs-styleguide.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs-styleguide.md b/docs-styleguide.md index 76457f2c..67d81e24 100644 --- a/docs-styleguide.md +++ b/docs-styleguide.md @@ -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 bash arguments, do not include a `$` before commands in man pages. A `$` may be included in READMEs. ### Acronyms From 6ee3e3d89073f26ea9d2f6b4738c1172f6a13b85 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Fri, 5 Feb 2016 10:36:26 -0500 Subject: [PATCH 2/4] Standardized single word headings capitalization --- docs-styleguide.md | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/docs-styleguide.md b/docs-styleguide.md index 67d81e24..5cc0bac5 100644 --- a/docs-styleguide.md +++ b/docs-styleguide.md @@ -15,7 +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 bash arguments, do not include a `$` before commands in man pages. A `$` may be included in READMEs. +* For command line arguments, do not include a `$` before commands in man pages. A `$` may be included in READMEs. ### Acronyms @@ -32,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. From 0b13a92b6b7e000bf77759d7fda7a59fa9445921 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Mon, 22 Feb 2016 11:45:35 -0500 Subject: [PATCH 3/4] Added man attribution to linux --- docs-styleguide.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs-styleguide.md b/docs-styleguide.md index 5cc0bac5..e2e5685b 100644 --- a/docs-styleguide.md +++ b/docs-styleguide.md @@ -62,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/). From 9f7efd2108ff098ea735686a51c2a90e2fe452c5 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Wed, 20 Apr 2016 15:54:11 -0400 Subject: [PATCH 4/4] Added note about > --- docs-styleguide.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs-styleguide.md b/docs-styleguide.md index e2e5685b..850b0988 100644 --- a/docs-styleguide.md +++ b/docs-styleguide.md @@ -15,7 +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 `$` before commands in man pages. A `$` may be included in READMEs. +* 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