meta: update to metaguides

Author: Sam Kleinman

meta.organization.rst

@@ -20,7 +20,7 @@ Indexes and Experience
 ~~~~~~~~~~~~~~~~~~~~~~
 
 There are two "index files," for the documentation
-project. "``/contents.rst``" and "``/index.rst``". The "contents" file
+project. "``/contents.txt``" and "``/index.txt``". 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
@@ -48,11 +48,12 @@ 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.
+     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:
 
@@ -63,11 +64,12 @@ Current topical indexes include:
 - mongo
 - sharding
 - replication
+- faq
 
 Additional topical indexes are forthcoming.
 
-Top Level Folders
------------------
+The 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
@@ -85,6 +87,10 @@ explanations below:
   coverage in this context. Topics include: drivers, schema design,
   optimization, replication, and sharding.
 
+  - *applications/use-cases* - contains use cases that detail how
+    MongoDB can support various kinds uses and application designs,
+    including in depth instructions and examples.
+
 - *core* - contains overviews and introduction to the core features,
   functionality, and concepts of MongoDB. Topics include: replication,
   sharding, capped collections, journaling/durability, aggregation.
@@ -96,4 +102,7 @@ explanations below:
 
 - *tutorial* - contains operational guides and tutorials that lead
   users through common tasks (administrative and conceptual) with
-  MongoDB.
+  MongoDB. This includes programming patterns and operational guides.
+
+- *faq* - contains all the frequently asked questions related to
+  MongoDB, in a collection of topical files.

meta.practices.rst

@@ -21,6 +21,18 @@ 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.
 
+Standards and Practices
+-----------------------
+
+- All non-trivial at least two people should vet all non-trivial
+  changes to the documentation before publication. One of the
+  reviewers should have significant technical experience with the
+  material covered in the documentation.
+
+- All development and editorial work should transpire in topic
+  branches (or in "forks," on github,) that editors will merge into
+  the publication branches before publication.
+
 Collaboration
 -------------
 
@@ -53,34 +65,20 @@ running builds yourself.
 Publication
 -----------
 
-The makefile for this repository contains targets for the publication
-process. In order to maintain multiple versions of the documentation
-(to reflect different versions of the MongoDB server, for editing,
-review, etc.,) the makefile adds a couple of targets to the default
-Sphinx makefile. In the ``build-branch`` target, Sphinx builds the
-documentation into branch-specific folders. The ``deploy`` target
-moves these builds to into a local mirror (i.e. "``../public-docs``")
-of the documentation resource and calls a "``publish.sh``" script that
-handles the upload process itself.
-
-To publish the documentation, use the following procedure:
-
-1. Checkout the branch of the documentation that you want to publish,
-   make/apply all changes that you wish to publish.
-
-2. Build the following target. This operation builds all components of
-   the documentation required for publication . ::
-
-        make build-branch
-
-3. Build the following target. This procedure exports the build to the
-   "``../public-docs``" directory and runs the "``publish.sh``"
-   script. ::
+The makefile for this repository contains targets that automate the
+publication process. Use "``make html``" to publish a test build of
+the documentation in the "``build/``" directory of your
+repository. Use "``make publish``" to build the full contents of the
+manual from the current branch in the "``../public-docs/``" directory
+relative the docs repository.
 
-        make deploy
+Other targets include:
 
-The ``publish`` target (i.e. "``make publish``") combines
-``build-branch`` and ``deploy`` procedures. 
+- ``man`` - builds UNIX Manual pages for all Mongodb utilities.
+- ``push`` - builds and deploys the contents of the
+  "``../public-docs/``".
+- ``pdfs`` - builds a PDF version of the manual (requires LaTeX
+  dependencies.)
 
 Branches
 --------

meta.style-guide.rst

@@ -8,6 +8,10 @@ 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.
 
+Also consider the `Documentation Organization
+<meta.organization.rst>`_ (meta.organization.rst) document for more
+information regarding the MongoDB Manual organization.
+
 Document History
 ----------------
 
@@ -18,6 +22,9 @@ guidelines, conventions, and questions.
 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.
+
 Naming Conventions
 ------------------
 
@@ -132,13 +139,6 @@ General Formulations
 - Contractions are acceptable insofar as they are necessary to
   increase readability and flow. Avoid otherwise.
 
-- Shorter sentences are better than longer sentences. Use complex
-  formations (e.g. compound complex structures that require
-  semi-colons.) only as a last resort, if at all.
-
-- For longer lists and more complex lists, use bulleted items rather
-  than integrating them inline into a sentence.
-
 - Make lists grammatically correct.
 
   - Do not use a period after every item unless the list item
@@ -158,6 +158,37 @@ General Formulations
   ``mongod`` instance that cannot be accessed rather than the
   colloquialism "down."
 
+Structural Formulations
+~~~~~~~~~~~~~~~~~~~~~~~
+
+- There should be at least two headings at every nesting level. Within
+  an "h2" block, there should either be: no "h3" blocks, 2 "h3"
+  blocks, or more than 2 "h3" blocks.
+
+- Section headers should be 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 when possible.
+
+- Shorter sentences are better than longer sentences. Use complex
+  formations (e.g. compound complex structures that require
+  semi-colons.) only as a last resort, if at all.
+
+- In general, 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.
+
 ReStructured Text and Typesetting
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~