Skip to content

Commit

Permalink
doc: add STYLE_GUIDE (moved from nodejs/docs)
Browse files Browse the repository at this point in the history
Also add a reference in CONTRIBUTING.md to it.

PR-URL: #11321
Reviewed-By: James M Snell <jasnell@gmail.com>
  • Loading branch information
gibfahn authored and MylesBorins committed Mar 9, 2017
1 parent bf4703d commit 41bf266
Show file tree
Hide file tree
Showing 2 changed files with 66 additions and 0 deletions.
3 changes: 3 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,9 @@ Create a branch and start hacking:
$ git checkout -b my-branch -t origin/master
```

Any text you write should follow the [Style Guide](doc/STYLE_GUIDE.md),
including comments and API documentation.

### Step 3: Commit

Make sure git knows your name and email address:
Expand Down
63 changes: 63 additions & 0 deletions doc/STYLE-GUIDE.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
# Style Guide

* Documents are written in markdown files.
* Those files should be written in **`lowercase-with-dashes.md`.**
* Underscores in filenames are allowed only when they are present in the
topic the document will describe (e.g., `child_process`.)
* Filenames should be **lowercase**.
* Some files, such as top-level markdown files, are exceptions.
* Older files may use the `.markdown` extension. These may be ported to `.md`
at will. **Prefer `.md` for all new documents.**
* Documents should be word-wrapped at 80 characters.
* The formatting described in `.editorconfig` is preferred.
* A [plugin][] is available for some editors to automatically apply these rules.
* Mechanical issues, like spelling and grammar, should be identified by tools,
insofar as is possible. If not caught by a tool, they should be pointed out by
human reviewers.
* American English spelling is preferred. "Capitalize" vs. "Capitalise",
"color" vs. "colour", etc.
* Though controversial, the [Oxford comma][] is preferred for clarity's sake.
* Generally avoid personal pronouns in reference documentation ("I", "you",
"we".)
* Pronouns are acceptable in more colloquial documentation, like guides.
* Use **gender-neutral pronouns** and **mass nouns**. Non-comprehensive
examples:
* **OK**: "they", "their", "them", "folks", "people", "developers", "cats"
* **NOT OK**: "his", "hers", "him", "her", "guys", "dudes".
* When combining wrapping elements (parentheses and quotes), terminal
punctuation should be placed:
* Inside the wrapping element if the wrapping element contains a complete
clause β€” a subject, verb, and an object.
* Outside of the wrapping element if the wrapping element contains only a
fragment of a clause.
* Place end-of-sentence punctuation inside wrapping elements β€” periods go
inside parentheses and quotes, not after.
* Documents must start with a level-one heading. An example document will be
linked here eventually.
* Prefer affixing links to inlining links β€” prefer `[a link][]` to
`[a link](http://example.com)`.
* When documenting APIs, note the version the API was introduced in at
the end of the section. If an API has been deprecated, also note the first
version that the API appeared deprecated in.
* When using dashes, use emdashes ("β€”", Ctrl+Alt+"-" on OSX) surrounded by
spaces, per the New York Times usage.
* Including assets:
* If you wish to add an illustration or full program, add it to the
appropriate sub-directory in the `assets/` dir.
* Link to it like so: `[Asset](/assets/{subdir}/{filename})` for file-based
assets, and `![Asset](/assets/{subdir}/{filename})` for image-based assets.
* For illustrations, prefer SVG to other assets. When SVG is not feasible,
please keep a close eye on the filesize of the asset you're introducing.
* For code blocks:
* Use language aware fences. ("```js")
* Code need not be complete β€” treat code blocks as an illustration or aid to
your point, not as complete running programs. If a complete running program
is necessary, include it as an asset in `assets/code-examples` and link to
it.
* When using underscores, asterisks and backticks please use proper escaping (**\\\_**, **\\\*** and **\\\`** instead of **\_**, **\*** and **\`**)
* References to constructor functions should use PascalCase
* References to constructor instances should be camelCased
* References to methods should be used with parenthesis: `socket.end()` instead of `socket.end`

[plugin]: http://editorconfig.org/#download
[Oxford comma]: https://en.wikipedia.org/wiki/Serial_comma

0 comments on commit 41bf266

Please sign in to comment.