Editorial guidelines (Bookshelf)

Info

This is a first draft.

simple
concise
quick read; not dense; technical materials will be in layman's terms
do not use Wikipedia writing style
introductory
inviting
enticing
encouraging
celebratory
entertaining
not flippant
not colloquial
age 12 years reading level (for localization ease and as example of encyclopedia reading/writing level)
style reflects that this is an outside view of Wikipedia; assume the audience is NOT familiar with Wikipedia interface (e.g. edit button location)
some text will function without visual support; other text will require visual support
presume that general technologies features rather than the very specifics regarding interface description etc because these can change over time and by Wiki language as well per browser
no acronyms without definitions

Style Guide

Introduction

This is a first draft and a living document. The Chicago Manual of Style is the default resource for questions or items not specifically covered in this guide.

The Bookshelf Project Style Guide is created to support hardcopy print as the final presentation format. The purpose of the Bookshelf Project Style guide is to assist the writers and designers in creating consistency and clarity in their writing. Bookshelf information should be organized in a way easily transferred to print and easily translated to other languages.

Preparing a style guide in collaboration with other team members prior to writing beginning, or creating a style guide while in the editing process using feedback from writers and layout designers are both preferred approaches but schedule constraints make both of those approaches impossible.

Overview

Keep the writing simple and direct. Use the active voice and present tense whenever possible. Choose the simpler of two words, e.g. “use,” not “utilize”. Use imperatives in procedures and instructions. Example: “Do this,” “Choose that,” “Click the INDEX tab”. Do not use contractions because they can be difficult to translate and can cause comprehension problems for non-native English speakers.

References and Resources

Consult the following resources when determining usage and style conventions for the Bookshelf Project.

The Associated Press Stylebook

http://www.apstylebook.com/

Merriam-Webster online dictionary

Merriam-Webster’s New Collegiate Dictionary http://www.merriam-webster.com/

General Writing

Whenever possible, plain language should be used. Plain language is organized logically. Plain language is easy to read and understand the first time you read it. Write in a style that is easy to translate to other languages. Avoid sentences that contain more than two clauses. When possible, break up clauses into individual sentences.

Use words that are easily understood. For example instead of "Content" use a more specific word such as information, video, knowledge, or facts. Limit the use of hyphens, em-dashes and forward slashes as grammatical devices.

Terminology

Avoid technical terms. If you must use them, define the term the first time it appears.

Spell out acronyms the first time they are used. Periods or points are not necessary between the uppercase letters of an acronym.

Define words specific to Wikimedia when they are used. Alternately, at a later date a full glossary of language specific to Wikimedia may be created.

Define page features or information structure specific to Wikimedia. For example, give an overview explanation of the relationship between Wikimedia and Wikipedia when providing instructions or directions to readers.

Write instructions in specific and clear step by step language.

Name page features and instructions the same way they appear on the page. If necessary, after the first instance include other words that can be used interchangeably with the page specific language.

Apply capitalization to user interface items, exactly as it is used in the interface. Example: My talk, Discussion, etc.

Bold

Include user interface items, and process items in Bold. Applying bold to special terms and process items will help readers learn terms that are useful in communicating with other Wikipedians and sustaining the Wikipedia community.

The first instance of the term should be set in bold. Or, the instance of the term that begins the definition of the term should be in bold. Since the Bookshelf materials are written in a narrative style (rather than in Instructional Design or Textbook) there is some flexibility with this rule.

Numbers

Use numerals followed by thousand, million, billion etc. This Wikimedia In-house Style rule allows for special emphasis when describing the success and scope of Wikipedia.

Spell out numbers at the start of sentences.

Stand-alone fractions are spelled out. For example: One-third of the population eats oats.

Use “percent” instead of the % symbol.

Titles

Titles should be written in title case. For example: Ten Easy Steps to Take.

Exceptions are “to”, “a”, and “and”.

Use quotation marks with titles of books, poems, plays, films, speeches, songs, works of art, subjects or lectures, magazine articles. When referring to newspapers or magazines, italicize them.

Bulleted List, Numbered Lists and Checkbox Lists

Keep the structure of the list parallel. Capitalize the first word in each item on a list. Do not end each item with a period. If a bullet item consists of more than one sentence, use standard period placement. If it is necessary to close an item with a period, then all items should be closed with a period whether or not they are complete sentences. The bullet list style should be consistent throughout the document.

Wikimedia In-house Style

When including the Wikimedia office address always include USA and the full mailing address.

Use the “mobile phone” not “cell” or “cellular phone”.

When listing a phone number, add the United States or relevant international calling code number. Put the three digit regional code in parentheses, and use a hyphen between the seven digits. For Example: +1 (415) 839-6885

Special Characters

Square brackets, [ ], should enclose words that will not appear on the page in print or electronic versions. Words enclosed in brackets are instructions to designers or programmers or other team members, to direct an action or treatment of the text.

Create a section entitled “Production Notes” at the end of each section or topic to communicate scripting, visual direction, questions, or outstanding items to other team members.

Special Language

Abbreviation Wikimedia WM Wikipedia WP

Wikipedians

Word List

A

B

C

I

Internet

O
online

S
sandbox
subheading
subsections

U
user account
user name
userpage

W
website
wiki
wikifies
wikiGnome - Contributors that make small or simple edits and changes to articles.
wikilinks
wiki markup

X

Y

Z