User:Jaszon Maynard/Jaszons sandbox Help the general help - Revision history

Jaszon Maynard: editing

2008-03-07T20:52:57Z

editing

← Older revision		Revision as of 13:52, 7 March 2008
Line 30:		Line 30:

	=== Write Or Link? ===		=== 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.		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.

Jaszon Maynard: editing

2008-03-02T15:17:56Z

editing

← Older revision		Revision as of 08:17, 2 March 2008
Line 2:		Line 2:

	Anyone may edit this wiki, subject to the wiki's [[Editing_Guidelines\|policies]] regarding editing. There's a lot to write for this Help, here's a few ideas and guidelines to maintain consistency.		Anyone may edit this wiki, subject to the wiki's [[Editing_Guidelines\|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 ==		== Articles That Need Work ==
Line 9:		Line 13:
	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: [https://wiki.secondlife.com/w/index.php?title=Special%3AAllpages&from=&namespace=12]		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: [https://wiki.secondlife.com/w/index.php?title=Special%3AAllpages&from=&namespace=12]

	== ~~Guidelines &~~ Considerations for Writing Help ==		== Other Considerations for Writing Help ==

	=== Duplication of Information ===		=== Duplication of Information ===
Line 20:		Line 24:

	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.		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.		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.

Jaszon Maynard: editing

2008-03-02T13:55:38Z

editing

← Older revision		Revision as of 06:55, 2 March 2008
Line 1:		Line 1:
	<big>'''I'm currently developing this article and will probably eventually publish it to the wiki'''</big>		<big>'''I'm currently developing this article and will probably eventually publish it to the wiki'''</big>

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

	== Articles That Need Work ==		== Articles That Need Work ==
Line 11:		Line 11:
	== Guidelines & Considerations for Writing Help ==		== Guidelines & Considerations for Writing Help ==

	=== ~~Organization~~ of ~~Topics~~ ===		=== 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.		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.

Jaszon Maynard: editing

2008-02-29T05:47:27Z

editing

← Older revision		Revision as of 22:47, 28 February 2008
Line 20:		Line 20:

	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.		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...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? ===		=== Write Or Link? ===

Jaszon Maynard: editing

2008-02-29T05:39:10Z

editing

← Older revision		Revision as of 22:39, 28 February 2008
Line 15:		Line 15:
	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.		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 ~~integrated~~ from the perspective of someone ~~acquiring Land~~.		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.

	~~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.		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.		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.

Jaszon Maynard: editing

2008-02-29T05:36:43Z

editing

← Older revision		Revision as of 22:36, 28 February 2008
Line 13:		Line 13:
	=== Organization of Topics ===		=== Organization of Topics ===

	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 perspective of the menus and pop-up windows in the Viewer; ~~and~~ 2) From a functional perspective. And this is probably a good thing.		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		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 integrated from the perspective of someone acquiring Land.

			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.

	=== Write Or Link? ===		=== Write Or Link? ===

Jaszon Maynard: editing

2008-02-29T04:52:16Z

editing

← Older revision		Revision as of 21:52, 28 February 2008
Line 6:		Line 6:

	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]].		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: [https://wiki.secondlife.com/w/index.php?title=Special%3AAllpages&from=&namespace=12]

	== Guidelines & Considerations for Writing Help ==		== Guidelines & Considerations for Writing Help ==
Line 27:		Line 29:
	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.		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 ~~belong~~ in a "Further Reading" section.		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 ===		=== Operating System Independence ===

Jaszon Maynard: editing

2008-02-29T04:38:18Z

editing

← Older revision		Revision as of 21:38, 28 February 2008
Line 19:		Line 19:
	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.		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 ~~when deciding whether or not~~ to ~~link at all~~ to ~~a site~~ are the articles in the secondlife [http://www.secondlife.com/support Knowledge Base] (KB). These are maintained by employees of Linden Labs, and so can be a great resource. ~~However they 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~~.		Of particular note in regards to linking to articles are the articles in the secondlife [http://www.secondlife.com/support 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.

	~~Another issue, right now~~ if ~~a wiki article links to a KB article, to read~~ the ~~KB article~~, ~~the reader has to login to the secondlife site~~, which is ~~a VERY slow process, and may be confusing to the reader, & that login process frequently seems~~ to be ~~having technical problems~~, ~~adding~~ to the ~~confusion ("Our support portal is currently having technical problems~~. ~~If you only need~~ to ~~view knowledge base~~ articles~~, please log in as a guest")~~. ~~And if you keep the article up too long, it will time-out on you.~~		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.

	~~One alternative~~ to ~~avoid link-breakage would be to direct~~ the reader to go to the ~~support site and execute a search~~. ~~Specify what they should type in~~, and ~~what~~ article ~~title~~ they ~~are looking for. This is however still a slow process, requiring login~~.		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.

	Since the KB is such a valuable resource, at the very least, links to useful KB articles belong in a "Further Reading" section~~, even if those links may break someday~~.		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 belong in a "Further Reading" section.

	=== Operating System Independence ===		=== Operating System Independence ===

Jaszon Maynard: /* Write Or Link? */ editing

2008-02-27T21:05:04Z

Write Or Link?: editing

← Older revision		Revision as of 14:05, 27 February 2008
Line 19:		Line 19:
	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.		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 when deciding whether or not to link at all to a site are the articles in the secondlife [http://www.secondlife.com/support Knowledge Base] (KB). These are maintained by employees of Linden Labs, and so can be a great resource. However they 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. Another issue, right now if a wiki article links to a KB article, to read the KB article, the reader has to login to the secondlife site, which is a VERY slow process, and may be confusing to the reader, & that login process frequently seems to be having technical problems, adding to the confusion ("Our support portal is currently having technical problems. If you only need to view knowledge base articles, please log in as a guest").		Of particular note when deciding whether or not to link at all to a site are the articles in the secondlife [http://www.secondlife.com/support Knowledge Base] (KB). These are maintained by employees of Linden Labs, and so can be a great resource. However they 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.

			Another issue, right now if a wiki article links to a KB article, to read the KB article, the reader has to login to the secondlife site, which is a VERY slow process, and may be confusing to the reader, & that login process frequently seems to be having technical problems, adding to the confusion ("Our support portal is currently having technical problems. If you only need to view knowledge base articles, please log in as a guest"). And if you keep the article up too long, it will time-out on you.

	One alternative to avoid link-breakage would be to direct the reader to go to the support site and execute a search. Specify what they should type in, and what article title they are looking for. This is however still a slow process, requiring login.		One alternative to avoid link-breakage would be to direct the reader to go to the support site and execute a search. Specify what they should type in, and what article title they are looking for. This is however still a slow process, requiring login.

Jaszon Maynard: editing

2008-02-27T07:13:34Z

editing

← Older revision		Revision as of 00:13, 27 February 2008
Line 23:		Line 23:
	One alternative to avoid link-breakage would be to direct the reader to go to the support site and execute a search. Specify what they should type in, and what article title they are looking for. This is however still a slow process, requiring login.		One alternative to avoid link-breakage would be to direct the reader to go to the support site and execute a search. Specify what they should type in, and what article title they are looking for. This is however still a slow process, requiring login.

	Since the KB is such a valuable resource, at the very least, links to useful KB articles belong in a "~~References~~" section, even if those links may break someday.		Since the KB is such a valuable resource, at the very least, links to useful KB articles belong in a "Further Reading" section, even if those links may break someday.

	=== Operating System Independence ===		=== Operating System Independence ===