/
style-guide.txt
509 lines (382 loc) · 18 KB
/
style-guide.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
.. _documentation-style-guide:
=========================================
Style Guide and Documentation Conventions
=========================================
.. default-domain:: mongodb
This document provides an overview of the style for the MongoDB
documentation stored in this repository. The overarching goal of this
style guide is to provide an accessible base style to ensure that our
documentation is easy to read, simple to use, and straightforward to
maintain.
For information regarding the MongoDB Manual organization, see
:ref:`documentation-organization`.
Document History
----------------
**2011-09-27**: Document created with a (very) rough list of style
guidelines, conventions, and questions.
**2012-01-12**: Document revised based on slight shifts in practice,
and as part of an effort of making it easier for people outside of the
documentation team to contribute to documentation.
**2012-03-21**: Merged in content from the Jargon, and cleaned up
style in light of recent experiences.
**2012-08-10**: Addition to the "Referencing" section.
**2013-02-07**: Migrated this document to the manual. Added "map-reduce"
terminology convention. Other edits.
**2013-11-15**: Added new table of preferred terms.
**2016-01-05**: Standardizing on 'embedded document'
Naming Conventions
------------------
This section contains guidelines on naming files, sections, documents,
and other document elements.
- File naming convention:
- For Sphinx, all files should have a ``.txt`` extension.
- Separate words in file names with hyphens (i.e. ``-``.)
- For most documents, file names should have a terse one or two word
name that describes the material covered in the document. Allow
the path of the file within the document tree to add some of the
required context/categorization. For example it's acceptable to
have ``/core/sharding.rst`` and ``/administration/sharding.rst``.
- For tutorials, the full title of the document should be in the
file name. For example,
``/tutorial/replace-one-configuration-server-in-a-shard-cluster.rst``
- Phrase headlines and titles so users can determine what questions the
text will answer, and material that will be addressed, without needing
them to read the content. This shortens the amount of time that
people spend looking for answers, and improves search/scanning and
possibly "SEO."
- Prefer titles and headers in the form of "Using foo" over "How to Foo."
- When using target references (i.e. ``:ref:`` references in
documents), use names that include enough context to be intelligible
through all documentation. For example, use
"``replica-set-secondary-only-node``" as opposed to
"``secondary-only-node``". This makes the source more usable
and easier to maintain.
Style Guide
-----------
This includes the typesetting and English grammatical conventions
that all documents in the manual should use. The goal
here is to choose good standards, that are clear, and have a stylistic
minimalism that does not interfere with or distract from the
content. A uniform style will improve user experience and minimize
the effect of a multi-authored document.
Spelling
~~~~~~~~
Use American spelling.
Punctuation
~~~~~~~~~~~
- Use the Oxford comma.
Oxford commas are the commas in a list of things (e.g. "something,
something else, and another thing") before the conjunction
(e.g. "and" or "or.").
- Use a single space after terminal punctuation, such as periods.
- Place commas and periods inside quotation marks.
.. NOTE: The above bullet replaces the commented bullet below. American style
refers only to quote marks and not to parenthesis. I consulted several sites,
including this one: http://www.thepunctuationguide.com/british-versus-american-style.html
.. - Use "American style" punctuation when enclosing punctuation
(i.e. parentheses, quotes, and similar) interacts with terminal
punctuation (i.e. periods, commas, colons, and similar.) This rule
dictates that the terminal punctuation always goes *within* the
enclosing punctuation, even if the terminal punctuation affects the
sentence/clause outside of the quote or parenthetical.
.. This is counter to the "logical style" which is default in British
English, because its easier to be consistent and edit using this
rule, and because the style of the documents tends towards American
English.
.. NOTE This last paragraph in the bullet (below) uses an example we no longer do.
We no longer put parens around literals.
.. The one exception is if a literal string or inline code snippet is
enclosed in quotations or parenthesis, it may make sense to move a
period or comma further away from the literal string to avoid
copy-and-paste errors or other confusion. For example, in this case,
"``cfg.members[0].priorty = 1``." is worse than
"``cfg.members[0].priorty = 1``".
Headings
~~~~~~~~
Use title case for headings and document titles. Title case capitalizes the
first letter of the first, last, and all significant words.
Verbs
~~~~~
Verb tense and mood preferences, with examples:
- **Avoid** the first person. For example do not say, "We will begin
the backup process by locking the database," or "I begin the backup
process by locking my database instance."
- **Use** the second person. "If you need to back up your database,
start by locking the database first." In practice, however, it's
more concise to imply second person using the imperative, as in
"Before initiating a backup, lock the database."
- When indicated, use the imperative mood. For example: "Back up your
databases often" and "To prevent data loss, back up your databases."
- The future perfect is also useful in some cases. For example,
"Creating disk snapshots without locking the database will lead to
an invalid state."
- Avoid helper verbs, as possible, to increase clarity and
concision. For example, attempt to avoid "this does foo" and "this
will do foo" when possible. Use "does foo" over "will do foo" in
situations where "this foos" is unacceptable.
Referencing
~~~~~~~~~~~
- To refer to future or planned functionality in MongoDB or a driver,
*always* link to the Jira case. The Manual's ``conf.py`` provides
an ``:issue:`` role that links directly to a Jira case
(e.g. ``:issue:\`SERVER-9001\```).
- For non-object references (i.e. functions, operators, methods,
database commands, settings) always reference only the first
occurrence of the reference in a section. You should *always*
reference objects, except in section headings.
- Structure references with the *why* first; the link second.
For example, instead of this:
Use the :doc:`/tutorial/convert-replica-set-to-replicated-shard-cluster`
procedure if you have an existing replica set.
Type this:
To deploy a sharded cluster for an existing replica set, see
:doc:`/tutorial/convert-replica-set-to-replicated-shard-cluster`.
General Formulations
~~~~~~~~~~~~~~~~~~~~
- Contractions are acceptable insofar as they are necessary to
increase readability and flow. Avoid otherwise.
- Make lists grammatically correct.
- Do not use a period after every item unless the list item
completes the unfinished sentence before the list.
- Use appropriate commas and conjunctions in the list items.
- Typically begin a bulleted list with an introductory sentence or
clause, with a colon or comma.
- The following terms are one word:
- standalone
- workflow
- Use "unavailable," "offline," or "unreachable" to refer to a
``mongod`` instance that cannot be accessed. Do not use the
colloquialism "down."
- Always write out units (e.g. "megabytes") rather than using
abbreviations (e.g. "MB".)
Structural Formulations
~~~~~~~~~~~~~~~~~~~~~~~
- There should be at least two headings at every nesting level. Within
an "h2" block, there should be either: no "h3" blocks, 2 "h3"
blocks, or more than 2 "h3" blocks.
- Section headers are in title case (capitalize first, last, and
all important words) and should effectively describe the contents
of the section. In a single document you should strive to have
section titles that are not redundant and grammatically consistent
with each other.
- Use paragraphs and paragraph breaks to increase clarity and
flow. Avoid burying critical information in the middle of long
paragraphs. Err on the side of shorter paragraphs.
- Prefer shorter sentences to longer sentences. Use complex
formations only as a last resort, if at all (e.g. compound
complex structures that require semi-colons).
- Avoid paragraphs that consist of single sentences as
they often represent a sentence that has unintentionally become too
complex or incomplete. However, sometimes such paragraphs are useful
for emphasis, summary, or introductions.
As a corollary, most sections should have multiple paragraphs.
- For longer lists and more complex lists, use bulleted items rather
than integrating them inline into a sentence.
- Do not expect that the content of any example (inline or blocked)
will be self explanatory. Even when it feels redundant, make sure
that the function and use of every example is clearly described.
ReStructured Text and Typesetting
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- Place spaces between nested parentheticals and elements in
JavaScript examples. For example, prefer ``{ [ a, a, a ] }`` over
``{[a,a,a]}``.
- For underlines associated with headers in RST, use:
- ``=`` for heading level 1 or h1s. Use underlines and overlines for
document titles.
- ``-`` for heading level 2 or h2s.
- ``~`` for heading level 3 or h3s.
- ````` for heading level 4 or h4s.
- Use hyphens (``-``) to indicate items of an ordered list.
- Place footnotes and other references, if you use them, at the end of
a section rather than the end of a file.
Use the footnote format that includes automatic numbering and a
target name for ease of use. For instance a footnote tag may look
like: ``[#note]_`` with the corresponding directive holding the
body of the footnote that resembles the following: ``.. [#note]``.
Do **not** include ``.. code-block:: [language]`` in footnotes.
- As it makes sense, use the ``.. code-block:: [language]`` form to
insert literal blocks into the text. While the double colon,
``::``, is functional, the ``.. code-block:: [language]`` form makes the source easier to
read and understand.
- For all mentions of referenced types (i.e. commands, operators,
expressions, functions, statuses, etc.) use the reference types to
ensure uniform formatting and cross-referencing.
Paths and Hostnames
~~~~~~~~~~~~~~~~~~~
- Use angle brackets to denote areas that users should input the relevant
path, as in ``--dbpath <path>``.
- When including sample hostnames, use ``example.com``,
``example.net``, or ``example.org``, which are reserved for
documentation purposes. See `RFC2606
<http://tools.ietf.org/html/rfc2606>`_ and `RFC6761
<http://tools.ietf.org/html/rfc6761>`_ for more information.
Jargon and Common Terms
-----------------------
.. list-table::
:header-rows: 1
:widths: 10, 20, 10, 60
* - Preferred Term
- Concept
- Dispreferred Alternatives
- Notes
* - :term:`document`
- A single, top-level object/record in a MongoDB collection.
- record, object, row
- Prefer document over object because of concerns about
cross-driver language handling of objects. Reserve record for
"allocation" of storage. Avoid "row," as possible.
* - :term:`database`
- A group of collections. Refers to a group of data files. This
is the "logical" sense of the term "database."
-
- Avoid genericizing "database." Avoid using database to refer to
a server process or a data set. This applies both to the
datastoring contexts as well as other (related) operational
contexts (command context, authentication/authorization
context.)
* - instance
- A daemon process (e.g. :binary:`~bin.mongos` or :binary:`~bin.mongod`)
- process (acceptable sometimes), node (never acceptable), server.
- Avoid using instance, unless it modifies something
specifically. Having a descriptor for a process/instance makes
it possible to avoid needing to make mongod or mongos
plural. Server and node are both vague and contextually
difficult to disambiguate with regards to application servers
and underlying hardware.
* - :term:`field` name
- The identifier of a value in a document.
- key, column
- Avoid introducing unrelated terms for a single field. In the
documentation we've rarely had to discuss the identifier of a
field, so the extra word here isn't burdensome.
* - :term:`field`/value
- The name/value pair that describes a unit of data in MongoDB.
- key, slot, attribute
- Use to emphasize the difference between the name of a field and
its value For example, "_id" is the field and the default
value is an ObjectId.
* - value
- The data content of a field.
- data
-
* - MongoDB
- A group of processes or a deployment that implements the MongoDB
interface.
- mongo, mongodb, cluster
- Stylistic preference, mostly. In some cases it's useful to be
able to refer generically to instances (that may be either
:binary:`~bin.mongod` or :binary:`~bin.mongos`.)
* - embedded document
- An embedded or nested document within a document or an array.
- nested document
-
* - :term:`map-reduce`
- An operation performed by the mapReduce command.
- mapReduce, map reduce, map/reduce
- Avoid confusion with the command, shell helper, and driver
interfaces. Makes it possible to discuss the operation
generally.
* - cluster
- A sharded cluster.
- grid, shard cluster, set, deployment
- Cluster is a great word for a group of processes; however, it's
important to avoid letting the term become generic. Do not use
for any group of MongoDB processes or deployments.
* - sharded cluster
- A :term:`sharded cluster`.
- shard cluster, cluster, sharded system
-
* - :term:`replica set`
- A deployment of replicating :binary:`~bin.mongod` programs that
provide redundancy and automatic failover.
- set, replication deployment
-
* - deployment
- A group of MongoDB processes, or a standalone :binary:`~bin.mongod`
instance.
- cluster, system
- Typically in the form MongoDB deployment. Includes standalones,
replica sets and sharded clusters.
* - data set
- The collection of physical databases provided by a MongoDB
deployment.
- database, data
- Important to keep the distinction between the data provided by
a mongod or a sharded cluster as distinct from each "database"
(i.e. a logical database that refers to a group of collections
stored in a single series of data files.)
* - :term:`primary`
- The only member of a replica set that can accept writes.
- master
- Avoid "primary member" construction.
* - secondary
- Read-only members of a replica set that apply operations from
the primary's oplog.
- slave
- Accept "secondary member" as needed.
* - primary shard
- The shard in a cluster that's "primary" for a database.
- primary
- Avoid ambiguity with primary in the context of replica
sets.
* - range based sharding
- Refers to sharding based on regular shard keys where the range
is the value of the field(s) selected as the shard key.
-
-
* - hash based sharding
- Refers to sharding based on hashed shard keys where the range
is the hashed value of the field selected as the shard key.
-
- Even though hashed sharding is based on ranges of hashes, the
sequence of hashes aren't meaningful to users, and the
range-based aspect of hashed shard keys is an implementation
detail.
* - sharding
- Describes the practice of horizontal scaling or partitioning as
implemented in sharded clusters.
- partitioning, horizontal scaling
- Only use the terms "partitioning" and "horizontal scaling" to
describe what sharding does, and its operation. Don't refer to
sharding as "the partitioning system."
* - metadata
- data about data
- meta-data, meta data
-
Database Systems and Processes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- To indicate the entire database system, use "MongoDB," not mongo or
Mongo.
- To indicate the database process or a server instance, use ``mongod``
or ``mongos``. Refer to these as "processes" or "instances." Reserve
"database" for referring to a database structure, i.e., the structure
that holds collections and refers to a group of files on disk.
Distributed System Terms
~~~~~~~~~~~~~~~~~~~~~~~~
- Refer to partitioned systems as "sharded clusters." Do not use
shard clusters or sharded systems.
- Refer to configurations that run with replication as "replica sets" (or
"master/slave deployments") rather than "clusters" or other variants.
Data Structure Terms
~~~~~~~~~~~~~~~~~~~~
- "document" refers to "rows" or "records" in a MongoDB
database. Potential confusion with "JSON Documents."
Do not refer to documents as "objects," because drivers (and
MongoDB) do not preserve the order of fields when fetching data. If
the order of objects matter, use an array.
- "field" refers to a "key" or "identifier" of data within a MongoDB
document.
- "value" refers to the contents of a "field".
- "embedded document" describes a nested document.
Other Terms
~~~~~~~~~~~
- Use ``example.net`` (and ``.org`` or ``.com`` if needed) for all
examples and samples.
- Hyphenate "map-reduce" in order to avoid ambiguous reference to the
command name. Do not camel-case.
Notes on Specific Features
--------------------------
- Geo-Location
#. While MongoDB *is capable* of storing coordinates in
embedded documents, in practice, users should only store coordinates
in arrays. (See: `DOCS-41 <https://jira.mongodb.org/browse/DOCS-41>`_.)