MongoDB Documentation Style and Conventions

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.”).

• Do not add two spaces after terminal punctuation, such as periods.

• Place commas and periods inside quotation marks.

• 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 inititating a back up, lock the database.”
• When indicated, use the imperative mood. For example: “Backup 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 inconsistent 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 转换一个副本设置为复制的片式集群 procedure if you have an existing replica set.

  Type this:

  To deploy a sharded cluster for an existing replica set, see 转换一个副本设置为复制的片式集群.

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.

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”.

• “sub-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.