This style guide is an edited version of the one given by Five Simple Steps to its authors. It therefore assumes that some formal publishing infrastructure and processes are in place.
Writing your book
Writing books can be daunting. There may be times during the process when you’ll question your reasons for doing so. This guide will assuage your fear a little, at least, though it won’t tell you how to write your book or what to write. Your writing shouldn’t conform to a bland, corporate template: you need to be yourself. The guide is here to help you do that.
Maybe you’re already an experienced online writer. If so, you possess a particular skill that takes time and effort to do well: keep things simple and clear; break up text into brief chunks; lots of headings for the reader to latch on to; a straightforward, human, approachable, even casual tone of voice, as if you’re talking to the reader, face to face.
Now you’re writing a book. Your writing will benefit from the techniques you practise online, but a book is different and it requires a different approach. Books, unlike webpages, take time to write and read. Think length and breadth and depth. You have more time. You can develop your ideas more fully, explore more of their consequences to greater depth, extend them with more varied examples, convey them with more eloquence, more style. Why not delay reaching your conclusion, if the intervening text is apposite, rich with value and helps to flesh out the skeleton of your ideas? You must still reach a conclusion, of course, but you are at greater liberty to digress in tangential and interesting ways.
Write the book that you want to read, the one that does justice to your area of expertise. There’s no need to be exhaustive, though often readers expect it. You’ll probably have to cover some basic ground to satisfy these assumptions, but assume that your readers are intelligent and already know something of your subject.
Tone of voice
Write in a confident, authoritative tone to allow the reader to have faith in your expertise. You know your stuff, so let your style reflect that. Don’t falter on things being correct or not – make it clear to any reader that you’re right – just do your research properly and make damn sure you are. Unless, however, something really is unclear to everyone (maybe it’s not widely researched or it’s very new or incomplete), but it still needs to be mentioned in the book.
At the same time as being authoritative, don’t be afraid to introduce a little informality and inject some fun into your writing. Be approachable to the reader, make them comfortable and avoid condescension. You need to guide the reader like an old friend, not a stuffy teacher. Don’t go overboard, of course, and let the jokiness get in the way of the information; strike a balance between authority and levity.
Use the active voice as much as possible. Put simply, in the active voice the subject of a sentence does an action to the object:
Geeks (subject) love (action) shiny new gadgets (object)
In the passive voice, the subject has something done to them by the object:
Shiny new gadgets (subject) are loved (action) by geeks (object).
Using the active voice can make your writing more immediate, direct and succinct. Remember, though, that the passive voice is also expressive, particularly when you want to make the object more important than the subject in a sentence. Don’t worry too much about it as your editor will help you. For more details, search online for active and passive voice.
Being yourself and addressing the reader
Use I, me, mine and my when you really are talking about something that you do, or is based on your own experience.
My preference for creating transparent PNGs is Fireworks rather than Photoshop, because I find it easier.
Chances are, you’ll often need to address the reader directly, particularly if your book contains instructions or examples to follow. Using you, your and yours can help draw in the reader and makes the subject more personal.
Before designing your web app, make sure you’re aware of the current market.
When you’re asking the reader to follow specific steps, though, it’s better to use we, us, our and ours. This lets the reader feel like you’re both working through something together as peers.
Now that’s done, we’ll take a closer look at our paragraph styles.
What to avoid
Don’t use Wikipedia as your only source of reference. Wikipedia is convenient but you shouldn’t rely on it exclusively. Look further and deeper when researching: even Wikipedia encourages further reading with its “See also”, references and external links sections.
Our industry is already full of jargon and buzzwords, so don’t add to it unnecessarily. Even though many readers will understand a lot of such vocabulary, and some subjects make technical terms unavoidable, be sure to explain concepts as clearly as you can, perhaps with an appropriate and insightful analogy. It’s rare for a new coinage to so succinctly capture an idea that it becomes widely accepted (responsive web design, for example); be wary of promoting that new favourite term or phrase you’ve come up with.
Write what you mean and make sure what you write means something. Vagueness, euphemism, circumlocution and clichés are unhelpful to readers, who seek precision and practical guidance from books. And time will tell, but most references to contemporary popular culture will date very, very quickly.
Punctuation, grammar, style and spelling
This guide generally follows the Oxford Guide to Style in matters of punctuation, grammar, spelling and some typographical niceties, but it happily emphasises the guide when making decisions. There’s no need for you to consult the OGS and this guide ignores some of its pronouncements, following other guidelines or common usage as appropriate. More important are sense, clarity and consistency.
Although your copy editor and proofreader should check all matters relating to spelling and punctuation – so you don’t have to – here are some common areas of uncertainty that you might want to know about as you write.
Punctuation
- colon
Use between two sentences, or parts of sentences, where the first introduces a proposition that is resolved by the second:
We can’t go on designing like this: webpages aren’t photos.
The colon points forward: from a premise to a conclusion, from a cause to an effect, from an introduction to a main point, from a general statement to an example.
A colon can introduce a quotation more emphatically than a comma:
As Tim Berners-Lee said: “This web thing’s got legs.”
It should also precede a list:
The following items are important: spelling, punctuation and grammar.
And a colon comes after a work’s title to introduce the subtitle: 2001: A Space Odyssey. Don’t assume that colons and semicolons are interchangeable: they’re not (see semicolon).
- comma
Commas help readers make sense of what’s being said in several ways. They can provide a short breathing space in long sentences and clarify meaning. Fully explaining the diverse ways commas can be used would take up far too much space and require too many examples, so this guide’s advice is to rely on your copy editor for guidance.
- dashes
As a clause separator, use an en dash – with spaces:
Use one word wherever possible – though there are exceptions.
Use them only to emphasise strongly the content that comes after one dash or between two – commas (or sometimes parentheses) are often better and less likely to interrupt the flow of text.
Between numeric values, including dates, use an en dash – without spaces: from 150–200 pixels wide.
- hyphens
Use one word wherever possible – though there are many exceptions. New ideas and concepts often begin life as two words, then become hyphenated, before finally becoming one word: shortlist, smartphone, website.
Most compound adjectives don’t require hyphens where the meaning is clear: web services industry, little black dress. Hyphens should, however, be used to form short compound adjectives: web-enabled devices, three-day week. Hyphens can also clear up the sense: a gradient-abusing design isn’t the same as a gradient abusing design.
Hyphens should not be used after adverbs ending in -ly: a hotly discussed topic, that badly drawn wireframe. They are needed with short and common adverbs: our much-loved interface, the well-known CSS hack. Though also note that the construction the CSS hack is well known doesn’t require a hyphen.
Prefixes such as anti, co, macro, mega, micro, mini, multi, over, pre, re, super and under rarely need hyphens but, as usual (this is British English, remember), there are exceptions. Your copy editor will set you right.
- lists
List items, except when very short (four or five words), usually begin with a capital letter and have a full stop at the end.
- Oxford or serial comma
A comma placed before the final “and” in lists. In straightforward lists, you can do without it: fish, chips and mushy peas, not fish, chips, and mushy peas. There are times, however, when the judicious use of a comma clarifies the sense:
This book is dedicated to my parents, Bill Gates and Steve Jobs.
- quotations
All extracts quoted must be in the exact words of the original. Use double quotes at the start and end of a quoted section, with single quotes for quoted words within that section. Full stops and commas should be placed inside the quotes for a complete quoted sentence:
Sherlock Holmes never said, “Elementary, my dear Watson.”
Otherwise the full stop comes outside:
Dr Watson described Holmes as “a pipe-smoking, violin-scratching, cocaine-addled misanthrope”.
When beginning a quotation with a sentence fragment that is followed by a full sentence, punctuate according to the final part of the quotation:
The developer said the code was “absolutely awful. But it was the best available at the time.”
- scare quotes
Avoid using ‘scare quotes’ around words you’re emphasising or trying to distinguish from the surrounding text. If a word really needs emphasis or has to be separated from what’s around it, use italics. If you’re trying to highlight the particular use of words in a particular context, then find another way to draw attention to that, or find a source for your quotation (which is what you’re suggesting the words are by using scare quotes anyway). In all other cases, you don’t need scare quotes.
- semicolon
Use between two or more main clauses that are closely related and could have been joined by a conjunction, or treated as separate sentences:
The markup is very carefully structured; the CSS shows no structure at all.
In that example, the semicolon also imparts greater emphasis to the clause that follows it. In a sentence already subdivided by commas, use a semicolon to indicate a stronger division:
She made her way to the office, enduring an uncomfortable journey, and decided to read up on jQuery online; it was then she remembered she’d left the TV on.
In a list, within the main body of text, where the items contain commas, use a semicolon to distinguish between the items:
In the next chapter we’ll cover: browsers and their support of border-image, background-size and box-shadow properties; new HTML5 elements section, article and aside; and how webfonts are the new black.
- title case
By which is meant Writing Headings with Capital Letters at the Beginning of Important Words. This is very common in US English. British English prefers to leave title case to titles, not headings, where only the first letter is capitalised (with exceptions for proper nouns).
Grammar
- collective nouns
Not things like a murder of crows or a mob of kangaroos (those are more properly called terms of venery, some dating back to medieval times. No, not the kangaroos), but nouns like committee, family and team. Pedants will tell you that these should always take singular verbs and pronouns – there’s one committee, one team – but usage is rather more fluid. When thought of as a single unit, use the singular forms:
The design team was grateful to get sign-off on its choice of colour scheme.
But use a plural verb or pronoun when thought of as a collection of individuals:
The development team were up all night writing code for their apps.
- he/she | him/her | his/hers and other gendered language
When referring to a general third person (the good designer selects her tools carefully) it has become common in web writing to either prefer the feminine (thereby somehow subverting the once correct but always sexist use of the masculine) or to alternate between a male and female singular. The main purpose of these approaches is to avoid awkward combinations:
Ask the user to enter his or her email address.
But the former technique is still exclusion and the latter draws unnecessary attention to itself. There’s nothing wrong with using the third person plural forms they/them/their in the singular context, but on many occasions it’s possible to make the subject of the sentence plural. So, Once a designer sees the benefits of CSS, they never look back is acceptable, but Once designers see the benefits of CSS, they never look back is better.
Gendered forms of nouns, such as actress, artiste, authoress, comedienne, male nurse, manageress and so on, are obsolete terms from a time when professions were largely the preserve of one sex. There’s no need to differentiate between the sexes, unless in the title of an award, like the Oscar for best actress (even some of those now use male and female as qualifiers) or to describe animals. Words borrowed from other, more heavily gendered languages, or historical terms, might make it through, depending on context.
- its/it’s
Its is equivalent to his or hers:
IE6 is a victim of its own longevity.
It’s is a shortened form of either it is or it has:
It’s only a browser; It’s been a long night of coding.
- of
Do not use outside of (outside) or off of (off) and other similar forms. Of for have (for instance, would have or would’ve, not would of) is inexcusable – at least for your copy editor.
- split infinitives
Avoid them if you can do so elegantly, but it doesn’t matter if you don’t. Feel free to boldly go.
- who, whom
Who says whom anymore? If in doubt, it’s better to use who and leave it to your copy editor.
But you can ask yourself how the clause beginning with who or whom would read in the form of a sentence giving he, she, they, him, her or them instead. If the who/whom person becomes he/she/they, then who is right; if it turns into him/her/them, then it should be whom:
At the conference, John followed Jane, who he thought was great (John thought she was great = who);
Schubert was influenced by the work of Beethoven, whom he admired (Schubert admired him = whom).
- whose/who’s
Who’s is the short form of who is or who has. Whose denotes possession: The designer whose CSS is full of hacks will come a cropper.
Style
- and/or
While this is a convenient construction in speech, in writing it’s rather inelegant. Rewrite it simply as or, or spell things out completely: this or that or both. Or rewrite the sentence to avoid it altogether.
- compare to, compare with
Comparing x to y assumes x is like y in some way; comparing x with y makes a comparison between them. Chances are you’ll be comparing one thing with another to weigh them both up, unless you want to specifically liken one thing to the other.
- dates
Precise dates should be shown in the order day, month, year, without internal punctuation: 25 May 2012. A named day preceding a date is separated by a comma: Friday, 25 May 2012. There is no comma between a month and year: The book was published in November 2009. In running text, month names should appear in full.
To include the social, cultural and political conditions of a particular decade, use the word with an initial capital: the Eighties; for the simple timespan, use numbers and include the century: the 1980s. Don’t replace the century with an apostrophe: the 1980s and ’90s should be the 1980s and 1990s.
In running text use words for centuries: the nineteenth century; the first century BCE. In short measures, numerals and abbreviations can be used: 14th cent.; 18th c. In adjectives, use a hyphen: a twentieth-century opera; 15th-c. manuscript.
- due to, owing to
Due to is equivalent to caused by; owing to is equivalent to because of.
The user’s poor experience was due to lack of proper testing.
The user’s experience sucked owing to a lack of proper testing.
- e.g./i.e./etc.
Remove these from your main text. For e.g. use for example, say, such as, an example of this is, like, for instance, as appropriate. Sometimes, an example can be given without being introduced as such. For i.e. use that is. For etc. use and so on or and the rest. The abbreviations are permissible in quotations and when text is set in narrow measure (in a table, for example).
- emphasis
Use italics to add emphasis, bold to add strong emphasis. But use them sparingly and only when it’s essential: every time there’s a change to the typeface, the reader is interrupted.
- end-users
There are no start-users or middle-users, so don’t write end-users when you really just mean users. Or maybe you mean visitors or customers or clients. They might even be people.
- farther, further
Use farther for physical distances, further for everything else: His argument went further; His tractor went farther.
- if, whether
If introduces a single condition; whether opens up alternative possibilities, sometimes with or not either expressed or implied.
If you don’t know which to way to turn, read this carefully.
Your book must be written whether it takes two months or two years.
- lists
Online, presenting information in bulleted lists can be very effective, particularly if each item is a one- or two-sentence point within an argument. In extended prose, however, lists interrupt the flow of text, so consider presenting longer list items within your narrative as paragraphs, perhaps beneath short subheadings.
- numbers and values
As a general rule, in running text numbers from zero to ninety-nine are written in words, with hyphens for compound numbers: twenty-one; forty-seven. When a sentence contains two or more figures of 100 or above, however, numerals could be used throughout for consistency within that sentence. But clarity for the reader is always more important than blind adherence to rule, so a pleasing balance must be found in each case.
Try not to start sentences with numerals. Spell out ordinals (but not in dates): first, second, third, fourth.
Use figures for numbers referring to measurement, percentage, quantities and so on:
an 80–20 split; each gutter between the 12 columns should be 16 pixels wide.
For percentage values, in running text the words per cent are preferable, but for numerals % is better:
In a recent survey, over eighty per cent of respondents were male.
In 453 lines of CSS, 10% were missing closing semicolons.
For the numbers 1,000–999,999 use a comma between the thousands. Numbers of a million or more are rarely used or useful expressed only in figures unless to make a particular point. Round figures up or down and combine numerals with words:
Over 8.5 million visits to the site were recorded last month.
Provide a footnote if it’s essential that the reader knows an exact number.
- that, which
There is sometimes confusion about when to use these apparently interchangeable words. Remember that that defines and which provides more detail (often in a clause enclosed by commas):
Blade Runner, which I watch every day, is the film that I love the most.
Quite often, as in that last example, that can be removed altogether.
Spelling
- affect, effect
There’s no simple noun/verb rule, unfortunately.
The photo wasn’t affected (verb) by the effect (noun) of the Photoshop filter – our attempt to effect (verb) a change had failed.
Particularly in the US, but increasingly in the UK and elsewhere, affect (noun, with the stress on the first syllable) is used as a psychological term to refer to the experience of emotion.
- Bézier curve
With an uppercase B and an acute accent on the first e, but cubic-bezier in CSS. Named for Pierre Étienne Bézier, a French engineer who started to use them in the 1960s to design car bodies for Renault.
- defence, defensive, defensible
Defense is not British English, but we like to confuse matters by using s in other forms of the word.
- click
Double-click, left-click and right-click are hyphenated as both nouns and verbs. Remember, too, that many users tap and don’t click. If you just mean clicking on a link, use follow.
- drop-down
Hyphenated as a modifier or noun: a drop-down menu; a drop-down.
- ebook, e-commerce, e-learning, email
There’s no hyphen in email or ebook, no matter how ugly Email and Ebooks look at the beginning of a sentence. E-commerce and e-learning, however, retain the hyphen. The jury’s still out on EPUB (as the IDPF has it). EPub (that is, ePub. See what I mean about when these words open sentences?) looks good, but does it serve eBeer?
- fullscreen
One word.
- homepage
One word.
- invite, invitation
Invite is the verb; invitation the noun. (A losing battle, really, like quote/quotation.)
- internet
Internet only gets a capital letter when it starts a sentence.
- -ise/-ize | -yse/-yze
British English has pretty much settled on -ise (despite the OED listing -ize forms first, and -ize being closer to the Greek source).
- licence/license | practice/practise
British English uses distinct spellings for the noun and verb. To remember the difference, think of advice/advise (c for noun, s for verb).
- line height
Two words, but line-height in CSS.
- log in, login, log out, logout
One word as an adjective (or noun: what’s your login?); two words as a verb. You use a login form to log in.
- lowercase, uppercase
One word, and in CSS as well.
- no one
Two words.
- OK
Okay is not OK.
- page view
Two words.
- per cent
Two words, but use % with numerals: fifty per cent; 50%.
- plug-in, plugin
Still hyphenated if a noun, but the single word form plugin is gaining ground.
- sans serif
Two words, but sans-serif in CSS.
- screen reader
Two words.
- screenshot
One word.
- sign up, sign-up
Hyphenated as an adjective; two words as a verb. You use a sign-up form to sign up.
- sitemap
One word.
- smartphone
One word.
- start up, startup
Has lost its hyphen when a noun. You start up a startup.
- style sheet(s)
Two words, for now.
- technologies (names and abbreviations)
The names of technologies and applications below are shown as they would appear in running text, followed by their abbreviated names (should they have them). Please note spellings and any capitalisation.
- asynchronous JavaScript and XML (Ajax)
- cascading style sheets (CSS)
- document object model (DOM)
- domain name system (DNS)
- hypertext markup language (HTML)
- hypertext transfer protocol (HTTP)
- iOS
- JavaScript
- jQuery
- LESS
- Mac OS X
- Photoshop
- Post-its
- PowerPoint
- Sass
- Twitter, tweet, tweeting
- their, there, they’re
They’re pronounced in more or less the same way, but be sure to distinguish between their different meanings there, in your writing.
- touchscreen
One word.
- units
The abbreviations are to be used with figures: 12KB; 60fps; 480px. When used as standalone words, spell out units in full: dimensions are stated in pixels; a higher frames per second rate is required.
- kilobytes = KB
- megabytes = MB
- gigabytes = GB
- terabytes = TB
- megabits per second = Mbps
- pixels = px
- frames per second = fps
- up to date, up-to-date
Let’s see: learning modern, up-to-date techniques helps keep your skills up to date.
- web, web app, webfont, weblog, webpage, website
Web isn’t capitalised unless it starts a sentence.
- white space
Two words, but white-space in CSS.