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.
Simply install your packages with
Install your packages with
What may be simple and second nature for you may be foreign and complex to another person. This is especially true when that person is learning the development ecosystem, or when something that’s usually straightforward fails for an unpredictable reason. Words like “simply” are judgmental.
Keep instructions short and to-the-point, without implying that it “should” be easy. You don’t need to overcompensate by pre-emptively answering every potential question or providing instructions “from scratch,” and that’s okay.
Furthermore, here’s a good collection of additional Words To Avoid in Educational Writing [CSS Tricks].
Specific words and phrases
For consistency, these words or phrases should always be written in the same way.
- Streetmix is one word, and the m is always lowercase.
- Code for America can be abbreviated CfA, after the full name has been mentioned at least once.
- GitHub always capitalizes the H.
- NEW INC is always in uppercase.
- open source is two words, 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 in the domain name.
Additional guidance for text used in the Streetmix interface may be found in our translation system.
We also use consistent typography based on industry standards.
- Use curly quotes instead of straight quotes.
- Use the ellipses character
…instead of three periods.
- Use the en dash and em dash characters when needed, instead of hyphens.
- There should be only one space after a period, instead of two.
Typography practices can differ between languages and cultures. For instance, in Chinese, periods are a small circle
。 instead of a dot; ellipses in written text are expressed with six dots (two ellipses characters side by side)
……, while in user interfaces (like menu items) the ellipses remain the single ellipses character
Translators should consider cultural and contextual differences in typography and make recommendations when they differ from expectations in English, and these differences 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, quotes and prime marks should both 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
- In Russian, the Cyrillic
мis more commonly used instead of
- In Arabic, the Arabic letter
مis more commonly used instead of
m. Measurements remain in the right-to-left content direction.