Over time, different publishing communities have established and documented 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 your Crowd Supply project manager 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 decent grasp of English. However, for a typical Crowd Supply campaign, almost half of your backers will come from outside the US. Consequently, try to avoid an excess of colloquial or metaphorical language (see below TODO link).
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.
In order to communicate clearly with backers from dispirate cultures and backgrounds, we strongly suggest you avoid using emojis and memes in your campaign copy. Similarly, avoid using metaphorical language or "in-group" vernacular. For example, "the boot" in the US means getting fired, but "the boot" in the UK is the trunk of a car. To avoid alienating, confusing, (or even annoying!) international, multi-cultural backers, it’s best to stick to clear, simple, straightforward language.
Note that you cannot use emojis in Headings as they will not be rendered correctly by our Markdown engine.
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.
Make sure links use descriptive text rather than "click here." For example, "Visit Crowd Supply’s home page" is preferable to "Click here to visit Crowd Supply’s home page".
Note that we do not support links opening in new windows or tabs. It’s counter to how web browsers work and it annoys users, especially the more technically oriented users that make up Crowd Supply’s audience.
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 Amp Master Pro for you, the avid audio engineer.”
That said, in general, try to write simple, imperative sentences that avoid the use of pronouns altogether. Write “Glowy Lights come in 12 colors” rather than “You can choose from 12 different colors of Glowy Lights.”
Avoid using gendered pronouns (“he,” “she”, etc.). Either recast the sentence so the pronoun is not needed or use “them/they” instead.
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. An 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). Another exception to this is when "k" is used to denote thousands, as in "8k" for "8,000". We prefer not using "k" for thousands (in agreement with AP styleguides), but if it must be used there should be no space between the number and the "k".
Question not answered here? Contact us to see how we can help.
Getting Started
Before Your Campaign Launches
During Your Campaign
After Your Campaign Concludes