Why a style guide?
High quality documentation and tutorials create a positive first impression. You should make it your goal to highlight each new user-facing feature of Coyote with novel, distinctive content. You need to write in a way that ensures success for all skill levels. Documentation is much easier to read when it has a consistent voice and tone, terminology, and format.
This style guide offers advice and best practices that will promote the consistency that will help our readers be successful in using Coyote. Try to follow them unless there’s a good reason not to which which case please propose changes and improvements to this style guide as needed.
How to use this guide
This guide specifies style and format for contributors to use when developing tutorials for Coyote. Be warm and relaxed, crisp and clear, and ready to lend a hand to your readers. The following sections offer guidance on structure, style, and formatting. Additional resources for word choice and other topics can be found in the Microsoft Writing Guide.
Writing style basics
When writing tutorials, keep some basic guidelines in mind.
Keep it simple. Write short, simple sentences. Replace complex sentences with lists and tables.
Instead of: Raspbian has an extensive internal logic that allows it to adapt the processor speed according to the amount of computational load at any given moment - when the processor is under heavy load it clocks itself down to prevent overheating, which can lead to severe and permanent damage.
Use: To protect the processor from damage caused by overheating, Raspbian throttles the processor speed during heavy loads.
Be clear and concise—not hip or clever. Avoid idioms, colloquial expressions, and culture-specific references.
Instead of: Down the road, Coyote will grow.
Use: In the future, Coyote will grow.
Don’t say it’s easy. You’re writing for a variety of readers, with varying degrees of ability. Don’t assume you know what’s challenging or easy for someone. Avoid adverbs such as obviously, clearly, and apparently. Also avoid “filler” adverbs, such as very, really, and actually.
Use technical terms carefully. Your audience is varied and includes high school robotics enthusiasts and experienced hobbyists, so define terms in context if there’s a chance your audience won’t understand them. Use plain language whenever you can.
Grammar and usage
These basic guidelines will get you started creating clear and useful content.
Use present-tense verbs. Present-tense verbs indicate the action is happening now, like is and open. Avoid will, was, and verbs ending in –ed, which indicate that text isn’t in the present tense:
- Instead of: The predict function will return an array.
- Use: The predict function returns an array.
Be direct. Write simple statements of fact (called the indicative mood) or use direct commands (called imperative mood) for procedures and instructions:
- Instead of: Next, we will copy the file to the Raspberry Pi. OR You should copy the files to your Raspberry Pi.
- Use: Copy these files to your Raspberry Pi.
- Instead of: At the point where the process terminates, you should restart your computer.
- Use: After the process terminates, restart your computer.
Use active voice (where the subject performs the action). In passive voice, the receiver of the action is the subject:
- Active example: The predict function returns an array.
- Passive example: An array is returned by the predict function.
Speak to the reader. Use second person most of the time. Second person often uses the pronoun you, as though you’re speaking to the reader:
- Instead of: Next, we’ll create a directory for this tutorial anywhere on your computer.
- Use: Next, you’ll learn how to create a directory for this tutorial on your computer.
- Always capitalize proper nouns, such as Raspberry Pi.
- Lowercase everything except the first word in a sentence, UI label, phrase, heading, or title (including the titles of blogs, articles, and press releases).
- Don’t capitalize the spelled-out form of an acronym unless it’s a proper noun.
- Use title-style capitalization for product and service names, book and song titles, article titles in citations, names of blogs, and titles of people (Vice President, for example). This typically means capitalizing the first and last word of a title, and using lower case for articles, prepositions, and conjunctions.
- In programming languages, follow the traditional capitalization of keywords and other special terms.
- Don’t use all uppercase for emphasis.
- Don’t use all lowercase as a design choice.
- End all sentences with a period, even if they’re only two words.
- Include a colon at the end of a phrase that directly introduces a list.
Make sure you have the following materials before you begin this tutorial:
Laptop or desktop computer
Raspberry Pi 3
Raspberry Pi camera or USB webcam.
Include commas after items in a series, including before the second-to-last item, even when a conjunction (such as and) is used. Example: networks, storage, and virtual machines
Don’t use a slash (/) to indicate a choice or as a substitute for or.
Readers scan text to find what they need. To help them, write to support scanning, and organize content into discrete, scannable chunks.
- Use sentence-style capitalization and no end punctuation.
Example heading: Getting started with image classification on Raspberry Pi
- Use parallel construction (same verb form or grammatical construction) for headings at the same level.
This parallel example uses active verb phrases (all the same tense and mood):
- Activate your environment
- Download pre-trained model
- Compile and run the model
This example does not use parallel construction:
- Activating your environment (gerund phrase)
- Download pre-trained model (active verb phrase)
- How to compile and run the model (adverb paired with a to-infinitive clause)
Formatting text and code in instructions
Follow normal coding standards for code snippets and samples. When you reference elements or
parameters in a paragraph, format the item accordingly; for example:
When you want a reader to type code, use the following construction and format.
To install OpenBLAS, type:
sudo apt-get install -y libopenblas-dev
Code blocks are part of the markdown spec, but syntax highlighting isn’t. However, many renderers (including GitHub) support syntax highlighting.
codeand filenames. But nothing else. Avoid overuse of back-ticks.
- For blocks of code, start and end the code block with three back-ticks. and add the language name so the code is highlighted correctly.
Word choice preferences
Choose simple, precise words that you use in conversations.
- Use common contractions, such as that’s and don’t. They’re friendly and conversational. Learn more.
- Avoid words with more than one meaning. Learn more.
Refer to this list to understand which common terms to use and when. (List to be updated regularly.)
|Term||When to use|
|app, application, demo, program||Use application to refer to the “actuation code” that a user writes that runs on the target device. Do not use app, demo, or program to refer to this code.|
|folder, directory, subdirectory||Use directory to refer to the structure of the file system or to match the API.|
|root directory||Use root directory to refer to the directory or folder from which all other directories or folders branch.|