User:Jaszon Maynard/Jaszons sandbox Help the general help

I'm currently developing this article and will probably eventually publish it to the wiki

Anyone may edit this wiki, subject to the wiki's policies regarding editing. There's a lot to write for this Help, here's a few ideas and guidelines to maintain consistency.

Requirements for Writing Help

While various optional thoughts are covered below, there is one requirement (so far) for writing help: Put all help articles in the category xxx. This will make it possible for there to be an index to all the help articles.

Articles That Need Work

In addition to the various red links you will find to articles that need to be created, here's a list of articles that need expansion or that have barely been written at all: Help stubs.

There are some [possibly outdated] articles already on the wiki that you may wish to look at to either link to, rename, copy from, or utilize in whatever fashion: [1]

Other Considerations for Writing Help

Duplication of Information

It seems likely that eventually a lot of the information contained under Main Viewer will be accessible from two perspectives: 1) From the perspective of the Viewer's organization, the separate perspective of the various menus and pop-up windows in the Viewer; in this way it functions as a reference for specific questions ("what does this option mean?"). 2) From a topical/functional perspective. And this is probably a good thing.

For instance, the Main Viewer documentation will have separate sections that mechanically, and separately, explain what various interface pieces do, like the Search window, the About Land window, etc. But an overall Land article could link to instructional articles that walk the reader through various functional tasks. An article about getting land could walk through the choice of buying vs. renting, mention how to use the Search window to find appropriate properties, talk about going to the property and examining it (About Land), mention Covenants, give advice on selecting land, and finally walk through the purchase (or rent) process. Such an article would obviously refer to the interface, but it would be giving a look at the interface all from the perspective of someone trying to get land.

Or, another example, the Main Viewer documentation will document About Land and the tabs in the Group window, but that's not the same thing as a topical article about Group Land, that explains what it is, how to set it up, how to maintain it, and where to go in the interface to accomplish all these tasks.

Topical articles will also be a great place to integrate useful info that has nothing at all to do with the interface. For instance, on the topic of land, info from the Land Buying FAQ is useful.

Another example...the Main Viewer documentation will document things like the Communicate window, the Profile window, etc, but an article on the topic of communication could integrate all that and cover the topic of chatting, IMing, using IM back and forth from email, voice chat, sending Notecards like a "letter", etc.

Another example...documenting the entire interface is not the same thing as writing a tutorial on smart ways to go about building a house on your land...though certainly the tutorial will want to refer the reader to the interface documentation for further reading and help.

Write Or Link?

Internal wiki links

As written about above, information in the wiki may be duplicated. Editors will have to consider, if they are working on a section that duplicates information that is already elsewhere, whether to actually write text for their article, or simply link to existing articles.

For instance, an article that focuses on navigation could simply internally link to the Main Viewer documentation that covers different pieces of the Viewer related to navigation (Zoom, Mouselook, Camera Controls, Run mode, Fly, Teleport Home, etc) and have little text.

If such an article had unique things to say about navigation that couldn't properly be covered under the Main Viewer breakdown, then it might have a lot of text, even copying from the other articles.

Or perhaps there doesn't need to be duplicated text, but it needs to be moved to a "better" spot in the wiki.

External links

Editors will have to consider, if there is a reliable, well-maintained site somewhere that does a good job of covering a topic, is it better for an article to simply refer the reader to that site, or is it better to write about the topic right here in this wiki.

Of particular note in regards to linking to articles are the articles in the secondlife Knowledge Base (KB). These are maintained by employees of Linden Labs, and so can be a great resource. Unfortunately viewing them requires a login (a slow, often broken process that may confuse the reader) which times-out. If a reader simply clicks a link they get a page saying they have timed-out and can't view the page and there's no way to recover.

Even if Linden changes the timeout requirement, these articles are denoted by an ID # which may or may not remain stable, in which case the link could break. The KB is also going to be re-coded, in part to remove the requirement of logging-in before reading help. That may also cause a break in the links to their articles.

There are only 2 alternatives at this point. The best one is to instruct the reader they must go login first, then they may click the link. This will probably be confusing, and who knows if the article ID # will remain stable, but at least there's a chance they'll get to read the KB article.

A second choice, more confusing, & harder, but at least not prone to link-breakage, is to tell the reader to login to the support site and tell them search terms to enter and the title of the article they should look for.

Since the KB is such a valuable resource, at the very least, it would be good to find some way to put links to useful KB articles in a "Further Reading" section.

Operating System Independence

When starting an article it may help future editors if you give some thought to structure and platform-specific dependencies: Can the article be written as a single topic that's valid for all operating systems (with perhaps small embedded notes about O.S. differences), or does the article need to be organized into broad sub-sections where section 1 deals just with Windows, section 2 Macintosh, and section 3 Linux?

SLurls, Tutorials

When possible the article should include useful SLurls, and if there are applicable in-world tutorials definitely give a SLurl to the relevant place (like Public Orientation Island or Public Help Island). Since the SLurl won't bring you right to the tutorial, & the islands can be crowded, confusing, laggy, & crashy, describe major landmarks near the applicable tutorial and how to get there so the resident can find it. i.e.--Once you've arrived, find the tall building labelled "XYZ". Stand so the building is to your left. Walk straight ahead until you come to a stand of trees, and look for a sign on your right....