meta: editing the style guide, and expanding the readme and a descrip…

…tion of the documentation process.

README.rst

@@ -14,12 +14,26 @@ command: ::
      make html
 
 Visit ``docs/mongodb/build/html/index.html`` to view the current state
-of the documentation.
+of the documentation. You may also wish to install `Pygments
+<http://pygments.org>`_ to provide syntax highlighting for code
+examples.
 
 To contribute to the documentation please fork this repository on
 github and issue a pull request. File issue reports or requests at the
-`Docs Jira Project <https://jira.mongodb.org/browse/DOCS>`_. Licensing
-information is forthcoming. If you have any questions, please contact
-`docs@10gen.com <mailto:docs@10gen.com>`_.
+`Documentation Jira Project <https://jira.mongodb.org/browse/DOCS>`_.
+See the following documents within this repository that provide a more
+thorough overview of the documentation style, process, and overall
+organization:
 
--- The 10gen Docs Team
+- `Style Guide <blob/master/meta.style-guide.rst>`_
+- `Jargon <blob/master/meta.jargon.rst>`_
+- `Documentation Practices <blob/master/meta.practices.rst>`_
+- `Documentation Organization <blob/master/meta.organization.rst>`_
+
+All documentation is available under the terms of a `Creative Commons
+License <http://creativecommons.org/licenses/by-nc-sa/3.0/>`_.
+
+If you have any questions, please contact `docs@10gen.com
+<mailto:docs@10gen.com>`_.
+
+-- The MongoDB/10gen Docs Team

meta.jargon.rst

@@ -1,5 +1,6 @@
-10gen Jargon Conventions
-========================
+========================================
+MongoDB Documentation Jargon Conventions
+========================================
 
 MongoDB
 -------
@@ -9,16 +10,43 @@ to the entire database system, including possibly ``mongod`` and
 ``mongos``.
 
 Refer to ``mongod`` or ``mongos`` to indicate the database process, or
-server instance itself.
+server instance itself. Use "database process," rather than "node,"
+"instance," or "host," to refer to the running database process.
 
 Data Structures
 ---------------
 
-*document* refers to "rows," or records in a MongoDB
+Use the following convention when referring to specific parts of
+MongoDB data:
+
+- *document* refers to "rows," or records in a MongoDB
  database. Potential confusion with "JSON Documents."
 
-*field* refers to a "key" or "identifier" of data within a MongoDB
+- *field* refers to a "key" or "identifier" of data within a MongoDB
  document.
 
-*value* refers to the contents of a *field*.
+- *value* refers to the contents of a *field*.
+
+Use "sub-document" as needed to describe nested documents.
+
+Other Terms
+-----------
+
+- Use "**shard cluster**," to refer to a collection of ``mongod``
+  instances that hold a sharded data set. Use the term "**replica
+  set**," to refer to a collection of ``mongod`` instances that
+  provide a replicated data set. Do not use the word "cluster" to
+  refer to a replication only deployment.
+
+- Use "``example.net``" (and ``.org`` or ``.com`` if needed) for all
+  examples and samples.
+
+The documentation project does not, as of early 2012, have a fixed set
+of nomenclature for describing interface elements, architectural
+components (daemons, databases, processes, drivers, hosts, mongos'
+etc.) Similarly, there is no standard nomenclature or examples for
+field names, values, variables, and other components of code examples.
 
+At some point in the near future creating a more standardized the
+nomenclature for examples of architectural elements and code
+components may be necessary.

meta.organization.rst

@@ -0,0 +1,99 @@
+==================================
+MongoDB Documentation Organization
+==================================
+
+This document provides an overview of the global organization of the
+documentation resource. Refer to the notes below if you are having
+trouble understanding the reasoning behind a file's current location,
+or if you want to add new documentation but aren't sure how to
+integrate it into the existing resource.
+
+Don't hesitate to open a ticket in the `Documentation Jira Project
+<https://jira.mongodb.org/browse/DOCS>`_ or be in contact with someone
+on the `documentation team <mailto:docs@10gen.com>`_ if you have any
+questions.
+
+Global Organization
+-------------------
+
+Indexes and Experience
+~~~~~~~~~~~~~~~~~~~~~~
+
+There are two "index files," for the documentation
+project. "``/contents.rst``" and "``/index.rst``". The "contents" file
+provides an index and top level tree of all documentation in the
+resource and Sphinx uses this organization to power the "Next" and
+"Previous" page functionality and all overarching outlines of the
+resource. The "index" file is not included in the "contents" file (and
+thus builds will produce a warning here) and is the page that users
+will land on first when visiting the resource.
+
+Having separate "contents" and "index" files provides a bit more
+flexibility with the organization of the resource while also making it
+possible to customize the primary user experience.
+
+Additionally, in the top level of the "``source/``" directory, there
+are a number of "topical" index or outline files. These (like the
+"index" and "contents" files) use the "``.. toctree::``" directive to
+provide organization within the documentation. The topical indexes
+combine to create the index in the contents file.
+
+Topical Indexes and Meta Organization
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Because the documentation on any given subject exists in a number of
+different locations across the resource the "topical" indexes provide
+the real structure and organization to the resource. This organization
+makes it possible to provide great flexibility while still maintaining
+a reasonable organization of files and URLs for the
+documentation. Consider the following example:
+
+Given that topic such as "replication," has material regarding the
+administration of replica sets, as well as reference material, an
+overview of the functionality, and operational tutorials, it makes
+more sense to include a few locations for documents, and use the meta
+documents to provide the topic-level organization.
+
+Current topical indexes include:
+
+- getting-started
+- administration
+- applications
+- reference
+- mongo
+- sharding
+- replication
+
+Additional topical indexes are forthcoming.
+
+Top Level Folders
+-----------------
+
+The documentation has a number of top-level folders, that hold all of
+the content of the resource. Consider the following list and
+explanations below:
+
+- *administration* - contains all of the operational and architectural
+  information that systems and database administrators need to know in
+  order to run MongoDB. Topics include: monitoring, replica sets, shard
+  clusters, deployment architectures, and configuration.
+
+- *applications* - contains information about application development
+  and use. While most documentation regarding application development
+  is within the purview of the driver documentation, there are some
+  larger topics regarding the use of these features that deserve some
+  coverage in this context. Topics include: drivers, schema design,
+  optimization, replication, and sharding.
+
+- *core* - contains overviews and introduction to the core features,
+  functionality, and concepts of MongoDB. Topics include: replication,
+  sharding, capped collections, journaling/durability, aggregation.
+
+- *reference* - contains references and indexes of shell functions,
+  database commands, status outputs, as well as manual pages for all
+  of the programs come with MongoDB (e.g. ``mongostat`` and
+  ``mongodump``.)
+
+- *tutorial* - contains operational guides and tutorials that lead
+  users through common tasks (administrative and conceptual) with
+  MongoDB.

meta.practices.rst

@@ -0,0 +1,50 @@
+=============================================
+MongoDB Documentation Practices and Processes
+=============================================
+
+This document provides an overview of the practices and processes that
+the documentation uses and hopes to use to maintain the
+documentation. This is a work in progress.
+
+Commits
+-------
+
+When possible, relevant, include a Jira case identifier in a commit
+message. Reference documentation cases when relevant, but feel free to
+reference other cases from <http://jira.mongodb.org/>.
+
+Err on the side of creating a larger number of discrete commits rather
+than bundling large set of changes into one commit.
+
+For the sake of consistency, avoid committing trailing whitespace in
+the source file. Additionally, the existing files are "hard wrapped"
+to 70 characters per-line, which you can adhere to if it is easy for
+you.
+
+Collaboration
+-------------
+
+To propose a change to the documentation, either:
+
+- Open a ticket in the `documentation project
+  <https://jira.mongodb.org/browse/DOCS>`_ proposing the change and
+  someone on the documentation team will make the change and be in
+  contact with you so that you can review our change.
+
+- Using github, fork the repository, commit your changes to this
+  repository and issue a pull request, and someone on the
+  documentation team will review and incorporate your change into the
+  documentation.
+
+Builds
+------
+
+Running the build of the documentation can be quite illuminating, as
+the build process can catch various kinds of errors in the format and
+syntax of the documentation. Also from a review perspective it's
+useful to see the documentation presented in another format. Besides
+Sphinx, Pygments, and Python-Docutils, the documentation repository
+contains all requirements for building the documentation resource.
+
+Talk to someone on the documentation team if you are having problems
+running builds yourself.