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.
Contents
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 <http://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.
- 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.
To propose a change to the documentation, either:
- 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.
- Using github, fork the repository, commit your changes to this repository and issue a pull request, and someone on the documentation team will review and incorporate your change into the documentation.
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.
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.)
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.
The MongoDB.org Wiki <http://www.mongodb.org/display/DOCS> 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.
The content in the Manual undergoes many types of review, including the following:
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."
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."
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.
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.
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.