2. Preferred Usage

can, might, and may	Use the verb “can” to describe ability, capability, or capacity. Use “might” to describe possibility or eventuality. Because “may” implies permission, the edX documentation team prefers to use one of the other two verbs.
capitalization	Use title capitalization for headings. When referring to elements in the user interface, follow the capitalization that is used in the labels or text. Do not capitalize job titles, such as professor, instructor, or program manager. Do not capitalize terms unless they are trademarks, so refer to the instructor dashboard or a course about video rather than the Instructor Dashboard or a course About video.
contractions	Do not use.
cross-references	Introduce standalone cross-references to other edX topics with the phrase, “For more information, see :ref:`{topic name}`”. To include more specific information about the material you are referencing, use the expanded phrase, “For more information about {task or concept}, see :ref:`{topic name}`”. Exception: In the glossary, cross-references to other glossary entries begin with, “See :ref:`{topic name}`” if the current entry consists only of the cross reference. To refer to a related entry, use “See also :ref:`{topic name}`”. To include a cross-reference inline, extend the cross-reference to include a phrase that makes sense in context. In this example, to create a sentence with the correct capitalization, “course launch checklist” is added to the cross-reference markup. “To verify that the course is ready for release, you can use the :ref:`course launch checklist<Course Launch Checklist>`.” For a cross-reference to an external resource, provide the title of the destination, not just a URL. This style promotes a better experience for those using screen readers. In addition, avoid repeating links to the same destination multiple times on a single HTML page. Exception: use “edx.org” to refer to the https://www.edx.org website.
dates	Format dates as DD Mon YYYY or DD Month YYYY. For example, 11 Jan 2015. Do not use both date formats within the same .rst file.
first person	Do not use “I” or “me” unless you are following the text of a user interface label or message. Avoid using “we”. If edX or another entity has established a best practice, identify the entity that recommends that practice by name.
heading style	Use title case for all headings. For a top level section heading and for topics that introduce concepts, use a verb in gerund form to start the title. For topics that describe a procedure, use an imperative verb to start the title. For example, “Adding Course Updates and Handouts”, “Adding a Course Update”, and “Identify a Course Handout”. Avoid the use of nouns or noun phrases without a verb as headings.
hyphenation	Minimize the use of hyphenated compounds. Present compound words as either two separate words or a single word. Use hyphens only when the meaning is unclear without them. For exceptions to this rule, see the word list.
images	Minimize the use of screen shots. For more information, see Images.
lists	Introduce a list with a complete sentence that ends in a period. Do not use “the following” as a noun or to introduce a list. Instead, include the noun. For example, “The .csv file includes the following columns.” or “When pretty printed, this comment has the following format.””
pronouns	Avoid ambiguous pronouns such as all, each, many, several, some, that, them, these, those.
punctuation	Avoid slashes, particularly “and/or”. They introduce ambiguity. Avoid em dashes. Putting non-restrictive relative clauses into separate sentences leads to simpler, clearer writing. Do not use smart quotes or smart apostrophes. Use the straight versions of these marks.
redundancy	Avoid including unnecessary words. For example, instead of “Create a new {noun}”, use “Create a {noun}”, and instead of “Delete or edit an existing {noun}”, use “Delete or edit a {noun}.”
steps	To introduce an ordered list of procedural steps, use “To {verb task}, follow these steps.” Note the complete sentence and terminal period. For example, “To add a course update, follow these steps.””
tables	When you include a table, be sure to include a heading row. In addition, consider whether a stub column is appropriate. The heading row and stub column provide useful context for users of screen readers.
word choice	See the Word List for our preferred terminology. Avoid jargon, colloquialisms, and humor. Do not use non-technical words that are not in common use, such as “and so forth”, albeit, heretofore, thus, or whilst. Be careful of commonly used phrases that introduce ambiguity. For example, instead of “When the process completes…” use “After the process completes…”