Manual of Style
While a manual of style can't cover all possible issues, this document should cover the major issues. If you encounter something that isn't covered in this guide and you need to make a decision on how to handle it, please let us know so we can update the style manual and ensure consistency throughout the site.
When writing copy for Dreamwidth, make the tone "casual professional" -- the style you might take with someone you've just met at work, where you want to be friendly and welcoming but you also want to avoid possibly giving offense. The watchwords for site copy, FAQs, and all corporate communication should be:
All copy should be gender-neutral, inclusive, and direct. We want readers to know there are other human beings on the other side of the screen, people who are talking to them directly in a human voice on a one-to-one basis. Avoid pompous phrasings, convoluted constructions, and any attempt to cover up something that might not be pleasing to the community.
The site's name is Dreamwidth Studios, and the company that owns it is Dreamwidth Studios, LLC. Whenever you're referring to the parent company (as opposed to the site itself), you must include the "LLC" at the end of the name. When writing a FAQ or cleaning up site copy, the first instance of the site name on the page should be "Dreamwidth Studios", and further instances on the same page should be "Dreamwidth".
Unless otherwise specified, follow the rules of grammar in The Columbia Guide to Standard American English (2001) unless a documentation editor overrides it. The casual tone of the site shouldn't extend to grammatical mistakes that are acceptable in spoken Informal American English but aren't acceptable in Standard American English. If in doubt, ask for arbitration.
- 1 ABBREVIATIONS
- 2 ACRONYMS
- 3 ARTICLES
- 4 AVERAGE READING LEVEL
- 5 CAPITALIZATION
- 6 COMMA SPLICES
- 7 CONTRACTIONS
- 8 DASHES VS. HYPHENS
- 9 DATES
- 10 DICTIONARY
- 11 DIRECT ADDRESS
- 12 EMAIL VS. E-MAIL
- 13 ENTRY VS. POST
- 14 FONT AND COLOR CHANGES
- 15 GENDER NEUTRALITY
- 16 GRAMMAR
- 17 HTML ENTITIES
- 18 HYPERLINKS
- 19 HYPHENATION
- 20 IDIOMS
- 21 INTERNET
- 22 LOGIN VS. LOG IN VS. LOG-IN
- 23 MUST VS. SHOULD VS. MAY
- 24 NUMBERS
- 25 OFF-SITE LINKS
- 26 OXFORD (SERIAL) COMMA
- 27 PARENTHETICALS
- 28 PASSIVE VOICE
- 29 PERSONAL PRONOUNS
- 30 POSITIONAL LANGUAGE
- 31 QUOTATION MARKS
- 32 QUOTATION MARKS (2)
- 33 RELATIVE PRONOUNS
- 34 SAMPLE COMMANDS
- 35 SEMANTIC HTML
- 36 SITE PAGES
- 37 SPECIAL CHARACTERS
- 38 STATEMENTS OF SITE POLICY
- 39 US VS. UK SPELLING
- 40 WORD PROCESSING
Avoid abbreviations on the site and in site documentation: Dreamwidth rather than DW, Terms of Service rather than ToS, etc. The exception to this: acronyms (FAQ for Frequently Asked Questions) are acceptable if the acronym is more common than the expansion.
If you're using an acronym (such as FAQ for Frequently Asked Questions), render it in all-caps (unless Internet-wide commonly-accepted style has it otherwise). Don't use an apostrophe for the plural: FAQs rather than FAQ's. Don't use periods in an acronym unless commonly-accepted usage agrees that they should be there (RSS rather than R.S.S.).
The proper article to use with singular FAQ is a: a FAQ.
AVERAGE READING LEVEL
FAQs should have a readability level of 8.0-9.0 on the SMOG Readability Scale if at all possible. (Lower is more readable, higher is less readable.) For complex instructions with a high level of technical terms, simplify the surrounding sentences as much as possible.
Capitalize the title of the page when you're referring directly to another site page, such as the Manage Journal page. For other uses, use your discretion. If it would be easy to mistake a DW-specific concept for another common word, or if you're mixing usage of the common word (not to refer to the DW concept) and the DW concept, capitalize the uses of the DW concept. Otherwise, default to lowercase unless the site text (not the FAQs) consistently capitalizes the concept. (A little inconsistency is okay; don't sweat it too much.)
When you're referring to something that's in common use on the Internet or that a beginning user would likely be familiar with, such as tags, bookmarks, etc., use lowercase.
The name of the site is Dreamwidth, with an initial capital and no internal capitals.
Use contractions whenever possible -- don't rather than do not, can't rather than cannot, it's rather than it is, etc.
DASHES VS. HYPHENS
A hyphen between two parts of a compound word should be a single dash: -. A split between two parts of a compound sentence should be an em dash with a space before and after the compound — like this. Use the HTML entity — rather than two hyphens.
Spell out dates using the international format: 23 June 2008, no commas.
Use the online version of Merriam-Webster (11th Edition) as your reference dictionary.
Address the reader directly whenever possible: you can rather than users can.
EMAIL VS. E-MAIL
Use email (no hyphen) in all cases.
ENTRY VS. POST
The proper noun form is entry (entries rather than posts or postings); the proper verb form is post.
In other words, they are entries, and you post them.
You post an entry.
However, if you must make something, you may make a post to your account.
If you are writing something in your journal, you are writing an entry, not a post (and definitely, help us all, not a blog).
FONT AND COLOR CHANGES
Do not convey information solely through font and color changes without accompanying semantic HTML structure. Do not use inline CSS styling to alter text. If you feel you need to use CSS styling to alter text, consult with the maintainer of the site scheme to have a semantic CSS class included in the site-wide CSS declarations.
Whenever possible phrase sentences so the pronouns are plural or use second-person address. If this is absolutely impossible no matter how hard you try, use "they" as a third-person singular gender-neutral pronoun — but please be aware that if you do, you will be causing physical pain and suffering to at least one staff member. When you need a compound noun, choose one that's as gender-inclusive as possible.
Use the rules of Standard Written American English.
Be sure to include the semi-colon (;) at the end of HTML entities such as —.
If you use a hyperlink inside the body of your work, make sure the link is anchored to the most relevant word or phrase in the sentence and describe the link as adequately as possible: go to the <a href="http://www.dreamwidth.org/admin/console">Admin Console</a> rather than go <a href="http://www.dreamwidth.org/admin/console">here</a>.
Unless a compound noun has passed into widespread use (either as a single word or as two words), hyphenate it. When in doubt, consult your fellow editors and arrive at consensus.
Avoid idiomatic expressions and slang whenever possible.
When you use it as a specific noun (the Internet, Internet standards, etc), capitalize "Internet".
LOGIN VS. LOG IN VS. LOG-IN
The verb is two words, and the proper preposition is "in" rather than "into": you log in to your account. The noun is one non-hyphenated word: you keep your login information secure. Don't use "log-in".
MUST VS. SHOULD VS. MAY
Use must/must not (or any synonyms such as "have to", etc) sparingly and only when what you're discussing is an absolute requirement for use of the site or to complete a task. Use should for recommendations, even strong recommendations. Use may or can for optional situations where the user can choose equally among options based on personal preference.
Use numerals in all instances (3 instead of three, etc).
Avoid off-site links (links to any site other than Dreamwidth) in FAQs and site copy. If valuable information is stored off-site and duplicating that information on Dreamwidth would be inconvenient or cumbersome to maintain, you must obtain permission to use an off-site link. All off-site links shall be stable, respectable, long-term links to respected sources; Wikipedia is not a stable, respectable, long-term source while something like the W3C would be. We'll grant permission to link based on the length of time the site has existed, the length of time the page in question has remained current, and the general reputation of the source.
OXFORD (SERIAL) COMMA
Use the Oxford (serial) comma in all instances of a multiple list: thing one, thing two, and thing three rather than thing one, thing two and thing three.
Avoid parenthetical statements in the body of a FAQ or site copy unless you are giving an alternate term. If you must use parentheticals, punctuation goes inside the parenthetical if it's a full sentence: (This is a full sentence.) Punctuation goes outside the parenthetical if it's a partial sentence inside a larger sentence (like this).
Avoid passive voice if at all possible.
Use we if at all possible, rather than Dreamwidth. However, see "#STATEMENTS OF SITE POLICY".
When possible, don't use visually positional language for describing where an element/item/menu/etc appears on the screen, as not only are these things consistent from site skin to site skin, this makes it harder for users with low vision and screenreader users to identify the item. If you do need to describe where an element is, include both visual position and the position in the HTML source. (For instance: the interaction menu on a profile page is both "on the right-hand side of the profile in most site skins", and "the first set of links when read by a screenreader or displayed by a non-graphical browser".)
If you quote a full sentence, punctuation goes inside the quote marks: "This is a full quoted sentence." If you're quoting a partial phrase at the end of the sentence and the punctuation isn't part of the quotation, punctuation goes outside the quote marks: this punctuation style is "nonstandard".
QUOTATION MARKS (2)
Do not use "smart quotes" under any circumstances.
Remove the relative 'that' whenever possible, unless it makes the sentence unclear or confusing: we believe you should be able to rather than we believe that you should be able to.
When using sample commands in the body of a FAQ, any sample commands should be used in the <code> tag, and any variable within that sample command should use the <var> tag.
If it's necessary to use HTML in your work, use XML 1.0 standards (including self-closing tags such as <br />), lowercased, and semantic tags rather than structural: <em> instead of <I>, and <strong> instead of <B>.
When referencing a site page, use the name of the page as given in the page's <TITLE> attribute (the title that appears in the browser bar), rather than any title given on the page itself as a header. Capitalize all page titles. In site copy, if you are naming a site page that the user will likely need to go perform an action on, hyperlink the name of that site page to the actual page. In FAQs, if you're naming a site page that is only marginally relevant to the question you're answering, add the link to the "Read More" section at the bottom of the FAQ.
Do not use "smart quotes", en or em dashes, or any other special character your word processor might insert. If you require any special formatting, special characters, ligatures, accents, or any extended-character-set text, use the HTML entity to produce that character (such as é for é).
STATEMENTS OF SITE POLICY
If you find it necessary to make a statement of policy on behalf of Dreamwidth Studios, LLC, or to make a statement that encapsulates site philosophy and you aren't sure if you have the appropriate corporate philosophy down pat, please confirm that statement of policy with an owner of the company before making that change visible to the community.
US VS. UK SPELLING
Always use US spelling.
If you choose to compose your work on your computer instead of directly in the on-site editor (which we strongly recommend so you can have a local copy of your work saved), use a plain text editor (such as Notepad, TextEdit, or BBEdit), not a word processor such as Word. Word processors insert control characters and auto-convert symbols, which will transfer via cut and paste.