diff --git a/book/duckumentation/30_style_guide/76_style_guide.md b/book/duckumentation/30_style_guide/76_style_guide.md index 8697659..c078559 100644 --- a/book/duckumentation/30_style_guide/76_style_guide.md +++ b/book/duckumentation/30_style_guide/76_style_guide.md @@ -6,8 +6,12 @@ This chapter describes the conventions for writing the technical documentation. ## Organization -The documentation is divided into books, parts (labeled 'part:') and units (with no CSS prefix). To create a new part, put \{#unit:name status=STATUS} after the header, like so: -> \#\# Safety {part:safety status=ready} +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 @@ -55,22 +59,22 @@ The following holds for all technical writing. - The English version of the documentation is written in American English. Please note that your spell checker might be set to British English. -Bad: behaviour +> Bad: behaviour -Better: behavior +> Better: behavior -Bad: localisation +> Bad: localisation -Better: localization +> Better: 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. -> Bad: "Edit the ~/.ssh/config file using vi." +Bad: "Edit the ~/.ssh/config file using vi." -> Better: "Edit the `~/.ssh/config` file using `vi`." +Better: "Edit the `~/.ssh/config` file using `vi`." - Ctrl-C, `ssh` etc. are not verbs. @@ -105,23 +109,48 @@ If the command is supposed to be run on both, omit the hostname: $ cd ~/duckietown -For a container: +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
- container $ echo container
+This:
-For a container on a Duckiebot:
+> duckiebot-container $ command
- duckiebot-container $ echo container
-
-For a container on the laptop:
+will become:
- laptop-container $ echo container
+ duckiebot-container $ command
-For a container on a traffic light:
+This:
+
+> laptop-container $ command
+
+will become:
+
+ laptop-container $ command
+
+
+
+
## Frequently misspelled words
- "Duckiebot" is always capitalized.
diff --git a/resources b/resources
index 1cbccfe..13a87f4 160000
--- a/resources
+++ b/resources
@@ -1 +1 @@
-Subproject commit 1cbccfe0e67e58913f45f3bde5ea8a9b14cb9c20
+Subproject commit 13a87f43fe60cfe19f428790ca419621c64002ec