Style Guide
This page aims to provide guidance for people contributing to the DCC-EX website on how to write individual pages to a) provide a better user experience, and b) be easier to maintain the documentation.
Text and Style Standards
Please ensure to follow the standards below when creating or updating documentation to ensure the look and feel of the website remains consistent.
Style Guidelines
Every page (except a few pages like home, about, contact, etc.) MUST start with one or more level images (after the title) to indicate the intended base audience for the page.
Where possible, use the expansions for the level images:
|conductor|
|tinkerer|
|engineer|
|conductor-no-text|
|tinkerer-no-text|
|engineer-no-text|
Where possible, use the Team and Product names the expansions (not possible in headings)
|DCC-EX| for DCC-EX
|EX-CS| for EX‑CommandStation
|EX-MS| for EX‑MotorShield8874
|EX-CSB1| for EX‑CommandStation / Booster One Express
|EX-CSB1-SHORT| for EX‑CSB1
|EX-I| for EX‑Installer
|EX-R| for EXRAIL
|EX-TT| for EX‑Turntable
|EX-DCCI| for EX‑DCCInspector
|BSC| for BaseStationClassic (DCC++)
Where possible, use the expansions for the level text (not possible in headings)
Additional expansions that should be used where possible: (currently these hyperlink to the the glossary but the intention is to have them link somewhere more sensible later.)
|DCC|
|DC|
|DC PWM|
|Motor Driver|
|JMRI|
|Engine Driver|
|wiThrottle|
|wiThrottle Protocol|
|wiThrottle Server|
|wiThrottle Lite|
|DCC-EX Native Commands| produces DCC-EX Native Commands
|DCC-EX Native Protocol| produces DCC-EX Native Protocol
|Access Point|
|Access Point Mode|
|Station Mode|
|I2C| (note this has no link, it simply replaces ‘I2C’ with I2C)
Avoid abbreviations that would not be easily recognised by ‘Conductors’.
In particular don’t use ‘CS’. Use the full name ‘Command Station’
Don’t use ‘AP’. Use ‘Access Point’ or ‘Access Point Mode’
Don’t use ‘STA’. Use ‘Station’ or ‘Station Mode’
Limit the use of using ‘RTR’ or ‘R2R’. Use ‘ready-to-run’ or ‘ready-to-run (RTR)’
Limit the use of* using ‘DIY’. Use ‘do-it-yourself’ or ‘do-it-yourself (DIY)’
Avoid ‘fluff’ - unnecessary text that adds no value.
Re-read everything you write. Ask yourself a) is there a simpler way of saying it. b) does it add value.
The exception to this is a bit of humour now and then, but don’t overdo it.
Keep headings short. If it fills the page it is too long.
Keep sentences short. Break them up where ever possible.
Keep paragraphs short. Break them up where practical.
Keep paragraphs on the same topic. If the topic changes start a new paragraph.
Do not start any page for a Conductor or Tinkerer with a technical explanation. Put technical explanations at the end of the page or preferably in a separate dedicated page.
If you have a number of sections that describe options; present them in list them first, before the sections, with an explanation as to why they are optional. (i.e. a bullet list with hyperlinks to the headings.)
Where possible, avoid starting a section with a negative point of view. i.e. Talk about the positives of what you are discussing first, before you delve into the negative or problematic aspects.
e.g. Don’t start with “… This is not for Conductors…”, instead say “..This page is for Tinkerers … Conductors should…”.Use British/Australian/Canadian/Indian (pretty much every except the USA) spelling e.g. ‘colour’ not ‘color’.
(Primarily because it is used in more English speaking countries)Preferred Terms:
Use “Motor Driver”, not “Motor Shield”, “Motor Board”, “Motorboard”
In general use ‘train’ or ‘loco’ instead of ‘locomotive’ or ‘engine’
Use “Smart Phone” instead of ‘Cell Phone’ (US only term) or ‘Mobile Phone’ (just about everywhere else)
Use Throttle or Throttle (controller) instead of ‘controller’ or ‘controller (throttle)’
Use railroad/railway terminology that is understandable by all English-speaking people.
Where there are clear differences from US to non-US terminology use both with a slash between and use the US version first. e.g. turnouts/points, consists/multiple units, switching/shunting. (Only because the US term appears in apps like JMRI.)No full stop at the end of a numbered or unnumbered list
Numbered lists should generally only be used if they are describing a specific sequence, or the numbering is important to the text
Use first person (you and your; not I, me, my or am) language
A string of nouns should be generally be sequenced in alphabetic order, unless it makes more sense within the context to display them in some other sequence
Double quotes (”) should only be used for quoting text from people, documents or web sites
No quotes around ‘Also See’ type references
Avoid ‘(above)’ or ‘(below)’ in text. Use hypertext links instead
``.. todo:: description…`` means that it is still a work-in-process and needs to be updated. It must be followed by descriptive text describing the issue to be fixed. If you want to to show in the page you will need add a separate line.
Use ``literal text blocks`` when describing preference values -
literal text blocksUse :menuselection:`Menu --> Preferences --> ..` for menu descriptions -
Use :guilabel:`GUI labels` for buttons - GUI labels
For dates, use dd-mmm-yyyy or yyyy-mm-dd to avoid confusion with the way dates are uniquely written in the US.
e.g. 2-Mar-2022 or 2022-3-2, not 2-3-2022Heading levels:
######### with overline, for parts - not really used
************ Page Titles
========= for sections
———————- for subsections (hyphen)
^^^^^^^^^^ for subsubsections
~~~~~~~~~~ for paragraphs
only if really needed (i.e. avoid):
''''''''''''''''''''''''''' for sub paragraphs
____________ for sub-sub-paragraphs (hyphens)
To force a :
Line break/new line use |BR|
Non-breaking space use |_|
Blank line use | on its own line
Paragraph break that a ‘float right’ element must not be placed before a point use |force-break|
useful if the ‘float right’ element is being placed beside another ‘float right’ element, rather than below.
To add a horizontal line, use ---- (four hyphens) on its own line