Use this style guide when writing and editing Second Life Knowledge Base articles. If you are updating content that has migrated to the Community Platform from the wiki, be sure to consult the Knowledge Base Editor's Checklist before you publish.

Basic guidelines

There are two basic types of Knowledge Base articles:

• Those that answer a specific question ("How to save textures to your hard drive")
• Those that give some general knowledge about a topic ("Guide to Jobs in Second Life")

In either case, the first paragraph of the article should answer the question:

• After I read this, what should I be able to do?
• After I read this, what should I understand better?

This can be as simple as making the first paragraph say something like "This article discusses ___."

Starting articles this way enables readers to find out quickly whether the information in a particular article will be useful in their immediate situation.

Article scope

One problem that knowledge bases frequently run into is the proliferation of pages with closely interrelated or even duplicate subject matter, but with little connection between them. To help address this, integrate or link related articles. Linking the pages together provides readers with a clear path to follow to get more help, and editors with a better view of what they need to keep track of when editing a given subject. For example, an FAQ on estate billing should be integrated with — or at the very least, closely linked to — the main article for estate billing.

Duplicate information on multiple pages increases the odds that those pages won't be updated as that information changes. This vastly reduces the usefulness of the Knowledge Base as a whole. Whenever possible, try to modularize things such that information on how to do something lives in one place only, and gets linked to by other articles. That way, you only have to update it once if it changes.

Knowledge Base article tense

When providing instructions, use the present tense, for example:

• Click IM. The IM window opens.

As opposed to:

• Click IM. The IM window will open.

Generally, prefer present tense over future tense.  Thus write

• This article covers xyz.

Rather than

• This article will cover xyz.

Terminology

Second Life-specific words

Second Life has its own jargon and usage. The official Second Life glossary is Viewer 2's built-in glossary, used in the Viewer 2 help system.  Refer there for information on usage, spelling, and capitalization of Second Life-specific terms.

Here are some common examples:

• "inworld" is one word. This used to be "in-world," but it's closing up the same way "e-mail" and "web site."
• "rez" or "rezzed" (not ressed/rezed/res). Do not capitalize.
• Always capitalize "Second Life."
• Spell "plugin" with no hyphen.
• Use "log in" as a verb but "login" (as in "login field") as a noun.
• Use "on" not "in" when referring to land, for instance, "on a parcel," "on a Private Region," and so forth.
• "SLurl" instead of "SLURL," when referring to Second Life URLs (http://www.SLurl.com). This is a Linden Lab trademark.

When referring to Linden Lab reflexively, use "We recommend" over "Linden Lab recommends." Better, just say "Do x to achieve y." You can also say things like "Our tests have found that x happens when you y."

If you're talking about a specific Linden Lab program or service, always, always use the full name of the program.

Deprecated terminology

As Second Life has matured, its terminology has changed as well. Take care to use the current words for concepts and items to avoid confusion and potential legal issues. Don't write "money" when you're talking about "Linden dollars" — Linden dollars aren't money!

Here are some guidelines for replacing common deprecated terms. Use:

• "Region" instead of "sim" or "simulator" when referring to a single region.
• "Sim host" instead of "sim" or "simulator" when referring to a server hosting regions.
• "Residents" instead of "users," "subscribers," "customers," "avatars," etc.
  • There are cases where "avatar" is a more appropriate term to use: for instance, when discussing the actual inworld representation of a Resident that can be clicked upon or edited. In that case, use "avatar," by all means!
• "Estates" or "Private Regions" instead of "islands," "private islands," etc. (An estate is a group of Private  Regions.)
• "Linden dollars" instead of "money," "dollars," "cash," "lindens," etc.
• "L$" instead of "$" when denoting Linden dollars.
• "US$" instead of "$" when denoting US dollars.
• "Pacific Time" (PDT or PST depending on daylight savings) instead of "Second Life Time" or "SLT." 
• "SLurl" instead of "SLURL" when referring to Second Life URL's (http://www.SLurl.com).
• Avoid using the term "first life." Instead, say "outside of Second Life.”

Use of jargon

If you're writing Second Life documentation, you should know the difference between a prim and a Class 4 server, but do the Residents reading your article? Depending on the audience your article is geared towards, they may or may not. With this in mind, you can avoid confusion in one of the following ways:

• If there is an actual English word or phrase for what you're describing, use that instead.
• If you must use jargon, link the first occurrence of each technical term to its appropriate page, or to its entry in the glossary. "Rez" shouldn't have its own page, but a good place to point to would be a page on building terminology. Likewise, "Class 5 server" should link to the Region Sales page, if that's the most applicable.

As a rule of thumb, if you're working on something involving advanced subject matter (such as a page on prim torturing), basic terms like "rez" or "IP address" might not need to be defined.

If, on the other hand, you're writing an article titled "I just started. What do I do now?", then everything in it will be new to your readers. When writing for a general audience, the trick is balancing between the phrases "rez a prim" and "create a primitive, one of the simple building blocks that can be used to create everything you see in Second Life."

Again, refer to the glossary for proper contextual usage.

User interface elements

In general, capitalize and spell user interface (UI) elements exactly as they are in the interface. This section explains the standard terms for UI elements.

Menus

Menus appear at the top of the Second Life window. Sometimes they also appear at the top of windows inside the Second Life window, like the Inventory window. In these cases, refer to the internal window before the name of the menu; otherwise it can be ambiguous, since there are two "File" menus available if the Inventory window is open. For example:

In the Inventory window, select File > Open.

Use the > mark as the separator for menu item selections. For example:

Select Edit > Detach Object > Right Hand to drop the object you're holding.

Windows

Use this term for the windows that appear within the Second Life window, such as the Inventory window or the Search window. A window is anything that satisfies most of these conditions:

• It's got the _ X widget in the top right corner.
• It's got a title in the upper left corner.
• It can be moved around or resized.

Notifications

Use this term for the small widget that pops up in the corner whenever something happens in Second Life, like when someone or something tries to give you inventory, or if it turns out you can't sit on that thing you wanted to sit on.

So you might write, for example:

"A notification appears, telling you there's no room to sit there."

There are multiple kinds of notifications, such as the group notification dialog and friend-status notifications, but they always pop up in a consistent place, so you can give the reader spatial references like "A notification pops up in the lower right corner, telling you your pal is online."

Tabs

These are the tabs inside the windows in Second Life. Refer to these as you would windows, except bold them (see the formatting section below).

Buttons

Use this term for the buttons that appear in the UI. For example:

Click the Save button.

or

Click Save.

Fields

Most other UI elements with which you provide input to Second Life are fields. Some notes on specific fields:

• Use "checkbox" rather than "check box."
• Use "select" as a verb for checking or unchecking, to avoid the redundancy of (for example) "Check the Rotate checkbox." "Select the Rotate checkbox" feels better, because the repetition is gone.
• Use "dropdown" instead of "drop down." This is another case where "select" works well, as in "From the Style dropdown, select Fancy."
• "Radio button" is any field that presents several choices that have round circles next to them. Use "select" here too, as in "Select the More swords radio button."

Any other interface item, like a text field or those number fields that are all over the Build window, can be referred to simply as "the ___ field."

In a long article, you can refer to fields more directly; for example, "provide a Description" instead of "provide a value for the Description field".

What to capitalize

Follow standard rules for capitalization; that is, capitalize:

• Proper nouns
• The first letter of the first word in numbered or bulleted lists

Also capitalize:

• "Second Life Viewer" and "Viewer" when referring to our client software.
• Second Life
• Linden Lab
• Resident or Residents, when referring to the Second Life community members.
• Region, when used in the phrase "Private Region," “Second Life Region,” “Homestead Region,” or “Openspace Region.” For generic unqualified use, do not capitalize.
• Second Life region names, for example: Ahern, Help Island, Serenity
• The first letter of each term that identifies the name of a key on a keyboard: Ctrl-A, Escape key, the M key, Ctrl-Shift-Q
• The first letter of each term that identifies a particular button or menu item within the Second Life client: Inventory, Fly, IM button, Edit menu
• Acronyms: SL, HTML, WWW
• General, Moderate, and Adult, when referring to an element in the interface or to the rating of a land or of an item in the Marketplace. Do not capitalize when referring generically to the broad concept of adult (or general or moderate) content. Hence, for example, "an Adult region" but "adult keywords" and "adult activities."

In general, capitalize any interface elements (names of windows, fields, buttons, menus, and so on) exactly as they appear in the Second Life Viewer.

Do not capitalize the following words or phrases:

• web/website (unless in the context of "World Wide Web")
• internet
• dollar (as in Linden dollar)
• premium account
• basic account

Formatting

General rules

Bold

Use bold text to refer to UI elements that the user can click on or interact with. This includes:

• Names of tabs
• Names of fields
• Selections you make from fields
• Labels of buttons
• Names of links
• Menus and menu item selections

Do not use bold for window titles, however windows and tabs that appear in the Viewer in all caps should be referenced accordingly in all caps.

Examples:

• In the Tools window, click the More button.
• In the Tools window, click the Object tab.
• Click the up arrow next to the Speak button. The NEARBY VOICE window opens.
• From the Building Block Type dropdown, select Cube.
• Select World > Force Sun > Sunset to make the sun set immediately.

Italics

Use italics when introducing a new term for the first time. For example:

All Second Life objects are made of prims, short for primitive, a 3D shape like a cube, sphere, or cone.

Otherwise, use italics sparingly, in cases of extreme emphasis (which should be quite rare).

Quotation Marks

To specify something that the user types, use quotation marks. This is usually only applicable to text fields, and it's probably rare that we would need to specify an exact string for someone to enter, but this might come in handy one day. For example:

In the About field, type "I am the king of this land and all that I survey."

Remember that commas and periods should always go inside quotation marks. The only exception is when you are instructing readers to type a specific command and wish to avoid any possible confusion.

Superscript

Use <sup> tags to raise text as needed. The proper abbreviation for "square meters" is a common example:

• WRONG: m2
• RIGHT: m²

Dashes

Use real em dashes to indicate a break in thought: "—", not "--" or "-". If you can't enter them on your keyboard, just copy them or use the &mdash; html entity.  Do not put a space before or after an em dash.

Sentence spacing

Use two spaces at the end of a sentence to separate it from the next sentence.

Do not format punctuation marks

Do not apply formatting to punctuation. For example, do not make periods and commas bold. For example:

Click OK.

• The period isn't bold.

Sections and headings

Divide articles into sections, each with its own heading representing a distinct topic. Use “Heading2” (the <h1> HTML tag) in the edit toolbar for top-level article headings. Sub-headings below that level are “Heading3,” (<h2> in HTML) and so on.  

Use sentence-style capitalization in headings: capitalize the first word, along with any other words, such as proper nouns, that are usually capitalized (see What to capitalize above).  

Do not capitalize other words that would not normally be capitalized. For example:

• INCORRECT: An Overview of Second Life Security
• CORRECT: An overview of Second Life security

• INCORRECT: How Do I Attach and Detach Objects From My Avatar?
• CORRECT: How do I attach and detach objects from my avatar?

Table of contents

Provide a table of contents (TOC) for articles with four or more sections. If an article feels tedious to scroll through, consider dividing it into several linked articles.  Lithium does not automatically generate a TOC as the wiki does.  Therefore, we use an external Perl script.

Prerequisite: Download this Perl script: http://duramecho.com/ComputerPrograms/HtmlHeadingsToTableOfContents/index.html

If you don't have Perl installed on your computer (i.e. "if you're on Windows"): You can get ActivePerl here. You can install with the default options. Make sure you restart your computer afterward.

Procedure

1. Copy / paste the HTML into a local file.
2. Add <html><body> ....</body></html>
3. Run script

perl HtmlHeadingsToTableOfContents.pl <YourHtmlFile.html>

4. Copy paste results back into Lithium.

5. Add TOC table wrapper code

TOC wrapper code

<table id="toc" class="toc" summary="Contents">
<tbody>
<tr>
<td>
<!-- Generated TOC here -->
</td>
</tr>
</tbody>
</table>

NOTE: You may want to strip off the <html><body> ....</body></html> tags, though Lithium will probably do that for you.

Lists

Use numbered lists for a series of steps that must be followed in order. For example:

1. Click the Log in button.
2. Read the Messsage of the Day.
3. Smile!

In general, each item or instruction in a numbered list should be a complete sentence and should be punctuated accordingly — that is, with a period, an exclamation point or (in rare cases) a question mark.

Use bullet points (unordered lists) for a series of brief points. If you find yourself writing bullet points with long paragraphs, consider whether a list is the best format.

Files, paths, URLs, code samples, and typed user input

Use the <code> tag for file names, directory paths, URLs (or portions thereof), code snippets, and other typed user input. For example:

• Look in C:\Program Files\Second Life\app_settings\.
• Edit the settings.xml file.
• Go to http://my.secondlife.com/
• In the top box, type 512.
• In the Region field, type Sandbox Newcomb.

Put lengthy URLs on a separate line using the <pre> tag.

Tables

Use tables to convey parallel information efficiently.  If you find yourself using a bullet list with lots of repetition, consider converting the information to tabular form.  The basic format that the Lithium toolbar inserts is fine, but you will need to edit HTML to add a heading row (<th> tags) and to make a wider table, which usually looks better than the default.

The above table is created with the following HTML:

<table border="0" style="width: 500px;">
<tbody>
<tr>
<th>Heading 1</th> <th>Heading 2</th>
</tr>
<tr>
<td>Data</td> <td>Data</td>
</tr>
<tr>
<td>Data</td> <td>Data</td>
</tr>
</tbody>
</table>

Warnings, notes, tips, and other templates

For information that deserves special emphasis, use the following HTML templates to make the message stand out.  You must edit HTML and use the following HTML snippets to do so.

• Warning: A strong notice of what NOT to do, and if applicable, the consequences, including something that can cause harm or damage.
• Important: An important notice of what NEEDS to or SHOULD be done — basically, the opposite of a warning.
• Tip: A helpful hint to make a process easier.
• Note: Additional considerations and things that are good to know.

Warning

<div style="background-color:#ffeeee;padding:10px">
	<strong>Warning:</strong> Warning goes here.
</div>

Caution

<div style="background-color:#ffffdd;padding:10px">
	<strong>Caution:</strong> Caution message goes here.
</div>

Tip

<div style="background-color:#ffffdd;padding:10px">
	<strong>Tip:</strong> Tip goes here.
</div>

Note

<div style="background-color:#f5f5f5;padding:10px">
	<strong>Note:</strong> Note goes here.
</div>

Cross-references and links

Links make it easier to discover more information about a topic, and save the reader the trouble of searching. If faced with a choice whether to link to relevant details or not, you can safely err on the side of linking.

Link "imperative sentences", as long as they're not extremely long, to prompt action and tell the reader what happens if they click that link:

• RIGHT - You can download Second Life
• WRONG - You can download Second Life

Cite Knowledge Base articles as follows:

• WRONG - Read this article for information on avatar attachments.
• WRONG - For more information see Avatar attachments.
• RIGHT - For more information, see Avatar attachments.

Images

Use images to illustrate articles with relevant screenshots of UI and inworld content. Do not include an image just for the sake of having an image: it should provide some illustrative value. The GNOME style guide contains a good discussion of when and how to use images.

Use PNG format for images. Insert images into articles at a width of 640 pixels (640px), or less if the original image dimensions are readable at smaller sizes. This tends to be a good balance between visibility and content. If an image has extreme dimensions, such as being very narrow and vertically long, consider cropping it selectively in an image editor, then re-upload. In general, don't use thumbnails.

Styles

As much as possible, keep English text out of images to ease localization. Of course, if a screenshot includes UI text, this won't be possible.

Don't use special effects such as drop shadows, torn edges on cropped images, and the like. Such effects are a distraction.

• There's no need to center-align images. In edge cases, they may be desired for aesthetic purposes. It's all right to leave them default, or left-aligned.
• Emulate the official callouts and highlights as closely as possible. We use TechSmith's SnagIt software.
• Only include as much as you really need; if you're talking about the Tools window, you don't have to capture the entire Second Life window.
• If you're going to call out something specific, like circling a button or a menu choice, use pink, and make sure the line is thick enough to stand out without obscuring anything else excessively.

Use captions with screenshots! If you're going to put a sentence next to a screenshot, it should include some useful information that's not readily apparent in the actual screenshot itself.

• A caption should be below the picture with no extra white space between.
• Use a complete sentence, and punctuate it as you would a sentence.
• Don't number the caption ("Figure 1" for example).
• Use the default skin for consistency. Assuming a customizable UI, use the default configuration when possible.

Tools

There are many tools for taking screenshots, and you are free to use whatever you like. Here are some suggestions:

• Jing is a free, easy-to-use tool that provides some rudimentary callout and highlighting tools.
• Capture-A-Screenshot is another very simple, free tool for screenshots.

Videos

You can include videos and multimedia to make articles more useful and fun. Video tutorials make it easier to understand kinetic, 3D concepts.

As with images, use videos judiciously to communicate only such information as can't be readily explained in words. Avoid overkill: if one video gets your point across, leave it at that.

Although Lindens can explicitly embed videos using the <embed> tag, that capability is not provided to community members, due to possible security risks.  The HTML filter will prevent Residents from saving articles containing such tags, so in general, use the edit toolbar's Insert a video button, shown at right.

All official Second Life videos are hosted in the Second Life YouTube channel.   Look there to find the URL to insert to include a video.

Include a brief text summary of the video's subject above the video in the page.  Use the following settings when inserting videos:

• Size - Large
• Alignment - Inline

Grammar and language

This section contains tips on grammar, style, and usage.

Thoughts on style

"The best way to be boring is to leave nothing out" -Voltaire

Edit articles consistently with their original "vibe" as established by employees of Linden Lab. Some topics will obviously be more jovial than others. Language (English and international equivalents) should be terse enough to communicate succinctly, but not so dry that it's boring. Humor can be useful to get the point across, but clarity is the first priority.

Overall, the Knowledge Base's tone is more formal than that of casual venues like the Second Life Blogs. When in doubt, consult existing articles or get advice!

Don't ask, tell

Avoid writing headings that put their subject in the form of a question; use simple declarative phrases instead. For example, rather than "How do I make a gesture?", write "How to make a gesture." This is a clearer, more straightforward way of presenting information.

Use the serial comma

 Per Strunk and White, in a series of three or more terms with a single conjunction, use a comma after each term except the last. Thus write, 

...red, white, and blue.

...honest, energetic, but headstrong.

Common grammatical errors

Semicolons are used to separate two clauses of a compound sentence while indicating a closer relationship between them than a period would. We can think of semicolons as somewhere between a comma and a period.

Avoid using a comma where a semicolon would be more appropriate. If you're unsure, ask someone.
For a more detailed explanation of semicolons, see UW-Madison's Writer's Handbook entry on semicolon usage.

Note: Short, concise sentences are always better than long and complicated ones.

Use American English

All Second Life English-language documentation is standardized on American English. This means (for example):

• Use "color" instead of "colour".
• Use "recognize" instead of "recognise".
• Write acronyms in all-caps without periods, except when they're a brand. (DOS, TCP/IP, NASA, WiFi, D.A.R.E. — these are all correct.)

Do not use Latin abbreviations

Latin abbreviations such as "e.g." may not be universally understood and can make translation difficult. Follow the guidelines below:

Keystrokes

Represent shortcuts as they're shown in the Viewer menus.

• RIGHT: Ctrl + Shift + W
• WRONG: Ctrl-Shift-W

Numbers

Spell out numbers zero through ten.  Use numerals for 11 or larger.

Trademarks

The first instance of Second Life® in an article should have registered trademark after it to assert our brand. Our trademarks should always be respected. For more information, see Guidelines for Using Linden Lab's Trademarks.