diff --git a/source/about.txt b/source/about.txt index 946e4398f82..00a67632593 100644 --- a/source/about.txt +++ b/source/about.txt @@ -4,40 +4,17 @@ About MongoDB Documentation .. default-domain:: mongodb -.. _meta-about-mongodb: +`The MongoDB Manual `_ contains +comprehensive documentation on the MongoDB :term:`document`-oriented +database management system. This page describes the manual's licensing, +editions, and versions, and describes how to make a change request and +how to contribute to the manual. -About MongoDB -------------- +For more information on MongoDB, see `MongoDB: A Document Oriented Database `_. +To download MongoDB, see the `downloads page `_. -MongoDB is a :term:`document`-oriented database management system -designed for performance, horizontal scalability, high -availability, and advanced queryability. See the following :wiki:`wiki -pages <>` for more information about MongoDB: - -- :wiki:`Introduction` -- :wiki:`Philosophy` -- :wiki:`About` - -If you want to download MongoDB, see the `downloads page -`_. - -If you'd like to learn how to use MongoDB with your programming -language of choice, see the introduction to the :doc:`drivers -`. - -.. _meta-about-documentation-project: - -About the Documentation Project -------------------------------- - -This Manual -~~~~~~~~~~~ - -The MongoDB documentation project provides a complete manual for the -MongoDB database. - -Licensing -`````````` +License +------- This manual is licensed under a Creative Commons "`Attribution-NonCommercial-ShareAlike 3.0 Unported @@ -47,11 +24,10 @@ This manual is licensed under a Creative Commons The MongoDB Manual is copyright |copy| 2011-|year| 10gen, Inc. Editions -```````` +-------- -In addition to the site, you can -also access this content in the following editions provided for your -convenience: +In addition to the `MongoDB Manual `_, you can +also access this content in the following editions: - :hardlink:`ePub Format ` @@ -59,7 +35,7 @@ convenience: - :hardlink:`PDF Format ` -PDF files that provide access to subsets of the MongoDB Manual: +You also can access PDF files that contain subsets of the MongoDB Manual: - :hardlink:`MongoDB Reference Manual ` @@ -81,7 +57,7 @@ manuals are available for offline use: :issue:`DOCS Jira project`. Version and Revisions -````````````````````` +--------------------- This version of the manual reflects version |version| of MongoDB. @@ -99,10 +75,16 @@ current manual in the :hardlink:`release.txt` file. The most up-to-date, current, and stable version of the manual is always available at "http://docs.mongodb.org/manual/." +Report an Issue or Make a Change Request +---------------------------------------- + +To report an issue with this manual or to make a change request, file a ticket at the +`MongoDB DOCS Project on Jira `_. + .. _meta-contributing: -Contributing to the Documentation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Contribute to the Documentation +------------------------------- .. this toctree should be moved to a not-yet-extant "translation" section of this page. @@ -112,27 +94,30 @@ Contributing to the Documentation /meta/translation -The entire source of the documentation is available in the `docs -repository `_ along with all of the -other `MongoDB project repositories on GitHub `_. -You can clone the repository by issuing the following command at your -system shell: +The entire documentation source for this manual is available in the +`mongodb/docs repository `_, which is one of the +`MongoDB project repositories on GitHub `_. + +To contribute to the documentation, you can open a `GitHub account `_, +fork the `mongodb/docs repository `_, make a +change, and issue a pull request. -.. code-block:: sh +In order for the documentation team to accept your change, you must +complete the `MongoDB/10gen Contributor Agreement `_. - git clone git://github.com/mongodb/docs.git +.. regarding this, below. Isn't it the case that forking to their origin is the way + users can contribute to github.com/mongodb/docs. Simply cloning + to their local workstation gives no access to issue pull requests: -If you have a GitHub account and want to fork this repository, you may -issue pull requests, and someone on the documentation team will merge -in your contributions promptly. In order to accept your changes to the -Manual, you have to complete the `MongoDB/10gen Contributor Agreement -`_. +.. You can clone the repository by issuing the following command at your + system shell: -This project tracks issues at MongoDB's :issue:`DOCS` project. -If you see a problem with the documentation, please report it there. +.. .. code-block:: sh -Writing Documentation -~~~~~~~~~~~~~~~~~~~~~ +.. git clone git://github.com/mongodb/docs.git + +About the Documentation Process +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The MongoDB Manual uses `Sphinx `_, a sophisticated documentation engine built upon `Python Docutils @@ -141,9 +126,17 @@ sophisticated documentation engine built upon `Python Docutils necessary Sphinx extensions and build tools, are available in the same repository as the documentation. -You can view the documentation style guide and the build instructions -in reStructured Text files in the top-level of the `documentation -repository `_. If you have any -questions, please feel free to open a :issue:`Jira Case `. +For more information on the MongoDB documentation process, see: + +.. toctree:: + :maxdepth: 1 + + meta/style-guide + meta/practices + meta/organization + meta/build + +If you have any questions, please feel free to open a :issue:`Jira Case +`. .. include:: /includes/hash.rst diff --git a/meta.build.rst b/source/meta/build.txt similarity index 66% rename from meta.build.rst rename to source/meta/build.txt index 5aff00ab142..b4f0c3dbb6c 100644 --- a/meta.build.rst +++ b/source/meta/build.txt @@ -1,6 +1,6 @@ -================================================ -Building and Deploying the MongoDB Documentation -================================================ +========================================== +Build and Deploy the MongoDB Documentation +========================================== This document contains more direct instructions for building the MongoDB documentation. @@ -26,9 +26,11 @@ For full publication builds: Building the Documentation -------------------------- -Clone the repository: :: +Clone the repository: - git clone git://github.com/mongodb/docs.git +.. code-block:: sh + + git clone git://github.com/mongodb/docs.git To build the full publication version of the manual, you will need to have a function LaTeX tool chain; however, for routine day-to-day @@ -39,17 +41,23 @@ For Routine Builds ~~~~~~~~~~~~~~~~~~ Begin by installing dependencies. On Arch Linux, use the following -command to install the full dependencies: :: +command to install the full dependencies: + +.. code-block:: sh + + pacman -S python2-sphinx python2-pygments python2-yaml + +On Debian/Ubuntu systems issue the following command: - pacman -S python2-sphinx python2-pygments python2-yaml +.. code-block:: sh -On Debian/Ubuntu systems issue the following command: :: + apt-get install python-sphinx python-yaml python-argparse - apt-get install python-sphinx python-yaml python-argparse +To build the documentation issue the following command: -To build the documentation issue the following command: :: +.. code-block:: javascript - make html + make html You can find the build output in ``build//html``, where ```` is the name of your current branch. @@ -58,13 +66,17 @@ For Publication Builds ~~~~~~~~~~~~~~~~~~~~~~ Begin by installing additional dependencies. On Arch Linux, use the -following command to install the full dependencies: :: +following command to install the full dependencies: - pacman -S texlive-bin texlive-core texlive-latexextra python2-sphinx python2-pygments python2-yaml +.. code-block:: sh -On Debian/Ubuntu systems use the following command: :: + pacman -S texlive-bin texlive-core texlive-latexextra python2-sphinx python2-pygments python2-yaml - apt-get install python-yaml python-argparse python-sphinx texlive-latex-recommended texlive-latex-recommended +On Debian/Ubuntu systems use the following command: + +.. code-block:: sh + + apt-get install python-yaml python-argparse python-sphinx texlive-latex-recommended texlive-latex-recommended **Note:** *The Debian/Ubuntu dependencies, have not been thoroughly tested. If you find an additional dependency, please submit a pull @@ -73,17 +85,21 @@ request to modify this document.* On OS X: #. You may need to use ``easy_install`` to install ``pip`` using the - following command if you have not already done so: :: + following command if you have not already done so: - easy_install pip + .. code-block:: sh + + easy_install pip Alternately, you may be able to replace ``pip`` with ``easy_install`` in the next step. #. Install Sphinx, Docutils, and their dependencies with ``pip`` using - the following command: :: + the following command: + + .. code-block:: sh - pip install Sphinx Jinja2 Pygments docutils PyYAML + pip install Sphinx Jinja2 Pygments docutils PyYAML ``Jinja2``, ``Pygments``, and ``docutils`` are all dependencies of ``Sphinx``. @@ -103,17 +119,21 @@ or you have a dependency list for Fedora, CentOS, Red Hat, or other related distributions, please submit a pull request to add this information to this document.* -To build a test version of the Manual, issue the following command: :: +To build a test version of the Manual, issue the following command: - make publish +.. code-block:: javascript + + make publish This places a complete version of the manual in "``../public-docs/``" named for the current branch (as of *2012-03-19*, typically master.) -To publish a new build of the manual, issue the following command: :: +To publish a new build of the manual, issue the following command: + +.. code-block:: javascript - make push + make push **Warning:** *This target depends on* ``publish``, *and simply uses* ``rsync`` *to move the content of the* "``../public-docs/``" *to the web @@ -161,15 +181,18 @@ file is well formed.*) #. A ``layout`` document that describes the structure the final presentation of the table. Contains two field, a ``header`` that holds a list of field references, and a ``rows`` field that holds a - list of lists of field references, for example:: + list of lists of field references, for example: + + .. code-block:: none + - section: layout - header: [ meta.header1, meta.header2 ] - rows: - - 1: [ content.sql1, content.mongo1 ] - - 2: [ content.sql2, content.mongo2 ] - - 3: [ content.sql3, content.mongo3 ] - - 4: [ content.sql4, content.mongo4 ] + section: layout + header: [ meta.header1, meta.header2 ] + rows: + - 1: [ content.sql1, content.mongo1 ] + - 2: [ content.sql2, content.mongo2 ] + - 3: [ content.sql3, content.mongo3 ] + - 4: [ content.sql4, content.mongo4 ] #. A ``meta`` document that holds row, column or other minor descriptions, referenced in the layout section. @@ -195,9 +218,11 @@ dependency of the Sphinx build process. [#table-deps-exception]_ - include the generated ``.rst`` file in your Sphinx document. (Optional.) - in the ``tables`` variable in the ``bin/builder_data.py`` file, add - a tuple to the list in the following form: :: + a tuple to the list in the following form: - ('$(rst-include)/table-sql-to-agg-terms', 'agg'), + .. code-block:: sh + + ('$(rst-include)/table-sql-to-agg-terms', 'agg'), The first element is the path of the table file, without the extension. This value becomes the target in a makefile, so you can @@ -225,13 +250,15 @@ Python scripts. This architecture reduces redundancy while increasing clarity and consistency. These makefiles enter the build process by way of include statements -and a pattern rule in the top level makefile, as follows: :: +and a pattern rule in the top level makefile, as follows: + +.. code-block:: phython - -include $(output)/makefile.tables - -include $(output)/makefile.sphinx + -include $(output)/makefile.tables + -include $(output)/makefile.sphinx - $(output)/makefile.%:bin/makefile-builder/%.py bin/makefile_builder.py bin/builder_data.py - @$(PYTHONBIN) bin/makefile-builder/$(subst .,,$(suffix $@)).py $@ + $(output)/makefile.%:bin/makefile-builder/%.py bin/makefile_builder.py bin/builder_data.py + @$(PYTHONBIN) bin/makefile-builder/$(subst .,,$(suffix $@)).py $@ This will rebuild any of the include files that match the pattern ``$(output)/makefile.%``, if the corresponding python script changes, @@ -241,64 +268,68 @@ This will rebuild any of the include files that match the pattern The Python scripts that output these makefiles, all use the ``MakefileBuilder`` class in the ``makefile_builder.py`` file, and are all located in the ``bin/makefile-builder/`` directory. Consider a -simplified example Python code: :: +simplified example Python code: + +.. code-block:: python + + from makefile_builder import MakefileBuilder + from builder_data import sphinx - from makefile_builder import MakefileBuilder - from builder_data import sphinx + m = MakefileBuilder() - m = MakefileBuilder() + m.section_break('sphinx targets', block='sphinx') + m.comment('each sphinx target invokes and controls the sphinx build.', block='sphinx') + m.newline(block='sphinx') - m.section_break('sphinx targets', block='sphinx') - m.comment('each sphinx target invokes and controls the sphinx build.', block='sphinx') - m.newline(block='sphinx') + for (builder, prod) in sphinx: + m.newline(1, builder) + m.append_var('sphinx-targets', builder) - for (builder, prod) in sphinx: - m.newline(1, builder) - m.append_var('sphinx-targets', builder) + if prod is True and builder != 'epub': + b = 'production' + m.target(builder, block=b) + else: + b = 'testing' + m.target(builder, 'sphinx-prerequisites', block=b) - if prod is True and builder != 'epub': - b = 'production' - m.target(builder, block=b) - else: - b = 'testing' - m.target(builder, 'sphinx-prerequisites', block=b) + m.job('mkdir -p $(branch-output)/' + builder, block=b) + m.msg('[$@]: created $(branch-output)/' + builder, block=b) + m.msg('[sphinx]: starting $@ build', block=b) + m.msg('[$@]: build started at `date`.', block=b) + m.job('$(SPHINXBUILD) -b $@ $(ALLSPHINXOPTS) $(branch-output)/$@', block=b) - m.job('mkdir -p $(branch-output)/' + builder, block=b) - m.msg('[$@]: created $(branch-output)/' + builder, block=b) - m.msg('[sphinx]: starting $@ build', block=b) - m.msg('[$@]: build started at `date`.', block=b) - m.job('$(SPHINXBUILD) -b $@ $(ALLSPHINXOPTS) $(branch-output)/$@', block=b) + m.write('makefile.output-filename') - m.write('makefile.output-filename') - You can also call ``m.print_content()`` to render the makefile to standard output. See ``makefile_builder.py`` for the more methods that you can use to define makefiles. This code will generate a makefile -that resembles the following: :: - - sphinx-targets += epub - epub:sphinx-prerequisites - @mkdir -p $(branch-output)/epub - @echo [$@]: created $(branch-output)/epub - @echo [sphinx]: starting $@ build - @echo [$@]: build started at `date`. - @$(SPHINXBUILD) -b $@ $(ALLSPHINXOPTS) $(branch-output)/$@ - - sphinx-targets += html - html:sphinx-prerequisites - @mkdir -p $(branch-output)/html - @echo [$@]: created $(branch-output)/html - @echo [sphinx]: starting $@ build - @echo [$@]: build started at `date`. - @$(SPHINXBUILD) -b $@ $(ALLSPHINXOPTS) $(branch-output)/$@ - - sphinx-targets += gettext - gettext:sphinx-prerequisites - @mkdir -p $(branch-output)/gettext - @echo [$@]: created $(branch-output)/gettext - @echo [sphinx]: starting $@ build - @echo [$@]: build started at `date`. - @$(SPHINXBUILD) -b $@ $(ALLSPHINXOPTS) $(branch-output)/$@ +that resembles the following: + +.. code-block:: python + + sphinx-targets += epub + epub:sphinx-prerequisites + @mkdir -p $(branch-output)/epub + @echo [$@]: created $(branch-output)/epub + @echo [sphinx]: starting $@ build + @echo [$@]: build started at `date`. + @$(SPHINXBUILD) -b $@ $(ALLSPHINXOPTS) $(branch-output)/$@ + + sphinx-targets += html + html:sphinx-prerequisites + @mkdir -p $(branch-output)/html + @echo [$@]: created $(branch-output)/html + @echo [sphinx]: starting $@ build + @echo [$@]: build started at `date`. + @$(SPHINXBUILD) -b $@ $(ALLSPHINXOPTS) $(branch-output)/$@ + + sphinx-targets += gettext + gettext:sphinx-prerequisites + @mkdir -p $(branch-output)/gettext + @echo [$@]: created $(branch-output)/gettext + @echo [sphinx]: starting $@ build + @echo [$@]: build started at `date`. + @$(SPHINXBUILD) -b $@ $(ALLSPHINXOPTS) $(branch-output)/$@ All information about the targets themselves are in the ``builder_data.py`` file, that contains a number of variables that @@ -309,13 +340,13 @@ in ``builder_data.py``. System `````` -The build system contains the following 8 makefiles: +The build system contains the following 8 makefiles: - *pdfs*: Encodes the process for transforming Sphinx's LaTeX output - into pdfs. + into pdfs. - *tables*: Describes the process for building all tables generated - using ``table_builder.py``. + using ``table_builder.py``. - *links*: Creates the symbolic links required for production builds. @@ -326,12 +357,12 @@ The build system contains the following 8 makefiles: - *releases*: Describe targets for generating files for inclusion in the installation have the versions of MongoDB automatically baked - into the their text. + into the their text. - *errors*: Special processing of the HTTP error pages. - *migrations*: Describes the migration process for all non-sphinx - components of the build. + components of the build. - *sphinx-migrations*: Ensures that all sphinx migrations are fresh. @@ -341,7 +372,7 @@ Troubleshooting If you experience an issue with the generated makefiles, the generated files have comments, and are quite human readable. To add new generated targets or makefiles, experiment first writing makefiles -themselves, and then write scripts to generate the makefiles. +themselves, and then write scripts to generate the makefiles. Because the generated makefiles, and indeed most of the build process does not echo commands, use ``make -n`` to determine the actual diff --git a/meta.organization.rst b/source/meta/organization.txt similarity index 74% rename from meta.organization.rst rename to source/meta/organization.txt index da124a38228..ae6f86021ad 100644 --- a/meta.organization.rst +++ b/source/meta/organization.txt @@ -1,3 +1,5 @@ +.. _documentation-organization: + ================================== MongoDB Documentation Organization ================================== @@ -8,10 +10,9 @@ 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 -`_ or be in contact with someone -on the `documentation team `_ if you have any -questions. +If you have questions, don't hesitate to open a ticket in the `Documentation Jira Project +`_ or contact +the `documentation team `_. Global Organization ------------------- @@ -19,22 +20,22 @@ Global Organization Indexes and Experience ~~~~~~~~~~~~~~~~~~~~~~ -There are two "index files," for the documentation -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 +The documentation project has two "index files": ``/contents.txt`` and +``/index.txt``. The "contents" file +provides the documentation's tree structure, which Sphinx uses +to create the left-pane navigational structure, to power the "Next" and +"Previous" page functionality, and to provide 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. +first land on 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 +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 +"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. @@ -75,34 +76,34 @@ 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 +- "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 +- "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. - - *applications/use-cases* - contains use cases that detail how + - "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, +- "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, +- "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 +- "tutorial" - contains operational guides and tutorials that lead users through common tasks (administrative and conceptual) with MongoDB. This includes programming patterns and operational guides. -- *faq* - contains all the frequently asked questions related to +- "faq" - contains all the frequently asked questions related to MongoDB, in a collection of topical files. diff --git a/meta.practices.rst b/source/meta/practices.txt similarity index 78% rename from meta.practices.rst rename to source/meta/practices.txt index bba51ef434d..0275d23e99b 100644 --- a/meta.practices.rst +++ b/source/meta/practices.txt @@ -2,58 +2,56 @@ 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. +This document provides an overview of the practices and processes. .. contents:: 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 . +When relevant, include a Jira case identifier in a commit +message. Reference documentation cases when applicable, but feel free to +reference other cases from `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. +For the sake of consistency, remove trailing whitespaces in +the source file. + +"Hard wrap" files to 70 characters per-line. Standards and Practices ----------------------- -- All non-trivial at least two people should vet 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. +- All development and editorial work should transpire on github branches + or forks that editors can then merge into + the publication branches. Collaboration ------------- -To propose a change to the documentation, either: +To propose a change to the documentation, do either of the following: - Open a ticket in the `documentation project - `_ 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. + `_ proposing the change. + Someone on the documentation team will make the change and be in + contact with you so that you can review the change. -- Using github, fork the repository, commit your changes to this - repository and issue a pull request, and someone on the +- Using `GitHub `_, fork the `mongodb/docs repository `_, + commit your changes, and issue a pull request. Someone on the documentation team will review and incorporate your change into the documentation. Builds ------ -Building the documentation is useful because Sphinx and docutils can +Building the documentation is useful because `Sphinx `_ and docutils can catch numerous errors in the format and syntax of the documentation. Additionally, having access to an example documentation as it *will* appear to the users is useful for providing more @@ -68,17 +66,17 @@ Publication ----------- 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 +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. Other targets include: - ``man`` - builds UNIX Manual pages for all Mongodb utilities. - ``push`` - builds and deploys the contents of the - "``../public-docs/``". + ``../public-docs/``. - ``pdfs`` - builds a PDF version of the manual (requires LaTeX dependencies.) @@ -88,15 +86,15 @@ Branches This section provides an overview of the git branches in the MongoDB documentation repository and their use. -At the present time, future work transpires in the "``master``", with -the main publication being "``current``." As the documentation +At the present time, future work transpires in the ``master``, with +the main publication being ``current``. As the documentation stabilizes, the documentation team will begin to maintain branches of the documentation for specific MongoDB releases. Migration from Legacy Documentation ----------------------------------- -The `MongoDB.org Wiki ` contains +The MongoDB.org Wiki contains a wealth of information. As the transition to the Manual (i.e. this project and resource) continues, it's *critical* that no information disappears or goes missing. The following process outlines *how* to @@ -147,7 +145,7 @@ Types of Review ~~~~~~~~~~~~~~~ The content in the Manual undergoes many types of review, including -the following: +the following: Initial Technical Review ```````````````````````` @@ -175,7 +173,7 @@ This occurs post-publication and is content focused. The goals of consistency reviews are to increase the internal consistency of the documentation as a whole. Insert relevant cross-references, update the style as needed, and provide background fact-checking. - + When possible, consistency reviews should be as systematic as possible and we should avoid encouraging stylistic and information drift by editing only small sections at a time. @@ -195,18 +193,20 @@ Review Methods If you're not a usual contributor to the documentation and would like to review something, you can submit reviews in any of the following -methods: +methods: - If you're reviewing an open pull request in GitHub, the best way to comment is on the "overview diff," which you can find by clicking on the "diff" button in the upper left portion of the screen. You can - also use the following URL to reach this interface: :: - - https://github.com/mongodb/docs/pull/[pull-request-id]/files + also use the following URL to reach this interface: + + .. code-block:: none + + https://github.com/mongodb/docs/pull/[pull-request-id]/files Replace ``[pull-request-id]`` with the identifier of the pull request. Make all comments inline, using GitHub's comment system. - + You may also provide comments directly on commits, or on the pull request itself but these commit-comments are archived in less coherent ways and generate less useful emails, while comments on the @@ -218,16 +218,18 @@ methods: line, or affect multiple files. - Create a fork of the repository in your GitHub account, make any - required changes and then create a pull request with your changes. - + required changes and then create a pull request with your changes. + If you insert lines that begin with any of the following - annotations: :: - - .. TODO: - TODO: - .. TODO - TODO - + annotations: + + .. code-block:: none + + .. TODO: + TODO: + .. TODO + TODO + followed by your comments, it will be easier for the original writer to locate your comments. The two dots ``..`` format is a comment in reStructured Text, which will hide your comments from Sphinx and diff --git a/meta.style-guide.rst b/source/meta/style-guide.txt similarity index 61% rename from meta.style-guide.rst rename to source/meta/style-guide.txt index 061bd36440d..73c2c10472c 100644 --- a/meta.style-guide.rst +++ b/source/meta/style-guide.txt @@ -1,3 +1,5 @@ +.. _documentation-style-guide: + =========================================== MongoDB Documentation Style and Conventions =========================================== @@ -8,9 +10,8 @@ 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) document for more -information regarding the MongoDB Manual organization. +For information regarding the MongoDB Manual organization, see +:ref:`documentation-organization`. Document History ---------------- @@ -25,7 +26,10 @@ 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**: Bob proposed an addition to the *Referencing* section. +**2012-08-10**: Addition to the "Referencing" section. + +**2013-02-07**: Migrated this document to the manual. Added "map-reduce" +terminology convention. Other edits. Naming Conventions ------------------ @@ -81,33 +85,42 @@ 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.") + something else, and another thing") before the conjunction + (e.g. "and" or "or."). - Do not add two spaces after terminal punctuation, such as periods. -- Use "American style" punctuation when enclosing punctuation - (i.e. parentheses, quotes, and similar) interacts with terminal - punctuation (i.e. periods, commas, colons, and similar.) This rule - dictates that the terminal punctuation always goes *within* the - enclosing punctuation, even if the terminal punctuation affects the - sentence/clause outside of the quote or parenthetical. +- Place commas and periods inside quotation marks. + +.. NOTE: The above bullet replaces the commented bullet below. American style + refers only to quote marks and not to parenthesis. I consulted several sites, + including this one: http://www.thepunctuationguide.com/british-versus-american-style.html - This is counter to the "logical style" which is default in British - English, because its easier to be consistent and edit using this - rule, and because the style of the documents tends towards American - English. +.. - Use "American style" punctuation when enclosing punctuation + (i.e. parentheses, quotes, and similar) interacts with terminal + punctuation (i.e. periods, commas, colons, and similar.) This rule + dictates that the terminal punctuation always goes *within* the + enclosing punctuation, even if the terminal punctuation affects the + sentence/clause outside of the quote or parenthetical. - The one exception is if a literal string or inline code snippet is - enclosed in quotations or parenthesis, it may make sense to move a - period or comma further away from the literal string to avoid - copy-and-paste errors or other confusion. For example, in this case, - "``cfg.members[0].priorty = 1``." is worse than - "``cfg.members[0].priorty = 1``". +.. This is counter to the "logical style" which is default in British + English, because its easier to be consistent and edit using this + rule, and because the style of the documents tends towards American + English. -- Use title case, that capitalizes the first letter of the first, - last, and all significant words, for headings and document titles. +.. NOTE This last paragraph in the bullet (below) uses an example we no longer do. + We no longer put parens around literals. + +.. The one exception is if a literal string or inline code snippet is + enclosed in quotations or parenthesis, it may make sense to move a + period or comma further away from the literal string to avoid + copy-and-paste errors or other confusion. For example, in this case, + "``cfg.members[0].priorty = 1``." is worse than + "``cfg.members[0].priorty = 1``". + +- Use title case for headings and document titles. Title case capitalizes the first letter of the first, + last, and all significant words. Verbs ~~~~~ @@ -127,10 +140,10 @@ Verb tense and mood preferences, with examples: 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 + "Creating disk snapshots without locking the database will lead to an inconsistent state." -- Avoid helper verbs, as possible to increase clarity and +- 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. @@ -140,7 +153,7 @@ 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 - for a "``:issue:``" role that will link directly to a Jira case + an ``:issue:`` role that links directly to a Jira case (e.g. ``:issue:\`SERVER-9001\```). - For non-object references (i.e. functions, operators, methods, @@ -174,7 +187,7 @@ General Formulations - Use appropriate commas and conjunctions in the list items. - Typically begin a bulleted list with an introductory sentence or - clause with a colon, comma, or semi-colon. + clause, with a colon or comma. - The following terms are one word: @@ -182,7 +195,7 @@ General Formulations - workflow - Use "unavailable," "offline," or "unreachable" to refer to a - ``mongod`` instance that cannot be accessed rather than the + ``mongod`` instance that cannot be accessed. Do not use the colloquialism "down." - Always write out units (e.g. "megabytes") rather than using @@ -192,24 +205,24 @@ 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" + an "h2" block, there should be either: 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 +- 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 when possible. + paragraphs. Err on the side of shorter paragraphs. -- 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. +- 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). -- In general, avoid paragraphs that consist of single sentences as +- 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. @@ -226,9 +239,9 @@ Structural Formulations ReStructured Text and Typesetting ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -- Use spaces between nesting parentheticals (and elements) in - JavaScript examples. For example, prefer "``{ [ a, a, a ] }``" over - "``{[a,a,a]}``". +- 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: @@ -245,95 +258,74 @@ ReStructured Text and Typesetting 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. + 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 +- As it makes sense, use the ``.. code-block:: [language]`` form to insert literal blocks into the text. While the double colon, - "``::``", is functional, the directive makes the source easier to + ``::``, is functional, the ``.. code-block:: [language]`` form makes the source easier to read and understand. -- For all mentions of referenced types (i.e. database commands, query - operators, aggregation framework expressions and pipeline operators, - java script functions, statuses, etc.) use the reference types to +- 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. Jargon and Common Terms ----------------------- -MongoDB and Database Organization -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Database Systems and Processes +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Refer to MongoDB as "MongoDB" rather than mongo or Mongo when referring -to the entire database system, including possibly ``mongod`` and -``mongos``. +- To indicate the entire database system, use "MongoDB," not mongo or + Mongo. -Refer to ``mongod`` or ``mongos`` by name to indicate the database -process, or server instance itself. These are "processes" or -"instances." Reserve "database" for referring to a database (i.e. the -structure that holds collections and refers to a group of files on -disk.) +- 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," over other - variants. (e.g. sharded clusters, or sharded systems.) +- Refer to partitioned systems as "sharded clusters." Do not use + shard clusters or sharded systems. -- Refer configurations that run with replication as "replica sets" (or +- Refer to configurations that run with replication as "replica sets" (or "master/slave deployments") rather than "clusters" or other variants. -Data Structures -~~~~~~~~~~~~~~~ - -Use the following convention when referring to specific parts of -MongoDB data: +Data Structure Terms +~~~~~~~~~~~~~~~~~~~~ -- *document* refers to "rows," or records in a MongoDB +- "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 +- "field" refers to a "key" or "identifier" of data within a MongoDB document. -- *value* refers to the contents of a *field*. - -Use "sub-document" as needed to describe nested documents. - -Notes on Specific Features -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -- Geo-Location +- "value" refers to the contents of a "field". - #. While MongoDB *is capable* of storing coordinates in - (sub-documents,) in practice, users should only store coordinates - in arrays. (See: `DOCS-41 `_) - -- *Others...* +- "sub-document" describes a nested document. Other Terms ~~~~~~~~~~~ -- Use "**sharded 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 +- 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. +- Hyphenate "map-reduce" in order to avoid ambiguous reference to the + command name. Do not camel-case. -At some point in the near future creating a more standardized the -nomenclature for examples of architectural elements and code -components may be necessary. +Notes on Specific Features +-------------------------- + +- Geo-Location + + #. While MongoDB *is capable* of storing coordinates in + sub-documents, in practice, users should only store coordinates + in arrays. (See: `DOCS-41 `_.)