build details

# 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.