Skip to content

Commit 0a04af8

Browse files
committed
Add text guide
1 parent f88dab5 commit 0a04af8

File tree

1 file changed

+47
-0
lines changed

1 file changed

+47
-0
lines changed

docs/style-guides/text/README.md

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# Style Guide
2+
3+
> Style guide for writing text.
4+
5+
6+
* Filenames should be lowercase. Some top-level files and all `README.md` files are exceptions.
7+
8+
* Filenames should be snake_case.
9+
10+
* Use American English spelling; e.g., "Capitalize" vs. "Capitalise", "color" vs. "colour", etc.
11+
12+
* Insofar as is possible, spelling and grammar issues should be identified using tools, and, if not caught by a tool, should be identified by human reviewers.
13+
14+
* Use the [Oxford comma][oxford-comma] for clarity.
15+
16+
* Avoid using personal pronouns in reference documentation (e.g., "I", "you", "we").
17+
18+
* Personal pronouns are acceptable in more colloquial documentation, such as guides.
19+
20+
* Prefer using gender-neutral pronouns and mass nouns. For example,
21+
22+
- __OK__: "one", "they", "their", "them", "people", "developers"
23+
- __NOT OK__: "his", "him", "guys"
24+
25+
Exclusive use of female pronoun forms is permitted.
26+
27+
* Place end-of-sentence punctuation inside wrapping elements; e.g., periods should be placed inside parentheses and quotes, not after.
28+
29+
* Markdown documents must start with a level-one heading, such as in this document.
30+
31+
* Use definitions rather than in-lining; e.g., prefer `[link][]` over `[link](http://example.com)`.
32+
33+
* References to constructor functions should use PascalCase.
34+
35+
* References to constructor instances should use camelCase.
36+
37+
* References to functions and methods should use parentheses; e.g., `foo.factory()` versus `foo.factory`.
38+
39+
40+
41+
<section class="links">
42+
43+
[oxford-comma]: https://en.wikipedia.org/wiki/Serial_comma
44+
45+
</section>
46+
47+
<!-- /.links -->

0 commit comments

Comments
 (0)