MongoDB Documentation Practices and Processes¶

This document provides an overview of the practices and processes.

Commits¶

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, remove trailing whitespaces in the source file.

“Hard wrap” files to between 72 and 80 characters per-line.

Standards and Practices¶

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 on GitHub branches or forks that editors can then merge into the publication branches.

Collaboration¶

To propose a change to the documentation, do either of the following:

Open a ticket in the documentation project 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 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 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 effective basis for the review process. 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.

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 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/.
pdfs - builds a PDF version of the manual (requires LaTeX dependencies.)

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 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 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 migrate a wiki page to the manual:

Read the relevant sections of the Manual, and see what the new documentation has to offer on a specific topic.

In this process you should follow cross references and gain an understanding of both the underlying information and how the parts of the new content relates its constituent parts.
Read the wiki page you wish to redirect, and take note of all of the factual assertions, examples presented by the wiki page.
Test the factual assertions of the wiki page to the greatest extent possible. Ensure that example output is accurate. In the case of commands and reference material, make sure that documented options are accurate.
Make corrections to the manual page or pages to reflect any missing pieces of information.

The target of the redirect need not contain every piece of information on the wiki page, if the manual as a whole does, and relevant section(s) with the information from the wiki page are accessible from the target of the redirection.
As necessary, get these changes reviewed by another writer and/or someone familiar with the area of the information in question.

At this point, update the relevant Jira case with the target that you’ve chosen for the redirect, and make the ticket unassigned.
When someone has reviewed the changes and published those changes to Manual, you, or preferably someone else on the team, should make a final pass at both pages with fresh eyes and then make the redirect.

Steps 1-5 should ensure that no information is lost in the migration, and that the final review in step 6 should be trivial to complete.

Review Process¶

Types of Review¶

The content in the Manual undergoes many types of review, including the following:

Initial Technical Review¶

Review by an engineer familiar with MongoDB and the topic area of the documentation. This review focuses on technical content, and correctness of the procedures and facts presented, but can improve any aspect of the documentation that may still be lacking. When both the initial technical review and the content review are complete, the piece may be “published.”

Content Review¶

Textual review by another writer to ensure stylistic consistency with the rest of the manual. Depending on the content, this may precede or follow the initial technical review. When both the initial technical review and the content review are complete, the piece may be “published.”

Consistency Review¶

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.

Subsequent Technical Review¶

If the documentation needs to be updated following a change in functionality of the server or following the resolution of a user issue, changes may be significant enough to warrant additional technical review. These reviews follow the same form as the “initial technical review,” but is often less involved and covers a smaller area.

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:

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
```
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 pull request lead to less specific changes to the document.
Leave feedback on Jira cases in the DOCS project. These are better for more general changes that aren’t necessarily tied to a specific 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.

If you insert lines that begin with any of the following annotations:
```
.. 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 publication if you’re worried about that.

This format is often easier for reviewers with larger portions of content to review.