Documentation Guidelines

To better ensure the quality of our documentation, please take the time to read through the following information.

Our documentation is broken-up into following namespaces (catagories), to help separate content…

• doc - Area for the official Aqsis user manual.
• guide - Area for in-depth tutorials and how-to's.
• recipe - Area for short/quick tutorials, otherwise known as recipes.
• tip - Area for tips and tricks.
• faq - Area for frequently asked questions.
• wiki - Area for discussions and a place where users can submit new content for inclusion within one of the other areas - i.e. new tutorials.
• dev - Area for development-related content.
• todo - Area for development-related todo lists.

There should only ever be one instance of content, and that should be held within the relevant namespace (refering to that content via a link or such is fine however).

It is possible that further namespaces may be added, but this will not be taken lightly and believe this structure should be sufficient for the foreseeable future.

Being 'Open' in nature can be both a blessing and a curse, which is why it's important to lay-down some ground rules for when editing/creating new content…

• Be sure to read all of the information contained within the Index page before editing/submitting any content.
• All file names (pages, images, etc) should be lowercase and use underscores (_) to represent spaces within the name.

• Index pages (the first/root page within each namespace) must be kept as clean/simple as possible.
• Try to use short, unique (yet descriptive) names when creating new pages, always thinking ahead (is the name you've chosen unique to your content only, or might it cause problems further down the line for somone else?).
• When creating new pages (files), use underscores to represent spaces within the name…

[[namespace:my_page|My Page]]

• Restrict image usage to PNG and JPG files only, though PNG is prefered if possible.
• When uploading images, place generic (non-platform specific) images into the relevant namespace root and platform-specific ones into the relevant sub-directory - i.e. win/linux/osx.
• When using images, ideally ensure the maximum width of the image is no larger than 320 pixels. You can automatically scale images using the '?«width»' suffix…

{{namespace:image_name.png?320}}

• Try not to use 1st and 3rd-person perspectives (like 'I' and 'we') within content, though if one must be specified 3rd-person is preferable - i.e. visit 'our' website.

We currently maintain 3 levels/types of user access…

• [ALL] - Can read content.
• registered_users - Can read and edit existing content.
• wiki_managers - Can read, edit and create new content.

Users who do not have vaild Aqsis accounts (website login) are assigned to [ALL], while those with valid Aqsis accounts are assigned to registered_users.

wiki_managers access has been restricted to the following accounts (point-men)…

• Tobi
• mbaas
• renderguy
• pgregory
• Romain
• stegu
• tcolgate
• c42f

This is not set-in-stone however, so things may change on this front (this list should always be updated though).

If you have any questions/queries that are not addressed above feel free to write them below for review/inclusion…