Style guide#

This chapter describes the style guide for our documentation. We will cover the conventions for writing the 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 stored inside the src/_toc.yml file.

General guidelines for technical writing#

The following holds for all technical writing.

  • The documentation is written in correct English.

  • The words “should” and “must” are not interchangeable, they have precise meanings;1

  • “Please” is unnecessary in technical documentation;

    Wrong

    “Please remove the SD card.”

    Better

    “Remove the SD card.”

  • Do not use colloquialisms or abbreviations;

    Wrong

    “The pwd is ubuntu.”

    Better

    “The password is ubuntu.”

  • Python is capitalized when used as a name;

    Wrong

    “If you are using python…”

    Better

    “If you are using Python…”

  • Do not use contracted forms;

    Wrong

    it’s

    Better

    it is

  • Do not use emojis;

  • Do not use ALL CAPS;

  • Make infrequent use of bold statements;

  • Do not use exclamation points;

Style guide for the Duckietown documentation#

  • The English version of the documentation is written in American English;

    Incorrect

    behaviour

    Correct

    behavior

  • All the filenames and commands must be enclosed in code blocks using Markdown backticks;

    Incorrect

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

    Correct

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

  • Ctrl-C, ssh, etc. are not verbs;

    Incorrect

    “Ctrl-C from the command line.”

    Correct

    “Use Ctrl-C from the command line.”

  • Subtle humor and puns about duckies are encouraged.

Frequently misspelled words#

  • “Duckiebot” is always capitalized.

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

  • These are other words frequently misspelled:

    5 GHz WiFi

Other conventions#

When the user must edit a file, just say: “edit /this/file”.

Writing down the command line for editing, like the following:

vi /this/file

is too much detail. Only specify the editor to use if the task at hand requires functionalities that are only available on a specific editor.

Troubleshooting sections#

Write the documentation as if every step succeeds.

Then, at the end, make a “Troubleshooting” section.

Organize the troubleshooting section as a list of symptom/resolution.

The following is an example of a troubleshooting section.

Troubleshooting#

Use the {trouble} directive to declare troubleshooting steps. For example,

Troubleshooting

SYMPTOM

This strange thing happens.

RESOLUTION

Maybe the camera is not inserted correctly. Remove and reconnect.

1

These meanings are explained in this document.