DOCS-1572: updating the style guide

Author: Sam Kleinman

source/meta/style-guide.txt

@@ -31,6 +31,8 @@ style in light of recent experiences.
 **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.
+
 Naming Conventions
 ------------------
 
@@ -275,6 +277,160 @@ ReStructured Text and Typesetting
 Jargon and Common Terms
 -----------------------
 
+.. list-table:: 
+   :header-rows: 1
+   :widths: 15, 15, 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 langauge 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. :program:`mongos` or :program:`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`/\ :term:`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
+       :program:`mongod` or :program:`mongos`.)
+
+   * - sub-document
+     - An embeded or nested document within a document or an array.
+     - embeded document, 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 :program:`mongod` programs that
+       provide redundancy and automatic failover. 
+     - set, replication deployment
+     - 
+
+   * - deployment
+     - A group of MongoDB processes, or a standalone :program:`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.) 
+
+   * - :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 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
+     - 
+
 Database Systems and Processes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~