Guidelines for Posting to the Wiki
From Partner Documentation Wiki
|
|
Rules? Aw...
Thats right, rules. They aren't difficult or complicated, so just read through them once and occasionally thereafter for reference and things should be just fine. The idea is to maintain some kind of order and consistency on the site, which becomes a problem quickly without a few guidelines.
Naming
I'm hitting this one first because it is by far the most important. Naming is everything in Wiki. Why you ask? Well, within the Wiki site, each article name is considered to be unique. That way, any time you need to link an article, you need only link the name and the Wiki knows exactly what you mean and does all of the work for you. We'll get into the details of the linking process in a minute.
This is so important because if you give a page a lazy, generic name like "tutorial" or some such, as soon as you get another author who is comparably lazy, things get complicated quickly. The Wiki will only allow one page with a given name, so the more generic the naming scheme used, the more likely that there will be links accidentally going to unrelated topics or authors trying to create new pages only to find that they already exist. These kind of things are really irritating, and I'll have none of it.
Instead, try and be as specific as possible. If you were writing a tutorial for, say, Map Viewer 3.7, go ahead and name the article "Map Viewer 3.7 Tutorial". The more specific the better. Any links that are derivative from the main article should progress in kind, i.e. "Map Viewer 3.7 Tutorial: Getting Started". This serves to minimize any potential confusion. Don't worry about awkwardly long names, as the links can be given a more aesthetically pleasing appearance within other articles with very little effort.
Linking
I'm just going to cover the basics, with a helpful hint here and there for reference. For an in-depth guide, I strongly suggest reading some or all of the MediaWiki User's Guide.
The first thing to keep in mind is that the Wiki is Case Sensitive. That means that Linking Example is not the same as Linking example. It isn't really that important whether or not you use capitalization or not, so much as you are consistent. If you read my entries, you can see that I am fond of capital letters in my naming, but it's a matter of personal preference. Don't judge.
Another quirk worth noting is that the Wiki treats spaces and underscores as the same, so Linking Example IS the same as Linking_Example.
Linking an article is easy. Simply type the name of the article within double brackets like so:
[[Name of Article Here]]
Since all of article names within the Wiki are unique, it knows exactly which article you are referring to and will do all of the messy redirecting for you. Even better, the Wiki even knows whether or not the link you posted is legit or not. If you create a link to a page that doesn't exist, the link will appear in red, like this. How cool is that?
Now suppose, for a moment, that you have a Page With a Ridiculously Long Name. You would undoubtedly say to me, "I know that you said long names are good, but I have a Page With a Ridiculously Long Name. The name is both ridiculous, and long. Every time I link my Page With a Ridiculously Long Name, it mars the pure, aesthetic beauty of my otherwise perfect article. What am I to do?"
Fear not. Without clicking, hover your mouse over this link. You should see a small window appear which informs you that this small, unassuming link leads to our very article in question (unless someone has turned this feature off in the preferences without my knowledge... which would be bad...). This astounding feat is accomplished by typing the following:
[[Page With a Ridiculously Long Name|this link]]
This is sometimes referred to as a "piped" link because of the pipe symbol used ('|'). If you can't find it, it's right above the "enter" key on your keyboard. Essentially, the "pipe" tells Wiki to rename the link in the article with whatever follows the pipe. Hence, the link appears only as this link, instead of Page With a Ridiculously Long Name.
The last example I feel is worth noting is how to link to pages outside of the Wiki. Structurally, the process is the same as a "piped" link, but the syntax is slightly different. Take, for example, the link to Wikipedia. The little arrow lets you know that the link leads outside of the Wiki. On the editing page, this link would look like:
[http://en.wikipedia.org/wiki/Main_Page Wikipedia]
Like the piped link, it has two main parts, the link, which in this case is the web address, and the link name, or what it should be called within the article. Unlike the piped link, the two parts need to be separated with a space instead of the pipe symbol. Additionally, only one set of brackets should be used, not two. That's it. Note that the Wiki has no knowledge of the outside world, so it will not mark the link as red if it is incorrect. You should, therefore, manually test all of your external links.
Length
In general, it is preferable to keep articles in one big page instead of in several smaller ones. This facilitates printing articles for reference, which is much easier if everything is together. Obviously, there are times when a single page just won't cut it, like in the longer tutorial entries with multiple sections. This isn't a huge deal. Try putting everything on a single page, and split it up later if it just isn't working out.
Sections
Keep in mind, if you divide your article up using sections, the Wiki will automatically generate a table of contents for your page. This makes finding a specific topic in a large article much easier. To create sections, enclose the title for a topic in equals signs ("="). The hierarchy of sections is determined by the number of equals signs, starting with one set as the biggest and four as the smallest. Generally, one set is almost never used, as it is the same size as the article title and can be confusing. More info can be found at the Mediawiki Article on Sections.
Placement
Placement should be fairly straightforward, as most of the site has already been set up to accommodate articles in new areas. In general, most articles should have a home within a more general category, i.e. the article on Bluetooth can be found on the Handheld Documentation page.
Categories
Categories are tags for specifying the nature of a given article. Once tagged, the articles are cataloged along with all of the other articles with the same tag, and can be browsed by following the category link. The syntax for tagging an article is as follows:
[[Category:Some-Generic-Category]]
A link to the category will then appear at the bottom of the tagged article. If the name appears in red, then it is a category that does not currently exist. For a list of available categories on this site, see the Categories page.
Including
The entire contents of a page can be directly imported into another article with an include command (which is actually a very simple template). The syntax for including a page is:
{{:An Example Include Page}}
Which would appear as:
Include Example
This page is an example of an include command.
An Example Include Page has been inserted in its entirety. This should be used sparingly, however, as it introduces redundancy between pages. In most cases, it would be preferable to simply include a link to the article in question.
In some instances, you may want to exclude a section of an article from being part of an include. To do this, enclose the section to be excluded in the following markup:
<noinclude>This sentence will not be included.</noinclude>
Adding the Page Banner
If you glance up at the top of this page, you'll see the site banner for the Partner Documentation Wiki. This should be added to every new page. To add the banner, simply add the following as the first line of your page:
{{Format}}
That's it. In addition to adding the banner, the Format inclusion also takes care of some page formatting, like right-justifying the table of contents and removing the section edit links.
