Quickstart#
Thank you for contributing to Rackspace 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 Information Development 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 Rackspace, 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 active voice |
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. |
Use present tense |
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 to the user by using second person and imperative mood |
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. |
Write clear and concise sentences and paragraphs |
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. |
Use effective 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. |
Tasks |
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 pronouns carefully |
Use correct punctuation. Use periods to end most sentences, avoid quotation marks, and use serial commas. |
|
Use sentence-style capitalization for all titles and headings. In sentence-style capitalization, you capitalize only the first word of the title or heading, plus any proper terms and terms that are always capitalized, such as some abbreviations. |
Titles and headings |
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. |
Code examples |
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. |