A style guide for content writers.
This is a style guide for writers. It is a work in progress, but represents the current state of our editorial standards.
The purpose of this style guide is to enforce editorial consistency. It is not to make every writer sound the same. If you think your style depends upon a particular use of the semicolon, then you don’t know what style is. The choice of colon vs semicolon isn't a choice between right and wrong, but simply the choices that we have made.
Ultimately, we care about good writing more than consistency. We're writing for the web, not an academic paper. We're also writing content that search engines can understand. Esoteric and quirky writing is fine for novels and can also work for authors with a loyal audience on the web. Our web writing, on the other hand, is characterized by simple, easily readable sentences that contain relevant information that helps the reader.
- US or British/Irish/Australian/NZ English
- Paragraph Length
- General Thoughts on Style
- Serial Comma
- Titles of Works
- Active voice
- Show, Don't Tell
- Punctuation Style
- Period / Full Stop
- General Style
- General Formatting
- Essential Writing Tools For The Web
US or British/Irish/Australian/NZ English
If in doubt, use the American spelling of a word.
We prefer short paragraphs. Like this one.
Don't waste space welcoming people to the blog or introducing people to the article. If the title does not begin with “what is”, you can leave out a definition of what it is. People will typically find the content by searching Google so if they search for “how to make sushi” and you start describing sushi like you're writing for Wikipedia, you're missing the point.
General Thoughts on Style
Here are a few thoughts on writing for your target audience (website readers)
- This isn’t a novel or poetry business. We publish “how to” and “nuts and bolts” articles. The key to this kind of writing is clarity. This doesn’t mean you can’t be clever and funny or grand and arrogant. But it is the content that matters. And that content needs to be clear to the reader. This is even more important than being interesting
- Don’t pad your work. I’ll repeat that: Do not pad your work. Avoid filler. We can tell when you are padding. And it takes a whole lot more work to insert random intensifiers that might give you ten more words than it does to come up with something new to say that will likely get you a hundred words without much effort. Forget this kind of stuff: “So let me tell you about the topic that I’ve already introduced and will introduce another six times before we get to the actual meat of the blog post”
- If you find the subject you are writing on boring, it will show. Find a way to get excited about the material you’re writing about. The ability to find the banal interesting is the key to good freelance writing. If you can’t write about the topic without putting us to sleep, don’t accept the work
- Beginners write like they speak. Professionals know this kind of writing leads to circuitous sentence structures that leave readers confused. You don’t have to write like Hemingway. But 3-line single sentences that need to be deciphered is the sure sign of a bad writer.
Lists should be formatted like this:
Note that the list ends with a period because that is where the sentence ends.
The serial (or Oxford) comma is the comma before the “and” (“or”) at the end of a series. For
example, Alfred Pennyworth, Jack, and Jill. Just use it.
Sometimes it is necessary for clarity: Jack Benny, Groucho Marx, and Burns and Allen. Clarity is never reduced by having it where it isn’t necessary. So why worry?
Titles of Works
Titles of major works of art are italicized. Generally: paintings, films, books, games, and so on.
In general, small works of art are not italicized but rather put inside quotation marks. So: poems, short stories, and so on. Musical compositions are italicized if they have a name but not if they have a purely descriptive title.
For example: Mozart wrote Eine kleine Nachtmusik and the Symphony No 25 in G Minor.
Use the active voice whenever possible.
Passive voice: “The book was read by the man”.
Active voice: “The man read the book”.
The second example is succinct, to-the-point, and is much easier to read.
Show, Don't Tell
Yes, even when writing for the web, it's important to show and not tell.
Telling: Bob was hungry. ❌
Showing: Bob hadn't eaten in days and his stomach rumbled. ✅
Telling: Adding milk to the recipe is not recommended. ❌
Showing: Milk tends to curdle because of the pan's high heat. ✅
Telling: Nobody likes using windows PCs for this task. ❌
Showing: Windows PCs are slower and harder to use for tasks like this so most people prefer to use Macs. ✅
Use punctuation to guide the reader.
If a word ends with the letter s, only add an apostrophe after it to make it possessive. When making a group possessive, only add an ‘s (or just ‘) to the final word if they represent a group.
Thus is would be: Key & Peele’s comedy. If the joint possessive is not a group, add an ‘s (or just ‘) to all subjects. Thus: Key’s and Peele’s cars.
Don’t use brackets except for editing notes. (They are also used in some programming languages where you will need to use them in sample code.)
Use the colon to introduce what comes after. It is most often used to introduce lists, but can be used for emphasis. Don’t use it to introduce a quote unless it is in a block. Do not capitalize the first word after a colon unless it would normally be capitalized. Don’t overuse the colon. Colons always go outside quotation marks when they end together.
Commas are the bane of writers. If there are too many commas in a sentence, it is either has too many thoughts for a single sentence, or is poorly structured. But don’t leave out necessary commas. It is better that a reader be able to figure out what you mean, even if it isn’t clear on first read.
Generally, add a comma before the conjunction if it links two clauses that could stand alone: I could have gone to Princeton, but instead I went to Yale. If there are two things the subject did, do not separate with a comma unless the subject is restated.
The dash is used in a couple of ways. First, it is used as a kind of super comma, allowing nonessential clauses to be set off. It can also be used to add a phrase to the end of a sentence. If a full sentence is added, use a semicolon, not a dash.
Use for exclamations. Don’t use them when writing for Fat Frog Media. Ever!
In general, avoid hyphens if you can. For example, email rather than e-mail.
Put sentence punctuation outside the parentheses. However, if you insert a complete sentence inside parentheses (Even short one) capitalize the parenthetical and end the sentence with the appropriate stop.
Period / Full Stop
Use it. Often. Short sentences are usually best, because they are clear.
Sentences should deliver one idea. So use the period. But don’t use periods in abbreviations.
Use US rather than U.S. Periods always go inside quotation marks when they end the sentence.
He said, “I’ll be right there.”
Use the question mark to end a sentence that is a direct question. How do you do this? Do not use it to end an indirect question. He asked how you do it. Question marks go inside quotation marks when they are part of the quoted material; otherwise, it should be outside. He asked, “When will you be here?”
Quotation marks are used to demarcate quoted material. Periods always go inside quotation marks; exclamation points and question marks depend upon whether they belong to the quoted material; and colons and semicolons always go outside the quotation marks.
If a quotation spans more than one paragraph, the ending quotation mark is skipped on all but the last paragraph. However, quotes like this should be presented as block quotes.
Use semicolons to connect complete sentences that are closely related. They don't see clean energy as a way to help our shared economy; they see it as a threat to their short term profits.
In general, don’t capitalize unless it is necessary.
Capitalize after a period, exclamation mark, and quotation mark. Do not capitalize after a dash or a semicolon. Do not capitalize after a colon unless what follows it is a full sentence.
Words that are not capitalized, should be capitalized when they start a sentence. The only exception to this is when a title is capitalized near the beginning. So a sentence starting with the word “cPanel” should be left like that instead of changing it to “CPanel.”
Titles and Headlines
We use The Chicago Manual of Style for title capitalization. Basically, it means you capitalize every important word in the title. Capitalize the first and last word no matter what. Capitalize all words with 4 or more characters. Capitalize words of less than 4 characters if they are nouns, verbs, or other “important” words. So capitalize “it” no matter what, but only capitalize “the” if it is at the beginning or end of the title.
But you don't need to worry about it. You can use this great tool. Enter your title and it will capitalize it correctly for you.
Here are some general thoughts on writing.
1. Omit needless words. A sentence should contain no unnecessary words, a paragraph no unnecessary sentences.
- “The reason why is that” could be shortened to: because.
- “Her story is a strange one” could be shortened to: Her story is strange.
2. You do not always need complete sentences — just complete ideas.
- The fewer words, the better.
- Concentrate on facts.
3. Avoid figures of speech, cliches colloquialisms and jargon.
- Remember we are (usually) writing for an international audience.
- Avoid Clichés
4. Concentrate on Nouns and Verbs, not adverbs and adjectives.
5. Avoid qualifiers like very, rather, little, pretty
6. Avoid these words and phrases: List of Plague Words Here <— Important
7. Strong Headlines / Titles are the most important part of web content creation/marketing.
Orwell’s Six Rules
And always remember George Orwell’s six rules:
- Never use a metaphor, simile, or other figure of speech which you are used to seeing in print.
- Never use a long word where a short one will do.
- If it is possible to cut a word out, always cut it out.
- Never use the passive where you can use the active.
- Never use a foreign phrase, a scientific word, or a jargon word if you can think of an everyday English equivalent.
- Break any of these rules sooner than say anything outright barbarous.
Titles and Bullet Lists
Headlines, subheads and bullet points should:
- Be useful to the reader,Provide him with a sense of urgency,
- Convey the idea that the main benefit is somehow unique; and
- Do all of the above in an ultra-specific way.
● How to Write a Magnetic Headline (in Under 15 Minutes)
Nothing is set in stone. But in general, structure your resource documents with the following list in mind. Don’t double up on header tags. For example, don’t go from an h2 tag “Resources” directly to an h3 tag “Online Resources.”
This almost always indicates that you haven’t structured your article correctly. You must have something to say about about resources generally. Remember: you are writing an article, not an outline.
In lists of resources, provide some discussion for all of them. Why did you include it? Why should the reader click on it rather than something else? There will be cases when no descriptions are necessary (eg, a list of download links to different versions of a language). In that case, provide any necessary discussion before the list.
Bottom line: descriptions are all or nothing.
Don’t capitalize things that aren’t titles. For example, if you are writing an article about breathing techniques, don’t capitalize “breathing techniques.” It’s a description, not a title. So you would capitalize the name of a programming language, but you would not capitalize “functional programming.” This may seem obvious, but it is a common error.
Text following a colon (or semi-colon) should not be capitalized; you are not starting a new sentence. See Punctuation Style above.
Never underline anything explicitly. Anchor links are fine. But don't, for example, use bold and underline for a heading. It looks good, but it is contrary to our style.
Resources often reference books.
If a book has a single author, list the full name of that author. For example, “Clarissa P Smartsalot.” If the book has two or three authors, list the last names of the authors. For example, “Smartsalot, Wellknownguy, and Actuallywroteit.” If the book has more than three authors, list the first author's last name followed by “et al.” For example, “Smartslot, et al.”
Book titles are always italicized.
- 24/7 – Use 24/7 and not 24×7 or 24-7.
- 3D – Not 3-D.
- Abbreviations – Use a or an based upon the sound of the abbreviation, not what it stands for.
- Acronyms – Add an “s” to make acronyms plural. Don't use periods in acronyms; US and not
- Ajax – Not AJAX.
- Ampersand – Avoid using “&” when you can use “and.” The Exception is in Titles.
- And/Or – Never use this construction.
- Antivirus – Not anti-virus.
- Apostrophes – Do not add an s to make a word or name ending in s possessive.
- Backend – Use “backend” and not “back end.”
- Backup/Back-up – Use “backup” for the noun and “back-up” for the verb.
- Bitcoin – do not capitalize when used as current. When talking about the protocol, capitalize.
- Boolean – always capitalized.
- BTC – BTC is the equivalent of USD for bitcoins.
- Capitalization – Names that start with a lowercase letter should still be capitalized if they start a sentence.
- CMS – Content Management System. Use “CMSs” for plural. WordPress is the best-known CMS
- Codebase – not code-base or code base.
- Comma – Use the serial comma: “this, this, and that.”
- Command-line – not commandline and not command line.
- Data – Data is plural, singular is acceptable.
- Datacenter – Not “data center.”
- DDoS – Not “DDOS.”
- Ebook – Use ebook, not eBook or e-book.
- Ecommerce – Use ecommerce, not eCommerce or e-commerce. In titles, use eCommerce.
- E-learning – Use e-learning, not eLearning or the confusing elearning.
- Em-dash – Put spaces before and after m-dashes.
- Email – Not “e-mail.” The plural of email is email — not emails. Also, one does not send an email just as one does not send a mail. One might have sent a lot of email, each one of them is an email message.
- Embedded – Not “embeded.” This is a common misspelling.
- Fail-safe – Not failsafe or “fail safe.” Confusing, isn’t it?
- Fair Use – always capitalize.
- Filename – When used when discussing technical terms or technical issues, use it as one word and not as “file
- name” or “file-name.”
- Focus – Plural is focuses unless dealing with explicit mathematical material, in which case it is foci.
- Front-end – Use “front-end” and not “front end” or “frontend.”
- Full-time – not fulltime.
- Gbps – Always capitalize the “G.”
- Google – Do not capitalize google when used as a verb.
- Gray – Not grey.
- Hard core – Always use as two words as “hardcore” is associated with pornography.
- Although we do discuss pornography if required, it is hard to imagine a time when
- we would discuss it to the extent that we would need the word “hardcore.”
- Healthcare – Not health care.
- Help desk – Not help-desk or helpdesk.
- HTML – HyperText Markup Language.
- Hyphens – Avoid hyphens in words like e-commerce and e-mail.
- Internet – Not capitalized. But no major problem if it is. The key is consistency. If it’s capitalized in one place it should be capitalized everywhere.
- Knowledgebase – Always use this as a lowercase word. Many websites refer to it as “Knowledgebase” because it is their one thing and they consider it a name. But from our
- perspective, they just have a knowledgebase, not the Knowledgebase. And it is one word, not two. Think of it like database.
- Lackluster – Not “lack luster.”
- Lead – The past tense of “lead” is “led” and not “lead.”
- Lightweight – Write as a single word.
- Long-term – Not longterm.
- Mbps – Always capitalize the “M.”
- Metadata – Not meta-data.
- Motherlode – Not mother lode and certainly not mother load.
- Neuter – Consider the sentence fragment, “Once a customer selects a plan, [the customer] can select the option…” The standard solution to this problem is to replace [the customer] with “he or she” or to alternate “he” and “she” throughout the document or to simply use the masculine “he.” We use the grammatically questionable, “Once a customer selects a plan, they can select the option…” If this bothers you, rewrite the sentence so that there is no problem. For example, the sentence fragment could be written, “Once customers select a plan, they can select the option…”
- New York Times – It is The New York Times and is always italicized. Never use the construct “the The New York Times.”
- Nonprofit – Not non-profit.
- Numbers – When at the start of a sentence, spell them out as words. When a number is followed by a unit, provide a space. So 10 GB and not 10GB.
- Okay – Not OK or Ok.
- Open-source – lowercase with hyphen.
- Or – The word “or” is not exclusive. So it is never correct to use the construction “and/or.” If you feel the need to use “and/or,” simply use “or.”
- Part-time – not parttime.
- PayPal – Not Paypal or paypal.
- PDF – Not pdf. When used to describe a link, put into parentheses outside the link text.
- Percent – Use the percentage sign (%) with numbers. For example, “They offer a 99.9% uptime guarantee.” But use the word when it is not attached to a number. For example, “A large percent of their hosting plans suck.” You should never start a sentence with a number, so if you start a sentence with a percent number, you will not use the percentage sign. For example, “Ten percent of all people love grammar rules”
- Formulas – Not formulae.
- Respectively – This word is almost never justified.
- Scare Quotes - Don't use “supposedly” with scare quotes. It's not: “she's supposedly ‘good’ at baseball.” It is: “she's supposedly good at baseball.” Of course, there is one time you could use this construct, but it would be highly stylized and you would never use it in the kind of stuff we do.
- Setup – as a noun, use setup and as a verb use set-up.
- Semicolons – don't capitalize after semicolons.
- Smartphone – not “smart phone” unless the phone you are talking about has gained consciousness.
- Solutions – avoid. Instead uses words like “services.”
- Story – when used to describe levels of buildings, use “stories” for the plural. “Storeys” is common, but it has fallen out of favor and usually confuses readers.
- Style sheet – not “stylesheet.”
- Subdomain - not “sub domain” or “sub-domain.”
- Supposedly – If something is “supposedly X” don't put quotes around “X.” That's implied by “supposedly.” See “Scare Quotes.”
- Takedown – as a noun or adjective, takedown; as a verb, take down.
- Trojan – Always capitalize because it is a name. A Trojan horse was installed.
- That – If it is a person, use “who.” Example: “Those that answer incorrectly get a quick refresher on the topic” should be “Those who answer incorrectly get a quick refresher on the topic.”
- Unsecure – When discussing computer security, use unsecure. It makes no sense, but insecure is not used in this context.
- Web – when used as shorthand for the World Wide Web, do not capitalize
- Web host – Not webhost (or webhosting).
- Webpage – Not web page
- Website – Not web site
- Web server – Not webserver (yet)
- World Wide Web – Should be capitalized. Contrast for Web
- WiFi – Not Wi-Fi.
- WordPress – not WordPress