Streetmix is a tool for communication and collaboration, so the way we write and present content should facilitate those goals. This is a reference that will continue to grow as needed. When you run into a situation that isn’t covered here, refer to the very excellent 18F Content Guide.
- Use plain language and simple sentence structure.
- Be funny or friendly, but:
- Choose clarity over cleverness.
- Avoid technical or industry-specific jargon.
- Content isn’t frozen in time. Always be refining. As we learn, we change and adapt.
When writing standalone text such as titles, labels, or headings, use sentence case. With sentence case, capitalize the first letter of a phrase, but leave all other words in lowercase, unless they would normally require capitalization, such as proper nouns.
Avoid title case (Where Each Word Is Capitalized, Like This), or uppercase (SUCH AS THIS). These approaches are harder to read than sentence case.
People have different levels of expertise¶
Avoid using the words “simply” or “just” when writing instructions.
Don’t write this:
Simply install your packages by typing
What may be second nature for you may be foreign to another person. These instructions are missing additional information for a less experienced developer: Where would you type this? What is
npm? What happens if the command doesn’t work?
At the same time, instructions should be short and to-the-point, so we would not strive to add context to every instruction. We should state the instruction but not create a value judgment about its relative ease.
Instead, write this:
Install your packages by typing
Those are not the only two words to avoid. For more, read Words To Avoid in Educational Writing from CSS Tricks.
Specific words and phrases¶
- Streetmix is one word, and the middle m is always lowercase.
- Code for America can be abbreviated CfA, after the full name has been mentioned at least once.
- GitHub always capitalizes its middle H.
- NEW INC is always in uppercase.
- open source is never hyphenated.
- email is one word. Do not hyphenate or capitalize (unless at the start of a sentence).
- The URL to our website is https://streetmix.net/, which uses the more secure https protocol, and does not have the
www.prefix before the domain name.
Additional guidance for text used in the Streetmix interface that are not likely to occur elsewhere in our written content will be provided in our translation system.
Consistent typography, based on standard practices in the typography industry, is another aspect of how we pay close attention to detail within the Streetmix project.
- Use curly quotes instead of straight quotes.
- Use the ellipses character
…rather than a series of periods.
- Use the en dash and em dash characters appropriately.
- There’s only one space after a period, never two.
Typography practices may differ between languages and cultures. For instance, in Chinese, periods use a small circle
。 instead of a small dot, and ellipses are written as six dots (two ellipses characters side by side)
……, but in computer UI, the ellipses in menu items remain the single ellipses character. When working on translations of Streetmix, cultural and contextual differences in typography should be considered by translators and should be consistent throughout the application.
Units of measurement¶
By default, use the metric system. We support the imperial system only in the United States for users who are more familiar with it.
When writing distances in the imperial system, feet and inches should use the prime
′ and double prime
″ marks respectively, instead of the straight quotes
". When processing input, both quote and prime marks should be accepted as valid.
For distance measurements, include a space between the quantity and unit. For example, fifty meters should be expressed as
50 m, not