For comments on the original version of this draft, see the old Style Guide (Draft) page.
The doc team follows Microsoft Manual of Style for Technical Publications style in general, but defers to AP style where there are differences.
Documenting the User Interface
Do we include the names of UI controls ("click **Save**" or "click the Save button"? ). Are icons an exception? (Select the **Edit** icon).
Do we want to go for specificity or generality here? "Box," "field," and "menu" can refer to more things, but "text box," "drop-down menu," and "pop-up menu" can help a user locate a control more easily.
It would be good to add screen shots here when necessary.
| dialog box | A small box that opens temporarily when a user performs an action. The user interacts with elements in the dialog box, which then disappears. A dialog box might just have cancel/OK buttons, or it may ask a user to specify a file. | ||
| pop-up menu | A list of related options that opens when a user performs an action. The menu disappears after the user selects an option. | ||
| screen | Larger than a dialog box, with more options. | ||
| course accordion | The list of sections and subsections in the left pane of the Courseware page in the LMS. | ||
| course ribbon | The strip at the top of the Courseware page in the LMS that lists the units in a subsection. | ||
| checkbox | One word. | ||
| drop-down menu | |||
| window | |||
| right pane | For an unnamed panel on the right side of the screen. | ||
| left pane | For an unnamed panel on the left side of the screen. | ||
| component editor | |||
| field | |||
| box | |||
| text box | A box that a user types or pastes text into. Prefer field. | ||
| panel | A field on the right or left that doesn't extend for the entire length of the page. (Maybe?) | ||
| course tabs | |||
| page | |||
| button | |||
| control | |||
| radio button | |||
| heading | |||
| publishing status panel | |||
| course pages | |||
Grammar and Punctuation
Hyphenation (email, course re-runs, drop-down list, etc.)
USE Oxford comma!
Use an asterisk (*)
Avoid em dashes.
Preferred Usage
Include the period before file type abbreviations (.txt, not txt or TXT) A Word (.doc) file, a .csv file
Punctuation for list items
Capitalization of headings, terms (e.g. program manager)Don’t use “the following” as a noun
Instead of short sentence “See XXX”, preferred: “For more information, see XXX”
You can use the :ref:`course checklists<Use the Course Checklist>` to work through the course and verify that it is ready for release.
You can use vs. Use
Locate the course you want to re-run and click **Re-Run Course**. → Locate the course you want to re-run, and then click **Re-Run Course**.
What do we do when there are errors in the UI? Do we match the UI or use the correct spelling/form in the docs? --> Go with correct form; UI may catch up someday.
Leave out UI element name ("click OK" instead of "click OK button")
How to refer to our UI objects: e.g. navigation pane, tabs, page, component editor, etc.
Standard intro: "To do this, follow these steps" - do we use a colon to introduce tables/lists of steps?
spell out number? if yes what conditions: words 0-9, otherwise numerals (five, six, or 12 oranges)
date formatting (DD Mon YYYY or DD Month YYYY): 11 Jan 2015
How headings are worded (H1s: gerunds, etc.)
Notes, warnings, cautions -- which do we use and when?
Formatting: Do we have styles for "this kind of info goes in tables", standard formatting for step-by-step tasks
Mix of conceptual and procedural info - how to treat that (when do we recommend using ordered list of steps, when can we just talk about it in a narrative way)
When we describe “how to” information, do we always use an ordered list of steps? Do we ever describe how to do something in a more narrative way?
Do not use abbreviations. For example, replace etc. with "and so on".
Write short, clear sentences. Avoid dependent clauses.
Minimize use of screenshots and other graphics. For details about
Always use active voice
Introduce list: Complete sentence with terminal period
Preferred Spelling and Terminology
email (not e-mail or Email) – TBC fine for use as noun and adjective. Verb? Prefer "send an email message"? "send an email" OK as a noun; don't use as adj
smartphone (one word)
URL (not url). When providing a URL in documentation, omit trailing slashes (http://edx.org instead of http://edx.org/).
ID (not id)
third party (noun), e.g. "This product comes from a third party"); third-party (adjective), e.g. "third-party software"
Standardize on section vs. chapter vs. topic, etc.
Do we refer to “pop up box”, “dialog box”?
“Staff View” and “Student View”? or is it “the Staff view” and “the Student view”?
“Must” vs “have to” vs “should”
Don’t use “discussion forums”; use “course discussions”
“User rights” vs “privileges”
drop-down or dropdown list/menu
check box or checkbox (and do users “select” a checkbox or “check” a checkbox? “Clear” or “deselect”?)
learner v student: learner (sigh)
instructor v professor: instructor
Instructor Dashboard
Student Dashboard
Formatting and Content Layout
| Item | rST Formatting | Examples | Notes |
|---|---|---|---|
| Code samples | monospace | In the Discussion Topic Mapping field, place your cursor on the line between the opening brace ({) and the closing brace (}), and then paste the following code. Make sure to include both braces. "General": { | |
| Programming elements | bold | Methods, classes, functions | |
| Headings | ************** ========= Heading 3 Heading 4 Heading 5 | See the FormattingCheatSheet.nouse file in the edx-documentation/en-us/course_authors folder. | |
| Name of book or guide | Italic | ||
| New term | Italic | Rubrics contain criteria and options. | Make sure to add new terms to the glossary. |
| Programming elements (attributes, classes, functions, methods, parameters, properties, etc.) | monospace | The event_type parameter enables downstream processing... To participate in the course grade, an XBlock should set has_score to True... | Identify the element type on first mention. (SP: May not be necessary for our technical audience, but this will help with localization - thoughts?) Element names only need an article when the text also includes the element type: Set the Set X Set the |
| Title | ##### Title ##### | ||
| UI item (headings, fields, check boxes) | bold | In the Advanced Module List field, type... On the Tools menu, click Checklists. Under Add New Component, click HTML, and then click Text. When the Insert Link dialog box opens, enter the URL of the page you want in the URL field. In the left pane, select the Filter messages like this check box. | A UI item is anything that the user views, clicks, selects, or interacts with and that has a name. Don't use named UI elements as generic objects. In the Display Name field, enter a value. Enter a display name for the section. X Enter the Display Name. |
| User input |
| In the Show Calculator field, type | Inline if the user input is short (one line); indented if more than one line. |
| Values | monospace | In the vertical, set the parameter to False. |
Images
Guidelines for using screenshots in documentation (when is it necessary)
Resources for making screen captures (existing dummy course with good data)
Guidelines for making screen captures (sizes, resolution, how much of window to capture/exclude)
Processing screenshots (colors for borders, overlay items) and how to make higher res version available
Making images and accessible and easy to globalize
- if callouts or other additions are made to a screenshot, or text added to a diagram, put it in a separate layer from the images
- if text is used in graphics, leave 30% extra surrounding space for expansion
- instead of using text, use numbered identifiers and provide a legend
- use alt text so that screenreaders have information for the image
Writing for Globalization
Avoid colloquial terms, idioms, etc. that might not translate easily
Try to minimize small variations in standard phrases
Don't use contractions
See Style Guide (Draft).
To be confirmed:
Add words to the glossary to promote consistent use.
Question: will the use of soft returns to wrap strings in rst files cause issues for translators?