Template:K

From Second Life Wiki
Revision as of 12:43, 16 November 2009 by Torley Linden (talk | contribs)
Jump to navigation Jump to search
KBtip2.png Tip: While you aren't required to follow this Style Guide to make unofficial Wiki pages, it may help you be a more effective writer, so feel free to adopt these practices!
This page is about style used in English articles. For other uses, see K (disambiguation).

Interested in contributing to the Extended Knowledge Base? Please read this style guide to gain a better understanding of the framework we're using to craft beautiful documents which aren't just well-written, but easy-to-read.

Our style guide is inspired by successful common conventions such as Wikipedia's, blended with specifics about the Second Life® experience. This guide is open to evolving over time, yet aims to provide consistency you can refer to when in doubt.

Please note that these style guidelines are meant to be more strictly enforced for material that's part of the Second Life Knowledge Base, but you can feel free to apply them elsewhere on this wiki wherever it may be beneficial! Consistency in communication helps clarity to a degree you may find startling.

Read the main Editing Guidelines before editing KB articles. Being well-primed will help you get started smoothly. You should also have a basic understanding of wikicode, a combination of plain text and formatting markup.

Furthermore, feel free to examine any established KB article in detail, such as How do I add someone to my Contacts list?, for examples. Once an article's in the Wiki, of course, you can click the Edit tab near the top of the screen. You'll need to be logged in.

It is not a replacement for industry standards such as The Chicago Manual of Style or The Elements of Style. However, when contributing to Linden Lab's written documentation and communication, it's a good idea to read through these notes to be sure your articles are meeting the standards.

Knowledge Base articles

This section discusses the structure of articles and their arrangement within the Knowledge Base as a whole, sort of.

Knowledge Base article structure

There are two basic types of Knowledge Base article:

  1. The ones that answer a specific question ("How to save textures to your hard drive")
  2. The ones 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 an unspoken question:

  1. After I read this, what should I be able to do? (Pretty self-evident.)
  2. 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 ___."

If all the articles in the Knowledge Base start off this way, readers will become accustomed to finding out very quickly whether the information in a particular article will be useful to them without having to read the whole thing.

Headers

Articles should be divided into headers, each one representing a distinct topic. For instance, in an article about different types of scripted objects, each type could have its own section with a header.

Top-level article headers are the equivalent to a "h2" in modern blog software and other content management systems: 

== Header ==

Furthermore, content should begin on the next line, with each paragraph separated by two line breaks (if you use a single line break, text continues on the same line).

In a particularly extensive article, use sub-headers: 

== Header ==
Text goes here...

=== Sub-Header ===
Even more text...

==== Sub-Header ====
You get the idea...

Keep flow a foremost priority. A table of contents will automatically appear in an article with four or more headers, but if an article feels tedious to scroll through, you may want to separate sections into their own pages, and link to them instead.

If you don't want an article to have the table of contents, insert this at the top: 

__NOTOC__

To save space and right-align the table of contents, use this template: 

{{TOCright}}

Note that this template doesn't work well if you are also using a navigation template that floats to the right.

Knowledge Base article scope

One problem that wikis and knowledge bases frequently run into is the proliferation of pages that contain closely interrelated or even duplicate subject matter, but with little connection between them. This is due to a lack of central planning, and the nature of wiki growth.

When it comes to Second Life documentation, we should remember that a FAQ on estate billing should be integrated with — or at the very least, closely linked to — the main article for estate billing. By linking the pages together and clearly indicating this, it provides readers with a clear path to follow to get more help, and editors with a better indicator of what they need to keep track of when editing a given subject.

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 you tell people what happens when they do things, use the present tense, for example:

  • Click IM. The IM window opens.

As opposed to:

  • Click IM. The IM window will open.

Terminology

KBcaution.png Important: The closest thing to an "official glossary" is the Viewer 2 built-in glossary, which uses the content from Viewerhelp:Glossary.

Second Life-specific words

  • "inworld" (this used to be "in-world," but it's closing up the same way "e-mail" and "web site" went)
  • "rez" or "rezzed" (not ressed/rezed/res). Do not capitalize.
  • Always capitalize "Second Life."
  • Spell "plugin" with no hyphen.
  • "SLurl" instead of "SLURL", when referring to Second Life URL's (http://www.SLurl.com). This is a Linden Lab trademark.

When referring to Linden Lab reflexively, we go with "We recommend" over "Linden Lab recommends," except in the case of something really formal, like a legal communication or something. It's probably likely we won't be writing actual legal briefs anytime soon, though.

  • You can probably write around this sort of thing 99% of the time anyway, by simply saying something along the lines of "Do x to achieve y."
  • You can also say things like "Our tests have found that x happens when y."

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

User interface elements

It would be good to have some standard terms that we use across the Knowledge Base to refer to elements of the UI.

  • Is that thing a "dialog" or a "window"?
  • Are those "forms" or "tabs" or what?

Maintaining consistency makes it easier for readers to understand what we're talking about, whether they realize it or not.

In general, capitalize and spell user interface (UI) elements exactly as they are in the interface. If there's some inconsistent capitalization in the UI, note it and we'll put it in a bucket that we'll eventually give to somebody. If there's a misspelling or a typo in the UI, that's probably bug material!

  • Menus - We all know what menus are; they 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, it's probably more helpful to refer to the internal window before the name of the menu. Like:
      • In the Inventory window, select File > Open.
    • Otherwise we risk confusing people, since there are two "File" menus available if you've got the Inventory window open.
    • The separator for menu item selections should be the > mark. For example:
      • Select Edit > Detach Object > Right Hand to drop the object you're holding.
  • The Pie Menu - This is that wheel of selections that shows up whenever you right-click on something inworld.
    • It's worth noting that it seems relatively easy to write around having to mention it by name. Just say "Right-click on the tree and select More > Wear," for example.
  • Windows - Use this term for the windows that appear internally within the Second Life window, such as the Inventory window or the Search window.
    • Note: A window is anything that satisfies most of these conditions:
      • It's got the _ X deal in the top right corner.
      • It's got a title in the upper left corner.
      • It can be moved around or resized.
    • An example of something that's not a window is the thing that appears at the bottom of the Viewer when you click the Chat button. We should standardize on calling that the "Chat bar", since it basically satisfies none of these conditions.
  • Dialogs - Use this term for the blue thing 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.
    • Sample usage might be something like "A dialog appears, telling you there's no room to sit there."
    • It's worth noting that there are multiple kinds of these, like 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 dialog pops up in the lower right corner telling you your pal is online".
KBnote.png Note: In Viewer 2, we're considering calling these simply "notifications," as they really serve only to notify a Resident that something's occurred, and don't present a yes/no choice, which is what most "dialogs" typically do these days.
  • Tabs - These are the tabs that live 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. Depending on the sentence that surrounds it, you're probably okay referring to a button any way you want.
    • Click the Save button.
    • or Click Save.
    • Pet peeve: "Click on the Save button" contains a redundant word! The world won't end if you use it, but Jon Linden doesn't like it.
  • Fields - Anything that you use to provide input to Second Life that's not a button is a field, pretty much. Notes on specific fields follow:
    • Use "checkbox" rather than "check box."
      • Use "select" as a verb for checking or unchecking one, because the redundancy of (for example) "Check the Rotate checkbox". "Select the Rotate checkbox" feels better, because the repetition's gone.
    • Use "dropdown" instead of "drop down."
      • This is another one where "select" works well, as in "From the Style dropdown, select Fancy." "Pick" also works, and is less formal, but there's slight potential for confusion if flower-picking ever becomes a widespread Second Life activity.
    • "Radio button" is preferred for any field that presents you with a bunch of choices that have round circles next to them.
      • Somewhat unsurprisingly, "select" works really well here too, as in "Select the More swords radio button."
    • There's at least one orphan field that doesn't actually have a prompt or a button next to it, which is the filter field in the Inventory window. That's the sort of thing you can probably write around, as in "Type something into the filter field at the top of the Inventory window."
    • Any other interface item, like a text field or those number fields that are all over the prim editing one, can probably safely be referred to simply as "the ___ field."
    • General idea: If you've got a long article, you can probably get away with referring to fields more directly (as in "Provide a Description" instead of "Provide a value for the Description field") as you progress through it. Unless you think the reader's not going to be able to follow you, this is OK to do.

Deprecated terminology

As Second Life has matured, Linden-favored terms have changed as well. We should take care to only use the current words for the concepts and items we describe, both to avoid confusion, as well as to avoid potential legal issues, such as the example of writing "money" rather than "Linden Dollars". Linden Dollars aren't money!

For example, "Private Islands" is a term we’ve deprecated in favor of "Estates" (when there's a group of Private Regions together) or "Private Region". (As many Residents have noted, if you have two adjacent non-mainland Regions, why are they individually considered "islands"?)

Please keep in mind that these are general guidelines; context is everything!

So, we 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, of course, a more appropriate term to use -- when discussing the actual inworld representation of a Resident that can be clicked upon or edited, for instance. 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
  • "SLurl" instead of "SLURL", when referring to Second Life URL's (http://www.SLurl.com)

These terms may be in common usage among Residents, but it’s important to maintain a consistent message.

When it comes to search keywords, it’s important to remember that we do have to respect common usage. Thus, keywords for common terms should be placed on the appropriate pages.

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
  • Internet
  • Linden Dollar
  • Resident or Residents, when referring to the Second Life community members.
  • Region (when referring to a Second Life Region), Private Region, Homestead Region, Openspace Region.
  • 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

In general, capitalize any interface element (names of fields, buttons, menus, etc) exactly as it appears in the Second Life Viewer.

Do not capitalize the following words/phrases:

  • Web/website (Unless in the context of "World Wide Web")

Use of jargon

If you’re writing help docs for Second Life, you hopefully 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 very well may not. With that in mind, we can avoid confusion in one of the following ways:

  • If there’s an actual English word or phrase for what you’re describing, use that instead of Second Life jargon.
  • If you can't do that for some reason, link the first occurrence of each Second Life-related 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 you’re writing an article titled "I just started. What do I do now?", everything will be new to those reading. 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".

Supplementary to the Glossary, let's remember jargon that might be confusing or just plain opaque to new Resis or non-English speakers. Such as:

  • rez, rezzing = appear inworld
  • av, avi = avatar
  • TP, teep, port = teleport
  • cam, alt-zoom = free camera motion using Alt + mouse
  • AO = Animation Override

All SL-specific terms should be spelled properly based on their predominant usage. For example, it's "rez" and "rezzed", not "res" and "ressed".

Certain terms should be capitalized, others should not. Others will be changed in time.

Again, refer to the glossary for proper contextual usage.

"First life"

Avoid using the term "first life" for anything that takes place in, well, first life. You can usually write around places where this comes up by including the phrase "outside of Second Life," which is handy.

Formatting

This section covers the actual formatting of text. Should that thing be bold? Do we italicize the names of fields? Fortunately, since we're sticking more or less to HTML in the Knowledge Base, this will be extremely simple.

General rules

  • Bold - Use bold text to refer to anything in the UI that you need to click on or interact with. This includes:
    • Names of tabs
    • Names of fields
      • Selections you would make from fields
    • Labels of buttons
    • Names of links
    • Menus and menu item selections
    • Examples:
      • In the Tools window, click the More button.
      • In the Tools window, click the Object tab.
      • From the Building Block Type dropdown, select Cube.
      • Select World > Force Sun > Sunset to make the sun set immediately.
  • Not Bold - Do not use bold for window titles.
  • Italics - Use italics sparingly, in cases of EXTREME EMPHASIS (which should be quite rare). On even rarer occasion, captions for images.
  • Quotation Marks - Anytime you need to specify something that the user needs to input, put it inside 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.
    • I.e., In the About field, type "I am the king of this land and all that I survey."
  • Punctuation - Jon thinks it makes more sense not to apply styles to punctuation.
    • I.e., Click OK.
    • The period isn't bold.
    • Jon likes this because it's consistent: The period doesn't show up on the button, so why bold it?
    • Confession: They did the opposite of this at Jon's old company, and it always vexed him.
  • Superscript - Use <sup> tags to properly raise text as-needed. A common example is properly showing the abbreviation for "square meters".
    • WRONG: m2
    • RIGHT: m2
  • Other typography - 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.

Titles and subtitles

Use sentence capitalization for all titles and headings. This means to capitalize the first letter in the heading (as well as other words that are normally capitalized such as proper nouns). 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?

Lists

What follows are some guidelines surrounding lists.

Numbered lists

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

# Click the '''Log in''' button.
# Read the Messsage of the Day.
# Smile!

Results in:

  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.

Unordered lists

Use bullet points for series of brief points. They're often found in the form of mid-article "Quick tips" or "Related resources" at the end of an article: 

* Consider that!
* Consider this!
** A sub-point, but don't go overboard on these.

If you find yourself writing bullet points with long paragraphs, consider whether a list is the best format.


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

Use the <code> tag to show a background-colored, fixed-pitch font 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.
  • Retrieve your capability from https://cap.secondlife.com/get_reg_capabilities
  • Use the max_results query parameter to limit the number of results returned.
  • Use the AgentLimit object to programmatically limit the number of agents present in a Region.
  • In the top box, type 512.
  • In the Region field, type Sandbox Newcomb.

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

For multi-line code samples, use the syntax highlighting extension; for example: 

 # Hello World in Python

 def main():
     print "Hello World!"
 
 if __name__ == '__main__':
     main()

Tables

We use Template:KBtable, to automatically style tables consistently. Template:KBtablehead is used if the table has a header row. The overall emphasis is on minimal, elegant readability without too much "boxiness". The style is subject to future revision.

For example, this: 

{| {{KBtable}}
|- {{KBtablehead}}
!  
! Column A
! Column B
! Column C

|- 
| '''Row A'''
| fill
| in
| these

|- 
| '''Row B'''
| values
| and 
| win

|}

becomes:

Column A Column B Column C
Row A fill in these
Row B values and win

For advanced users, further styling is available.

Warnings, notes, tips, and other templates

If there's something you think deserves some special emphasis in a Knowledge Base article, make a warning, a note, or a tip out of it. The following table describes the main KB templates, part of a larger group of KB templates.

Template Wiki code Description What it looks like
Template:KBwarning {{KBwarning|Foo}} A strong notice of what NOT to do, and if applicable, the consequences, including something that can cause harm or damage.
KBwarning.png Warning: Foo
Template:KBcaution {{KBcaution|Foo}} An important notice of what NEEDS to or SHOULD be done — basically, the opposite of KBwarning.
KBcaution.png Important: Foo
Template:KBtip {{KBtip|Foo}} A helpful hint to make a process easier to do.
KBtip2.png Tip: Foo
Template:KBnote {{KBnote|Foo}} Additional considerations and things that are good to know.
KBnote.png Note: Foo
Template:KBtrivia {{KBtrivia|Foo}} Optional, bonus knowledge. These are least relevant of the templates and an article should be able to be understood entirely without trivia.
KBtrivia.png Trivia: Foo

For example, here is an item that deserves use of the KBCaution template:

KBcaution.png Important: Be sure to click the Save button or your work will be lost!

Troubleshooting

If you have problems including certain styling or a link in a template, a "?" or other characters may be interfering. Use the format "{{TemplateName|1=text}}" with the "1=". For example: 

{{KBcaution|1=[http://forums-archive.secondlife.com/327/85/252954/1.html Don't click this!]}}

becomes (RIGHT):

KBwarning.png Warning: Don't click this!

instead of (WRONG):

KBwarning.png Warning: http://forums-archive.secondlife.com/327/85/252954/1.html Don't click this!]

Links

Link liberally! Links make it easier to discover more info about a given topic, and save someone 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 to relevant pages where more info is provided or there are terms that benefit from further definition. For instance, in an article about performance tips:

If you're in a crowded area, make sure to enable Avatar Impostors.

This has a dual benefit:

  1. Saves space because you don't need to explain an advanced concept in the current article, since the knowledge already exists — a primer sentence or two is fine.
  2. Makes it easier to navigate through related topics, as famously illustrated in xkcd.

Imperative sentences

Linking "imperative sentences", as long as they're not an eyesore long, is encouraged to prompt action and tell the reader what happens if they click that link:

Also, citing articles where there may be ambiguity, whether they're in the Knowledge Base or elsewhere, should be done like this:

  • RIGHT - For more information, see "What are Second Life's subnets?".
  • WRONG - For more information, see What are Second Life's subnets?.
    • The hyperlink may color the article title, but consider if this is printed, that won't be as evident. Just like non-hyperlinked print media, quotation marks should enclose titles of shorter written works.
  • WRONG - Read this article for information on Second Life's subnets.

Images

Pictures show Second Life as-is. They can be uploaded using the "Upload file" form. All images must be uploaded to this Wiki, we can't link to externally-hosted files.

Generally, upload images as PNG, since it's lossless and the Wiki will dynamically resize them to JPGs.

Images should be inserted 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 balance: 

[[Image:Flying-car.jpg|640px]]

Results in:

Flying-car.jpg

The original flying car is 1024px wide.

If an image has extreme dimensions, such as being very narrow and vertically long, consider cropping it selectively in an image editor, then reupload.

Thumbnails can be used sparingly if there's a need to include multiple images: 

[[Image:Flying-car.jpg|none|thumb|''Oh look! A flying car!'']]

Results in:

Oh look! A flying car!

Also! You can link an image to another Wiki page or external site.

Styles

  • There's no need to center-align images. In edge cases, they may be desired for aesthetic purposes. It's alright to leave them default, or left-aligned.
  • Emulate the official callouts and highlights as closely as possible. We use Camtasia'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 PNG format rather than GIF, unless you're taking a picture of something inworld, in which case go with a JPEG.

Captions for 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.
  • Italicize the whole thing too, why not.
  • As far as we're aware, there's no need to label it ("Figure 1" or what-have-you).
  • Use the default skin for consistency.

Revisions

Images can be automatically replaced by another with the same filename. This is useful if there's a new version of the Second Life Viewer with user interface changes and you have fresh screenshots. Simply upload, then confirm you want to replace the older version. This replaces it for all linked instances on the Wiki. If you make a mistake, you can revert.

Videos

You can embed videos & multimedia to make articles more useful and fun. Video tutorials make it easier to understand kinetic, 3D concepts. For example, "{{KBvideo|3578377}}" becomes:

<videoflash type="vimeo">3578377|640|480</videoflash>

Like images, embed videos at a width of 640px. See Template:KBvideo for more info. Also whenever appropriate: include the video in its own section with "Video tutorial" header, and a text summary of what it's about. This can be done as bullet points.

We standardized on Vimeo for Torley's official video tutorials which you can search through, or "vidtuts" for short. (We also have an alternative Widgets extension, but it conflicts with FlaggedRevs, so don't use it for videos on official Knowledge Base articles.)

KBwarning.png Warning: Flash was discontinued in the 2020s, meaning that currently there is no easy way to embed videos on the SL Wiki. This has been reported to Linden Lab and we await a solution.

Navigation Templates

Stuff to do for the Old Knowledge Base: This spec is still being defined. COME SEE Torley if you have questions.


You can use navigation templates to provide easy links to related articles, as shown in the actual example of Template:Navbox/Adult to the right. They can be any articles you choose; all you have to do is insert the template code at the top of a page. For ease of maintenance, you should create a new template when designing a Navbox for a new set of related articles.

Best practices

Navigation templates provide helpful navigation:

  • Choose your articles carefully. Does this navbox help the reader move effectively between related topics? Pick any two articles in the template. Would a reader really want to go from A to B? An overpopulated navigation template creates clutter and loses its effectiveness.
  • Navigation templates should be relatively small. If you find you have too many articles in a single template, consider separating some of them out into more than one template, or remove some from your list, leaving only the most directly related and relevant articles.
  • Navigation templates shouldn't be too small. A navbox with only two links might be better served by a normal link in the body of each article.

Navigation templates provide navigation between existing articles:

  • Navigation templates shouldn't contain "red links". If the article doesn't exist yet, please write it first!
  • Try to avoid unlinked text in a navigation template.
  • Unless deemed essential, avoid the use of external, offsite links in navigation templates. Instead, include any external links in the main article.

Style

Many style concerns with navigation templates are automatically covered by the Navbox template. However, here are a few additional style guidelines:

  • Article titles in a navigation template should always be presented as a bullet list.
  • Always use each article's full title. This is for the purpose of standardization and navigational clarity; an article's title is its unique identifier. We understand that some article titles are exceptionally long, and we are currently considering options to universally shorten and standardize Knowledge Base article titles.
  • Avoid unuseful font styles (bold, italic, etc) in article titles or the navbox title.

Grammar and language

This section contains tips on grammar and dialect that are useful.

Thoughts on style

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

Edit articles consistent 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 is useful to get the point across with examples, but shouldn't distract from understanding.

Overall, since this is reference material, the Knowledge Base's tone is more formal than casual venues than the Official Second Life Blogs. When in doubt, consult existing articles by the Doc Team and ask!

Common grammatical errors

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

Try to 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: The best is to use short, concise sentences rather than longer ones.

Latin abbreviations

Latin abbreviations such as "e.g." may not be universally understood, and can cause difficulty with translation. Follow the guidelines below:

Do not use Use instead
i.e. that is
e.g. for example
etc. and so on

Mixing menus and windows

We use ">" to indicate hierarchy, and it's usually unnecessary to state "menu" unless there's abject confusion or the article is for newcomers.

  • RIGHT - File > Take Snapshot
  • WRONG - File —> Take Snapshot

The same applies for the pie menu, where ">" is explicitly shown for deeper levels.

When UI elements are mixed, make this obvious.

  • RIGHT - Open the Preferences window by selecting Edit > Preferences, click the Network tab, then uncheck Custom Port Connection.
  • WRONG - Edit > Preferences > Network tab > uncheck Custom Port Connection.

We're aware the latter is used by the technically-savvy and in brief Issue Tracker reports, but for the purposes of explaining Second Life as clearly as possible to newer Residents, we do the former.

Keystrokes

We're aware some conventions prefer "+" over "-" as a joiner, and some operating systems (like Mac OS X's own menus) dispense with them entirely. However, this Style Guide is about Second Life; for now, represent shortcuts as they're shown in the Viewer menus.

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

To visually prettify your keystrokes and make them stand out, use Template:K. For example:

  • "{{K|T}} key" becomes T key
  • "{{K|Ctrl|Shift|W}}" becomes Ctrl-Shift ⇧-W
  • "{{K|Up}} {{K|Left}} {{K|Down}} {{K|Right}}" becomes ↑ ← ↓ →
    • This is great for symbols like arrow keys instead of spelling out "up arrow".
  • See "PC and Mac shortcut key differences" for how this template looks in a live article.

The full list of special keys is shown when editing Template:K/core.

Dialect

As Second Life began with a predominantly American user base, all Second Life English-language documentation should be standardized on American English. (We may revisit this policy in the far future, but it would require such an extensive overhaul to so many documents that it seems somewhat suboptimal from a time cost/benefit standpoint, given the other things we could be working on)

This means:

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

Writing in another dialect may be a hard habit to get into. It's to be expected that some mistakes will slip through. We'll still work to correct them, but these sorts of errors should be considered low-priority, trumped first by technical inaccuracy and simply incorrect grammar and sentence structure.

Trademarks

The first instance of Second Life® in an article should have a registered trademark after it to assert our brand. Our trademarks should always be respected, and you can learn more.

Advanced additions

The Second Life Wiki keeps growing and we laud Resident enthusiasm to evolve styles. Be aware some styles are very useful for other sections on the Wiki but don't apply to us yet. Various issues of note are recorded on User:Torley/Code.

Please don't make any broad style changes without consulting with the Documentation Team first. We're here to help and would be happy to have a look.

Commentary

If you want to discuss an article, don't place inline comments unless it's an article which explicitly invites them, because it leads to clutter. Instead, use the Discussion ("Talk") tab, located at the top of every article. The same style guidelines apply here, and you should sign your commentary for clear attribution.{{{1}}}

Adapted from Wikipedia's Template:Keypress

Retrieved from "https://wiki.secondlife.com/w/index.php?title=Template:K&oldid=656923"