Knowledge Base Style Guide: Brief Edition

The main content of an Answer consists of three parts: The Summary, the Question, and the Answer.

The Summary

The Summary is an incomplete sentence written in the third person. It is the only section that is fully visible in searches. It serves as a title for the Answer and is capitalized as such. The Summary is as brief as possible so that it can be read at a glance (about 5-10 words).

If an Answer pertains to a specific product or group of products, that information should be included in the Summary as the first word followed by a colon. Multiple products should be separated by commas.

If the Answer pertains to a specific error, a portion of that error is included in the summary.

Examples

Scoring Options in MyMathLab

Microsoft Word: “Registry Policy Setting” Error

The Question

The Question field is written as a question being asked by a visitor to the support site. For that reason, it is written in first person. It always ends in a question, and may also include a more detailed description of the issue than what is found in the Summary. The question is brief (about 20 words) but may be longer if a detailed error message is included.

Examples

How do I retrieve mylogin nameor password?

How do I set scoring options in MyMathLab?

When Itry to open a MicrosoftWord fileIreceive an error message that refers to my "registry policy setting," and the file will not open. How can I use this file?

The Answer

The Answer section contains the resolution to the issue in the question. It is written in second person as a response to the Question, as though spoken to the customer. The length of an Answer will vary according to the subject, but it is always a discrete piece of content that is about a specific subject, has an identifiable purpose, and can stand alone.

Keywords

Keywords should be words that uses may search on, but that do not appear in the Summary or the Question. Please do not use any words that are in the Summary or Question as Keywords as it throws off searches

Writing Style

For a complete description of the writing style, please see the full version of the Knowledge Base Style Guide. The guidelines below provide a summary of the most important aspects of writing style.

Typographical Conventions

Bold type is used for the name of a button or clickable control. Italics are used to add emphasis or to denote a variable in instructions. An underline is used only for hyperlinks. Quotation marks (“”) are used for direct quotes, while the text of a user entry or error message is indicated by using the Courier font.

Web addresses are displayed as hyperlinks, and (where formatting allows) the full address of a link’s destination is shown. Links to pages in the 247 Technical Support site (addresses that contain “247pearsoned.custhelp.com”), open in the same window while links to other sites open in a new window. When linking to another Answer, link to the text “Answer 1234” (where 1234 is the Answer ID).

Preferred Words and Phrases

Several commonly misused words and phrases are listed below.

Use… / Do not use… /
ActiveX / Active X
double-click / double click
email / e-mail
log in (v.), login (adj.); log in to
log out (v.), logout (adj.) / log on (v.), logon (adj.); log on to
log off (v.), logoff (adj.)
option button / radio button
plug in (verb)
plug-in (noun) / plug in (noun)
plug-in (verb)
restart / re-boot or reboot
set up (verb)
setup (noun, adj.) / setup or set-up (verb)
set up or set-up (adj)
set up or set-up (noun)
standalone / stand alone

When writing about a graphic user interface, use the following conventions to promote consistency in our documents:

· Select for menu commands, check boxes, option buttons, text, and items in a list.

· Clear when deselecting a check box.

· Click when selecting buttons, links, and tabs.

· Double-click when clicking the mouse button twice completes an action.

· Press when touching a key on a keyboard or a physical button is required.

· Enter when typing text into a field.

Capitalization

Proper nouns and acronyms are capitalized. The Summary section is capitalized as a title.

Punctuation

Follow the rules of English grammar regarding commas, colons, semicolons, dashes, hyphens, apostrophes, quotation marks, parentheses, exclamation points, ellipses, etc.

Using Lists

When instructions are given in an Answer, they are presented in a numbered list. When a list of items is given where order is not significant, they are presented in a bulleted list.

Reading Level

It is important when composing Answers to keep in mind that some of our customers are enrolled in developmental reading, writing, and math classes; therefore please avoid technical jargon and complex writing styles.