Over time, different publishing communities have written standards for the style and grammar they prefer in their publications. These standards are called style guides. Generally, Crowd Supply’s documentation uses the standards described in the Associated Press’s (AP) style guide. If you’re already familiar with another style (MLA, Chicago, etc.), it’s fine to use that. The most important thing is that you choose and adhere to some style standard.
If a question about syntactical, grammatical, or lexical practice comes up, refer to the AP guide first. If you don’t have a copy of (or online subscription to) the AP guide, you can almost always find an answer to a specific question by searching the web directly (e.g., search on “AP style capitalization”). If you can’t find an answer, please ask Fred or anyone else at Crowd Supply and we’ll help you figure it out.
That said, please don’t get too hung up on using correct style. We’d rather have you submit good information that doesn’t conform to a guide than no information at all. We are always happy to help you with the prose, and promise not to judge or use a red pen!
In general, try to write simple, straightforward prose. We prefer short, single-clause sentences and brief three-to-five sentence paragraphs. Try to choose vocabulary that is straightforward and precise. Avoid creating new terms, using obscure terms or, in particular, using a lot of jargon. For example, instead of leveraging “leverage,” use “use”.
Generally, you can assume that your audience is college-educated and has a good grasp of English (the vast majority of Crowd Supply backers are from North America). Nonetheless, try to avoid an excess of colloquial, technical, or metaphorical language.
In all cases, we prefer clear, concise communication over stilted, formal language. Don’t feel like you have to write copy that “sounds like” technical writing or marketing. Use your own natural voice and let your personality shine through.
Unlike AP, in lists, we prefer the Oxford or terminal comma. E.g., “Superoven is available in small, medium, and jumbo.”
Contractions are perfectly acceptable, as long as your prose doesn’t get too slangy and informal. Make certain you are using apostrophes correctly. If you need to get something across firmly, consider NOT using a contraction.
Only proper nouns should be capitalized in body text. In general, strive to be as strict as possible in applying this rule. Avoid using capitals for emphasis or to denote “specialness”. It makes your prose read like a bad fantasy novel.
Avoid starting sentences with words that aren’t capitalized, like code samples or brand/personal names that officially aren’t capitalized.
Generally, we adhere to AP style for titles.
Dashes (the en dash “–” and the em dash “—”) are used to separate parenthetical material. They should be used sparingly since readers will de-emphasize material contained in dashes.
Usage Example: Our video board – based on an entirely open design – provides connections for every known standard.
Use dashes cautiously and consider whether commas or parentheses would work just as well. We always emphasize short, succinct sentences.
It’s okay to use first and second person pronouns, especially if it lets you avoid a passive construction. Specifically, always use “we” to refer to yourself (the creator) and/or Crowd Supply. Use “you” to refer to the backer or user. For example, “We built the Gear Gate for you, the avid cyclist.”
That said, in general, try to write simple, imperative sentences that avoid the use of pronouns altogether. Say “Snap Shades come in 12 colors” rather than “You can choose from 12 different colors of Snap Shades.”
As much as possible, avoid using gendered pronouns (“he,” “she”, etc.). Either recast the sentence so the pronoun is not needed or, less preferably, use “they” instead. If you absolutely can’t get around using a gendered pronoun, pick one and stick to it. Which one you choose is up to you. One common convention is to use the pronoun of the author’s gender, but if you prefer to always default to “he” or “she”, that’s fine too. Just be consistent.
Exempli gratia (e.g.) and id est ( i.e.): these should always have periods and are always followed by a comma when used in a sentence. “E.g.” means “for example”, while “i.e.” means “in other words.”
Acronyms are pluralized by simply adding “s”, e.g., PCs, OSs. No apostrophe should be used unless the acronym is used as a possessive.
On first use on a given page, the complete term should be used, with the abbreviation or acronym in parentheses. E.g., “Free Software Foundation (FSF).” The exception is common, non-specialized acronyms like AKA or ASAP. Note that acronyms other than “i.e.” and “e.g.” are capitalized.
Other than “e.g.” and “i.e.” (as discussed above), acronyms do not take periods, PC not P.C.
When writing lists, keep the following in mind:
Use bullets when the items being listed are independent of each other and the order of presentation is not important.
Use numbers for steps that have to happen in order or if you have mentioned the list in introductory text. For example, if you wrote “There are three available packages for the Librem laptop:…” you would number each package in the subsequent list.
In all lists, if an item is a complete sentence, it should end with a period. Otherwise, we prefer no terminal punctuation for list items. Each item in a list should start with a capital.
Write out numbers in body text and titles from one to ten. From 11 on, use numerals. It’s okay to use numerals in specification lists, tables, etc.
Separate quantities and units with a single space. For example, write 1.2 GHz instead of 1.2GHz. The exception is when using the single quotation mark and double quotation mark to indicate feet and inches, respectively (e.g., 6’ 9” to mean six feet and nine inches).
Contact us at email@example.com to see how we can help.
Intro & Overview
Before Your Campaign Starts
During Your Campaign
After Your Campaign Concludes
Please send us your feedback on this Guide: firstname.lastname@example.org.