build details

Show: section status errors & todos local changes recent changes last change in-page changes feedback controls

Style guide

Modified 2018-06-02 by Andrea Censi

This chapter describes the conventions for writing the technical documentation.

Organization

Modified 2018-10-13 by Andrea Censi

The documentation is divided into books, parts (labeled ‘part:’) and units (with no CSS prefix).

To create a new part, put {#part:name status=STATUS} after the header, like so:

## Safety {#part:safety status=ready}

General guidelines for technical writing

Modified 2018-06-02 by Andrea Censi

The following holds for all technical writing.

  • The documentation is written in correct English.

  • Do not say “should” when you mean “must”. “Must” and “should” have precise meanings and they are not interchangeable. These meanings are explained in this document.

  • “Please” is unnecessary in technical documentation.

“Please remove the SD card.”

“Remove the SD card”.

  • Do not use colloquialisms or abbreviations.
Bad: “The pwd is ubuntu.”
Better: “The password is ubuntu.”

“To create a ROS pkg…”

“To create a ROS package…”

  • Python is capitalized when used as a name.

“If you are using python…”

“If you are using Python…”

  • 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

Modified 2018-10-13 by Andrea Censi

  • The English version of the documentation is written in American English. Please note that your spell checker might be set to British English.

behaviour

behavior

localisation

localization

  • It’s ok to use “it’s” instead of “it is”, “can’t” instead of “cannot”, etc.

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

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

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

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

Ctrl-C from the command line”.

“Use Ctrl-C from the command line”.

  • Subtle humor and puns about duckies are encouraged.

Writing command lines

Modified 2018-10-13 by Andrea Censi

Use either “laptop” or “duckiebot” (not capitalized, as a hostname) as the prefix for the command line.

For example, for a command that is supposed to run on the laptop, use:

laptop $ cd ~/duckietown

It will become:

laptop $ cd ~/duckietown

For a command that must run on the Duckiebot, use:

duckiebot $ cd ~/duckietown

It will become:

duckiebot $ cd ~/duckietown

If the command is supposed to be run on both, omit the hostname:

$ cd ~/duckietown

Other rules:

  • For a container use container.
  • For a container on a Duckiebot use duckiebot-container.
  • For a container on the laptop use laptop-container.

This:

container $ command

will become:

container $ command

This:

duckiebot-container $ command

will become:

duckiebot-container $ command

This:

laptop-container $ command

will become:

laptop-container $ command

Frequently misspelled words

Modified 2018-06-02 by Andrea Censi

  • “Duckiebot” is always capitalized.

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

  • These are other words frequently misspelled:

    5 GHz WiFi

Other conventions

Modified 2018-06-02 by Andrea Censi

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.

(If people need to be told how to edit a file, Duckietown is too advanced for them.)

Troubleshooting sections

Modified 2018-06-02 by Andrea Censi

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

Modified 2018-10-13 by Andrea Censi

This strange thing happens.

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

This other strange thing happens.

Maybe the plumbus is not working correctly. Try reformatting the plumbus.