github.com/Hnampk/fabric@v2.1.1+incompatible/docs/source/style_guide.md

github.com/Hnampk/fabric@v2.1.1+incompatible/docs/source/style_guide.md (about)

1 # Documentation style guide for contributors
2
3 *Audience: documentation writers and editors*
4
5 While this style guide will also refer to best practices using ReStructured Text (also known as RST), in general we advise writing documentation in Markdown, as it's a more universally accepted documentation standard. Both formats are usable, however, and if you decide to write a topic in RST (or are editing an RST topic), be sure to refer to this style guide.
6
7 **When in doubt, use the docs themselves for guidance on how to format things.**
8
9 * [For RST formatting](http://hyperledger-fabric.readthedocs.io/en/release-1.4/channel_update_tutorial.html).
10
11 * [For Markdown formatting](http://hyperledger-fabric.readthedocs.io/en/release-1.4/peers/peers.html).
12
13 If you just want to look at how things are formatted, you can navigate to the Fabric repo to look at the raw file by clicking on `Edit on Github` link in the upper right hand corner of the page. Then click the `Raw` tab. This will show you the formatting of the doc. **Do not attempt to edit the file on Github.** If you want to make a change, clone the repo and follow the instructions in [Contributing](contributing.html) for creating pull requests.
14
15 **Line lengths.**
16
17 If you look at the raw versions of the documentation, you will see that many topics conform to a line length of roughly 70 characters. This restriction is no longer necessary, so you are free to make lines as long as you want.
18
19 **Tutorials should have a list of steps at the top.**
20
21 A list of steps (with links to the corresponding sections) at the beginning of a tutorial helps users find particular steps they're interested in. For an example, check out [Use private data in Fabric](../private-data/private-data.html).
22
23 **"Fabric", "Hyperledger Fabric" or "HLF"?**
24
25 The first usage should be “Hyperledger Fabric” and afterwards only “Fabric”. Don't use "HLF" or "Hyperledger" by itself.
26
27 **Chaincode vs. Chaincodes?**
28
29 One chaincode is a “chaincode”. If you’re talking about several chaincodes, use "chaincodes".
30
31 **When to bold?**
32
33 Not too often. The best use of them is either as a summary or as a way of drawing attention to concepts you want to talk about. “A blockchain network contains a ledger, at least one chaincode, and peers”, especially if you’re going to be talking about those things in that paragraph. Avoid using them simply to emphasize a single word, as in something like "Blockchain networks **must** use propery security protocols".
34
35 **When to surround something in back tics `nnn`?**
36
37 This is useful to draw attention to words that either don’t make sense in plain English or when referencing parts of the code (especially if you’ve put code snippets in your doc). So for example, when talking about the fabric-samples directory, surround `fabric-samples` with back tics. Same with a code function like `hf.Revoker`. It might also make sense to put back tics around words that do make sense in plain English that are part of the code if you're referencing them in a code context. For example, when referencing an `attribute` as part of an Access Control List.
38
39 **Is it ever appropriate to use a dash?**
40
41 Dashes can be incredibly useful but they're not necessarily as technically appropriate as using separate declarative sentences. Let's consider this example sentence:
42
43 ```
44 This leaves us with a trimmed down JSON object --- config.json, located in the fabric-samples folder inside first-network --- which will serve as the baseline for our config update.
45 ```
46
47 There are a number of ways to present this same information, but in this case the dashes break up the information while keeping it as part of the same thought. If you use a dash, make sure to use the "em" dash, which is three times longer than a hyphen. These dashes should have a space before and after them.
48
49 **When to use hyphens?**
50
51 Hyphens are mostly commonly used as part of a “compound adjective”. For example, "jet-powered car". Note that the compound adjective must immediately precede the noun being modified. In other words, "jet powered" does not by itself need a hyphen. When in doubt, use Google, as compound adjectives are tricky and are a popular discussion on grammar discussion boards.
52
53 **How many spaces after a period?**
54
55 One.
56
57 **How should numbers be rendered?**
58
59 Number zero through nine are spelled out. One, two, three, four, etc. Numbers after 10 are rendered as numbers.
60
61 Exceptions to this would be usages from code. In that case, use whatever’s in the code. And also examples like Org1. Don’t write it as OrgOne.
62
63 **Try to avoid using the same words too often.**
64
65 If you can avoid using a word twice in one sentence, please do so. Not using it more than twice in a single paragraph is better. Of course sometimes it might not be possible to avoid this –-- a doc about stateDB is likely to be replete with uses of the word “database” or “ledger”. But excessive usage of any particular word has a tendency to have a numbing effect on the reader.
66
67 **How should files be named?**
68
69 For example, `identity_use_case_tutorial.md`. While not all files use this standard, new files should adhere to it.
70
71 **Capitalization rules for doc titles.**
72
73 The standard rules for capitalization in sentences should be followed. In other words, unless a word is the first word in the title or a proper noun, do not capitalize its first letter. For example, "Understanding Identities in Fabric" should be "Understanding identities in Fabric". While not every doc follows this standard yet, it is the standard we're moving to and should be followed for new topics.
74
75 Headings inside of topics should follow the same standard.
76
77 **Use the Oxford comma?**
78
79 Yes, it’s better.
80
81 For example: “I’d like to thank my parents, Ayn Rand and God”. Compared to: “I’d like to thank my parents, Ayn Rand, and God.”
82
83 **JSON vs .json?**
84
85 Use “JSON”. The same applies for any file format (for example, YAML).
86
87 **Referring to the reader.**
88
89 It’s perfectly fine to use the word “you” or “we”.
90
91 **Ampersands (&).**
92
93 Not a substitute for the word “and”. Avoid them unless you have a reason to use it (such as in a code snippet that includes it).
94
95 **Acronyms.**
96
97 The first usage of an acronym should be spelled out, unless it’s an acronym that’s in such wide usage this is unneeded. For example, “Software Development Kit (SDK)” on first usage. Then use “SDK” afterward.
98
99 **Captions.**
100
101 These should be in italics, and it’s the only real valid use for italics in our docs.
102
103 **Commands.**
104
105 In general, put each command in its own snippet. It reads better, especially when commands are long. An exception to this rule is when suggesting the export of a number of environment variables.
106
107 **Code snippets.**
108
109 In Markdown, if you want to post sample code, use three back tics to set off the snippet. For example:
110
111 ```
112 Code goes here.
113
114 Even more code goes here.
115
116 And still more.
117 ```
118
119 In RST, you will need to set off the code snippet using formatting similar to this:
120
121 ```
122 .. code:: bash
123
124 Code goes here.
125 ```
126
127 You can substitute `bash` for a language like Java or Go, where appropriate.
128
129 **Enumerated lists in markdown.**
130
131 Note that in Markdown, enumerated lists will not work if you separate the numbers with a space. Markdown sees this as the start of a new list, not a continuation of the old one (every number will be `1.`). If you need an enumerated list, you will have to use RST. Bulleted lists are a good substitute in Markdown, and are the recommended alternative.
132
133 **Linking.**
134
135 When linking to another doc, use relative links, not direct links. When naming a link, do not just call it "link". Use a more creative and descriptive name. For accessibility reasons, the link name should also make it clear that it is a link. For example, check out [this link to Google](www.google.com).
136
137 **curl vs cURL.**
138
139 The tool is called “cURL”. The commands themselves are “curl” commands.
140
141 **Fabric CA.**
142
143 Do not call it "fabric-CA", "fabricCA", or FabricCA. It is the Fabric CA.
144
145 **Raft and RAFT.**
146
147 "Raft" is not an acronym. Do not call it a "RAFT ordering service".
148
149 **All docs have to end with a license statement.**
150
151 In RST, it’s this:
152
153 ```
154 .. Licensed under Creative Commons Attribution 4.0 International License
155 https://creativecommons.org/licenses/by/4.0/
156 ```
157
158 In markdown:
159
160 ```
161 
163 ```
164
165 **How many spaces for indentation?**
166
167 Depends on the use case, I suppose. Frequently it’s necessary, especially in RST, to indent two spaces, especially in a code block. In a NOTE box in RST, you have to indent to the space after the colon after note, like this:
168
169 ```
170 .. note:: Some words and stuff etc etc etc (line continues until the 70 character limit line)
171 the line directly below has to start at the same space as the one above.
172 ```
173
174 **When to use which type of heading.**
175
176 Check out [this topic on headings](http://blender-manual-i18n.readthedocs.io/ja/latest/about/markup_style_guide.html?highlight=tooltip#headings).
177
178 In RST, use this:
179
180 ```
181 Chapter 1 Title
182 ===============
183
184 Section 1.1 Title
185 -----------------
186
187 Subsection 1.1.1 Title
188 ~~~~~~~~~~~~~~~~~~~~~~
189
190 Section 1.2 Title
191 -----------------
192 ```
193
194 Note that the length of what’s under the title has to be the same as the length of the title itself. This isn’t a problem in Atom, which gives each character the same width by default (this is called “monospacing”, if you’re ever on Jeopardy! and need that information.
195
196 In markdown, it’s somewhat simpler. You go:
197
198 ```
199 # The Name of the Doc (this will get pulled for the TOC).
200
201 ## First subsection
202
203 ## Second subsection
204 ```
205
206 Both file formats don't like when these things are done out of order. For example, you might want a `####` to be the first thing after your `#` Title. Markdown won’t allow it. Similarly, RST will default to whatever order you give to the title formats (as they appear in the first sections of your doc).
207
208