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.

Do make use of the necessary complexity to convey your message, but do not hide behind overly complex language to disguise flaws. Remember Einstein’s quote:

You don’t really understand something unless you can explain it to your grandmother.

Examples

provide → give

query → question

in order to → to

utilize → use

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.