MongoDB Manual 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.
If you have questions, don’t hesitate to open a ticket in the Documentation Jira Project or contact the documentation team.
Global Organization¶
Indexes and Experience¶
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 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.
Topical Organization¶
The placement of files in the repository depends on the type of documentation rather than the topic of the content. Like the difference between contents.txt and index.txt, by decoupling the organization of the files from the organization of the information the documentation can be more flexible and can more adequately address changes in the product and in users’ needs.
Files in the source/ directory represent the tip of a logical tree of documents, while directories are containers of types of content. The administration and applications directories, however, are legacy artifacts and with a few exceptions contain sub-navigation pages.
With several exceptions in the reference/ directory, there is only one level of sub-directories in the source/ directory.
Tools¶
The organization of the site, like all Sphinx sites derives from the toctree structure. However, in order to annotate the table of contents and provide additional flexibility, the MongoDB documentation generates toctree structures using data from YAML files stored in the source/includes/ directory. These files start with ref-toc or toc and generate output in the source/includes/toc/ directory. Briefly this system has the following behavior:
- files that start with ref-toc refer to the documentation of API objects (i.e. commands, operators and methods), and the build system generates files that hold toctree directives as well as files that hold tables that list objects and a brief description.
- files that start with toc refer to all other documentation and the build system generates files that hold toctree directives as well as files that hold definition lists that contain links to the documents and short descriptions the content.
- file names that have spec following toc or ref-toc will generate aggregated tables or definition lists and allow ad-hoc combinations of documents for landing pages and quick reference guides.