MongoDB Documentation, Release 3.0.4 Style Guide and Documentation Conventions Document History Naming Conventions Style Guide 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. 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 (page 939). This section contains guidelines on naming files, sections, documents and other document elements. • File naming Convention: – For Sphinx, all files should have a .txt extension. – Separate words in file names with hyphens (i.e. - .) – For most documents, file names should have a terse one or two word name that de- scribes the material covered in the document. Allow the path of the file within the doc- ument tree to add some of the required context/categorization. For example it’s ac- ceptable to have http://docs.mongodb.org/manual/core/sharding.rst and http://docs.mongodb.org/manual/administration/sharding.rst . – For tutorials, the full title of the document should be in the file name. For example, • Phrase headlines and titles so users can determine what questions the text will answer, and material that will be addressed, without needing them to read the content. This shortens the amount of time that people spend looking for answers, and improvise search/scanning, and possibly “SEO.” • Prefer titles and headers in the form of “Using foo” over “How to Foo.” • When using target references (i.e. :ref: references in documents), use names that include enough context to be intelligible through all documentation. For example, use “ replica-set-secondary-only-node ” as opposed to “ secondary-only-node ”. This makes the source more usable and easier to maintain. 930 Chapter 13. About MongoDB Documentation 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. 2013-02-07 : Migrated this document to the manual. Added “map-reduce” terminology convention. Other edits. 2012-08-10 : Addition to the “Referencing” section. 2013-11-15 : Added new table of preferred terms.