6. Style Conventions and Content Layout#
The edX documentation is authored using reStructuredText markup syntax. For a description and complete documentation, see reStructuredText .
For a sample .rst file that contains examples of the markup used by the edX
documentation team, see the
edx-documentation/en_us/edx_style_guide/source/ExampleRSTFile.rst
file.
Item |
.rst Formatting |
Examples |
Notes |
Book or guide name |
|
Building and Running an edX Course |
When you provide the title of the guide in addition to a cross-reference to a specific section or topic in the guide, link the section or topic and then place the name of the guide in italics. Otherwise, make the title the cross reference link instead of presenting it in italics. Translator guidance is that strings in italic font should be translated. |
Code samples |
|
The member fields of this dictionary are |
Use For longer examples, such as XML templates that include text that can be translated, use the code block markup and include a comment for translators with explicit instructions.
<problem display_name="webGLDemo">
In the image below, click the cone.
|
Programming elements |
|
The An XBlock must set |
Follow the same rules as for code samples. Programming elements include attributes, classes, events, functions, methods, parameters, and properties. Identify the element type on first mention. Element names only need an article when the text also includes the element type.
|
Unnamed icons |
“brief description” |
Select “back 30 seconds” on the playback bar. |
In most cases, icons have mouseover help text. If the icon has
help text, use that text as the name of the control and
use |
New term |
optional: link to glossary definition |
This section provides conceptual and procedural information about
using |
Add new terms to the glossary. If you want to be sure that people understand how you are using the term, provide a link to the glossary definition. Do not italicize newly introduced terms. |
User interface controls |
|
From the Tools menu, select Import. In the discussion navigation pane, select Filter messages like this. |
For more information about user interface controls in edX products, see Documenting User Interface Interactions. Translator guidance is that strings in boldface font can be translated. |
User input |
|
In the Show Calculator field, type |
Follow the same rules as for code samples. The assumption is that values presented in monospace font must be entered exactly as documented, and that translated versions of the value are not acceptable. If the user input value can be translated, add a “Translator:” comment to that effect. |
Variables |
Surround with braces ({}). |
…in the format |
Avoid angle brackets (< >) because rST uses angle brackets to identify XML examples. |