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.
...
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 | |||
...
| 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. |
...