Difference between revisions of "Manual of Style"

Revision as of 15:13, 7 August 2008

Dreamwidth Manual of Style

(a working document)

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 that we can update the style manual and ensure consistency throughout the site.

When writing copy for Dreamwidth, the tone should be "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:

• Friendly
• Clear
• Honest
• Human
• Respectful

All copy should be gender-neutral, inclusive, and direct. We want readers to feel like there are other human beings on the other side of the screen, 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 given as "Dreamwidth Studios" and further instances on the same page should be given as "Dreamwidth".

In all instances, unless otherwise specified, questions of grammar should be resolved by [The Columbia Guide to Standard American English] (2001) unless overridden by a documentation editor. The casual tone of the site should not 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.

ABBREVIATIONS

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 familiar to the reader than the expansion.

ACRONYMS

If you're using an acronym (such as FAQ for Frequently Asked Questions), it is rendered in all-caps (unless Internet-wide commonly-accepted style has it otherwise) and the plural does not take an apostrophe: FAQs rather than FAQ's. Do not use periods in an acronym unless commonly-accepted usage agrees that they should be there (RSS rather than R.S.S.)

ARTICLES

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. For complex instructions with a high level of technical terms, simplify the surrounding sentences as much as possible.

CAPITALIZATION

When referring to another site page (such as the Manage Journal page, etc), the title of the page shall be capitalized. When referring to a site-wide concept that is unique to Dreamwidth or not in common use Internet-wide, such as the Watching list (whatever we decide to call it), the concept shall be capitalized. When referring to something that is in common use Internet-wide, or something that a beginning user would be likely to be familiar with ("tags", "bookmarks", etc), the term shall be in lowercase.

COMMA SPLICES

[Don't.]

CONTRACTIONS

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 two dashes with a space before and after the compound &emdash; like this. Use the HTML entity — rather than two hyphens.

DATES

If necessary, spell out dates entirely, using the international format: 23 June 2008, no commas.

DICTIONARY

The reference dictionary to use is the online version of <a href="http://www.merriam-webster.com">Merriam-Webster</a> (11th Edition).

DIRECT ADDRESS

Where possible, address the reader directly: 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. The only exception to this is the verb to make. (You post an entry to your account; you make a post to your account; you write an entry in your account.)

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.

GENDER NEUTRALITY

For pronouns, if at all possible, rephrase the sentence so that it's plural or so that it uses second-person address instead. If this is absolutely not possible no matter how hard you try, you should 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. If you need a compound noun, choose one that is as gender-inclusive as possible.

GRAMMAR

When in doubt, the rules of Standard Written American English shall apply.

HTML ENTITIES

When using HTML entities such as &mdash;, be sure to include the ; at the end of the entity.

HYPERLINKS

If you use a hyperlink inside the body of your work, make sure the link is anchored to the most relevant word 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>.

HYPHENATION

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.

IDIOMS

Avoid idiomatic expressions and slang if at all possible.

INTERNET

If used as a specific noun (the Internet, Internet standards, etc), "Internet" shall be capitalized.

LOGIN VS. LOG IN VS. LOG-IN

If used as a verb, it's two words, and the proper preposition is "in" and not "into": you log in to your account. If used as a noun, it's one word, non-hyphenated: you keep your login information secure.

MUST VS. SHOULD VS. MAY

Must/must not (or any synonyms such as "have to", etc) should be used sparingly, and only when what you're discussing is an absolute requirement for use of the site or to complete a task. For recommendations, even strong recommendations, use should. For optional situations, where the user can choose equally among options based on personal preference, use may or can.

NUMBERS

Use numerals in all instances (3 instead of three, etc).

OFF-SITE LINKS

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 itself 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; something like the W3C would be. Permission to link will be granted 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.

PARENTHETICALS

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).

PASSIVE VOICE

Avoid passive voice if at all possible.

PERSONAL PRONOUNS

Use we if at all possible, rather than Dreamwidth. (However, see "STATEMENTS OF SITE POLICY".)

QUOTATION MARKS

If quoting a full sentence, punctuation should appear inside the quote marks: "This is a full quoted sentence." If quoting a partial phrase at the end of the sentence, and the punctuation is not part of the quotation, punctuation should appear outside the quote marks: this punctuation style is "nonstandard".

QUOTATION MARKS (2)

Do not use "smart quotes" under any circumstances.

RELATIVE PRONOUNS

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.

SAMPLE COMMANDS

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.

SEMANTIC HTML

If it's necessary to use HTML in your work, use XML 1.0 standards (including self-closing tags such as <br />), lowercased, and use semantic tags rather than structural: <em> instead of <I>, and <strong> instead of <B>.

SITE PAGES

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.

SPECIAL CHARACTERS

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 &eacute; 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

In all circumstances, use US spelling.

WORD PROCESSING

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.