Wiki
Contents
Meta-Wiki
This guide is a guide to the Swivel Knowledge-base and is intended as a guide for people to help them get the most out of the wiki but also a guide for how to contribute articles to the wiki.
What is the wiki
The wiki is a knowledge-base full of a range of articles. Articles can be of the following types
- Navigation (where) pages: Pages that guide people to the most appropriate sections within the wiki
- Explanations (what): Articles that explain features of the product, installations, error messages
- Solutions (how): Solutions to problems, eg getting locked out of the admin console, changing the port numbers that PINsafe runs on
How to use the Wiki
The wiki provides a number of different routes for a user to get to the information for which they are look.
- Search: The wiki has an advanced seach engine that allows a user to serach for the information they seek, eg "Nortel Integration" to find a Nortel VPN Integration guide.
- Navigate: Starting at the Main Page following the appropriate links, eg Intergration Guides then VPN Integration then Nortel VPN
- Mixed: If a user has a symptom that they wish to understand they may first search based on that symptom, eg "account locked" this will take them to an article that explains when and how accounts become locked. This article then has links to a number of related articles that may provide the required solution.
Articles will be constantly be being added to the wiki, realistically the navigation pages will always be slightly behind, therefore if information cannot be found via navigation, searching should be tried.
Contributing to the Wiki
To keep the wiki manageable articles should be small and self-contained. Authors should remember that a solution needs to be understandable to someone who has gone directly to that article via a search as well as by someone who has navigated to it. Authors who contribute new or edit existing solutions should check relevent navigation/explanation pages to see if any of htse would benefit from updating.
Document Format
There are some standard article formats that are recommended. These are
- Only use two levels of headings
- Do not number headings
- Images should be annotated
[[Image:selectNAT.jpg|frame|none|Selecting NAT option]]
- The following format should be used for command line representation
> ls -al
This is achieved by starting each line with a space character
Document Categories and Templates
All documents should be categorised as either Navigation (where), Explanation (what) and Solution (how).
They should be further sub-categorised, for example a VPN Integration guide would be in the VPN category which is a subcategory of Integration which is a sub-category of How.
To ensure this include the following
[[Category:VPN]]
Documents can be in multiple categories, for example a white paper that explains a feature of PINsafe and includes a how to section could be a what and how page.
You can see the available categories Special:Categories
An easy way to ensure that you document is place in the appropriate categories is to use an appropriate template. Wiki templates are not like Word templates, they merely include a block of wiki-text in to all documents that include them. To use a template use
{{Template:templatename}}
eg {{Template:default}} will add the Swivel Secure logo to the top of the page.
For example the a VPN Integration guide should include the following wiki-text
{{Template:default}} {{Template:how}}
[[Category:VPN]]
So including the logo and ensuring that the article is appropriately categorised. The use of Templates also means that additional functionality can be added at a later date.
As well as their being a hierachy of doucment types, there are other parallel categories, eg subject categories. Manuals etc should also be categorised according to the product to which they relate, eg an appliance white paper would be categorised under "appliance", a sub-category of "product" and "whitepaper", a subcategory of "what".
For hints and tips about authoring articles see the authoring article.
