Quickstart
Warning
This page needs updated content and examples for MongoDB. Though incomplete, this page contains useful information and should be considered a resource though it is under revision.
Thank you for contributing to MongoDB content!
Don't worry if your job title doesn't include the word writer, information, or content—your most important contribution is your knowledge and expertise. Your willingness to share what you know with users will help them to accomplish their goals and be successful.
The Documentation team is ready to help turn your contributions into clear, concise, consistent, easy-to-read content for users. We do this, in part, by adhering to the standards that are defined in this style guide. The team doesn't expect contributors to know or adhere to all of these standards; however, if you are interested in improving your writing or learning some of the style standards at MongoDB, we invite you to explore them.
The style guide includes hundreds of standards, but you can start with the following ones to help you boost the effectiveness of your writing.
Standard | More information and examples |
|---|---|
Write in active voice. Active voice makes the performer of the action (usually the user) the subject of the sentence. Active-voice sentences are more direct and easier to understand than passive-voice sentences. | |
Use present tense. Users read content to help them perform tasks or to gather information. These activities occur in the users' present time, so the present tense is appropriate in most content. | |
Write to the user by using second person and imperative mood. Users are more engaged with content when it talks to them directly. You talk to users directly by using second person, addressing the user as you. When you use second person with the imperative mood (in which the subject you is understood) and active voice, you make the text clear, concise, and direct. | |
Write short sentences and paragraphs, and use lists whenever possible. Even a well-written long sentence can be hard to follow and understand, so try to limit sentences to 25 words. Short paragraphs are easier to scan and understand than longer ones. When listing three or more items, use a bullet list instead of embedding the items in a paragraph. | |
Use action-oriented verbs. Verbs carry the action in a sentence, and they make your content come alive for users. To make the biggest impact with your writing, use strong, simple, action verbs. | |
Write clear and brief step text. When you write instructions for users, write short steps, number them, and use active voice and imperative mood. | |
Clarify pronouns. Pronouns such as it, this, there, and that are useful, but you must ensure that their antecedents (the words that they are used in place of) are clear, and that they (the pronouns) don’t cause vagueness and ambiguity. | |
Use correct punctuation. Use periods to end most sentences, avoid quotation marks, and use serial commas. | |
Use AP headline-style capitalization for all titles and headings. To meet AP headline-style (or AP title case) capitalization requirements, refer to the guidelines in the Titles and Headings guide. | |
Write clear and consistent code examples. When you create blocks of code as input or output examples, follow some basic guidelines to make them clear to users. | |
Use consistent and simple terminology. Use short, simple words, and use them as they are defined in a general or accepted industry dictionary. Each word or phrase should have only one meaning that is used consistently throughout the content. Avoid using humor, jargon, and metaphors. |