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 MongoDB Manual Organization.
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.
This section contains guidelines on naming files, sections, documents and other document elements.
This includes the local typesetting, English, grammatical, conventions and preferences 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.
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.
Verb tense and mood preferences, with examples:
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 Convert a Replica Set to a Replicated Sharded Cluster procedure if you have an existing replica set.
To deploy a sharded cluster for an existing replica set, see Convert a Replica Set to a Replicated Sharded Cluster.
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.
For underlines associated with headers in RST, use:
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.
|Preferred Term||Concept||Dispreferred Alternatives||Notes|
|document||A single, top-level object/record in a MongoDB collection.||record, object, row||Prefer document over object because of concerns about cross-driver langauge handling of objects. Reserve record for “allocation” of storage. Avoid “row,” as possible.|
|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. mongos or 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.|
|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.|
|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 exdample, “_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 deployment that implement 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 mongod or mongos.)|
|sub-document||An embeded or nested document within a document or an array.||embeded document, nested document|
|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 sharded cluster.||shard cluster, cluster, sharded system|
|replica set||A deployment of replicating mongod programs that provide redundancy and automatic failover.||set, replication deployment|
|deployment||A group of MongoDB processes, or a standalone mongod instance.||cluster, system||Typically in the form MongoDB deployment. Includes standalones, replica sets and sharded clusters.|
|data set||The collection of phyisical 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.)|
|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 hases 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|
“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.