Style guide#

This chapter defines the conventions for writing Duckietown technical documentation.

Organization#

The documentation is divided into books, parts (labeled part:), chapters (labeled chapter:), and sections (labeled sec:).

The structure of each book is defined in src/_toc.yml.

General guidelines for technical writing#

The following guidelines apply to all technical writing.

  • Write the documentation in correct English.

  • Use “should” and “must” deliberately; each has a distinct meaning.1

  • Omit “please”; it is unnecessary in technical documentation:

    Wrong

    “Please remove the SD card.”

    Better

    “Remove the SD card.”

  • Avoid colloquialisms and unexplained abbreviations:

    Wrong

    “The pwd is ubuntu.”

    Better

    “The password is ubuntu.”

  • Capitalize Python when referring to the programming language:

    Wrong

    “If you are using python, follow these instructions.”

    Better

    “If you are using Python, follow these instructions.”

  • Do not use contractions:

    Wrong

    “It’s ready.”

    Better

    “It is ready.”

  • Avoid emojis.

  • Avoid ALL CAPS for emphasis; retain established acronyms, commands, and identifiers.

  • Use bold text sparingly.

  • Avoid exclamation points.

Style guide for the Duckietown documentation#

  • Use American English in English-language documentation:

    Incorrect

    behaviour

    Correct

    behavior

  • Format filenames and commands as inline code using Markdown backticks:

    Incorrect

    “Edit the ~/.ssh/config file using nano.”

    Correct

    “Edit the ~/.ssh/config file using nano.”

  • Do not use keyboard shortcuts or command names as verbs:

    Incorrect

    “Ctrl-C the command.”

    Correct

    “Press Ctrl-C in the terminal.”

  • Subtle humor and puns about duckies are encouraged.

Use only the complexity needed to convey your message, and do not use overly complex language to disguise flaws. A useful test is whether you can explain the topic clearly to a non-specialist.

Prefer concise wording

Use simpler wording when it does not change the meaning:

  • provide -> give

  • in order to -> to

  • utilize -> use

Naming and spelling#

  • Capitalize product names in prose, headings, link labels, captions, alternative text, and SEO descriptions: “Duckietown”, “Duckiebot”, “Duckiedrone”, “Duckiebox”, “Duckiebattery”, and “Duckiematrix”.

  • Use “Duckietown Shell”, “Duckietown Viewer”, “Duckietown Workspace”, “Duckietown Dashboard”, and “Dev Container” when referring to named tools and environments. Use lowercase forms in commands, package and repository names, URLs, filenames, anchors, configuration values, and SEO keywords.

  • Capitalize “Engine”, “Renderer”, and “Entity” when referring to Duckiematrix components and simulated objects. Use lowercase forms in command subcommands and flags.

  • Use “Raspberry Pi”, not “PI” or “raspi”.

  • Use - for unordered list items, including both levels of {list-table} rows. Use decimal-number markers followed by a period for ordered lists.

  • Use _italic text_ and __bold text__, rather than asterisks, for emphasis.

  • Write prose list items as complete sentences. Capitalize each item, end a standalone sentence with a period, and use a colon when an item introduces a nested block. Labels, option values, and table cells are exceptions.

Other conventions#

  • Place the seo directive immediately after any YAML front matter, before page labels, headings, and other content.

  • Every non-decorative {figure} and {image} directive must include a concise :alt: description. Add a figure caption to standalone diagrams, maps, screenshots, overview and reference figures, and completed assemblies. Omit captions for routine procedural-step images when adjacent instructions already identify the image.

  • Every {figure} directive must include a unique :name: label so that it can be referenced.

When instructing a user to edit a file, write edit /this/file.

Do not include an editing command such as the following unless the task requires a feature available only in a particular editor:

vi /this/file

Troubleshooting sections#

Write the main procedure assuming that every step succeeds.

Add a “Troubleshooting” section at the end.

Organize the section as a list of symptom-and-resolution pairs.

The following is an example of a troubleshooting section.

Troubleshooting#

Use the {trouble} directive to define troubleshooting entries. For example:

Troubleshooting

SYMPTOM

The camera image is blank.

RESOLUTION

Check that the camera cable is fully inserted. Disconnect and reconnect it if necessary.

1

The meanings of these terms are defined in RFC 2119.