This wiki needs some sort of organization. Especially if it's to become Source Mage's primary interface into the intertubes. We don't have a whole lot of documentation and some of it is old.
This document proposes the following categories for Source Mage's documentation:
- FAQ
- Security
- Hardware Issues
- Developer Procedures and Policies
- User Procedures
- Code Documentation
FAQ
A FAQ is the obvious, Frequently Asked Questions. This is a general category so that anything that is a FAQ can fit under this category. Just has to match the format of
Q: Question? A: Answer.
HowTo
Again an obvious category. Anything that is a How-To should go in this category. These documents describe a procedural way to doing something or setting something up. However, things that are Developer HowTo's fit in a different category (Developer Procedures). Developer documents and how-to-set-up-$foo documents should be seperate.
Security
Security documents address specific security issues. They may be HowTo's (How To Secure your Mailserver) or gotcha's. It is not the purpose of these to document Security updates for the distro. This is simply a category for people to use to organize things. If one wanted to look up Linux-PAM and how it works within Source Mage, one could expect to find the information within the Security category.
Hardware Issues
This category is for documentation that pertains to a specific piece of hardware. Making WPA Supplicant work would fit in this category, because it pertains to Wifi Cards. Documentation that pertains on how to get something within Source Mage working on, or with, a specific piece of hardware goes in this category.
Developer Procedures and Policies
This category is for all of Source Mage's internal documentation. For example: the voting procedures would go within this category. Any documents that describe our internal processes.
User Procedures
These are the procedures for the user to follow. They should be written from the point of view of someone who only uses Source Mage and doesn't understand how it all works. Documentation pertaining on how to file a bug in Bugzilla would go in to this category.
Code Documentation
Finally, things like the BashDoc for sorcery could go into this category. The Spell File Documentation will fall under this category as well.
Beyond Categories
Categories are only the way of organizing the documentation by a specific group. Some things specific to a certain component may very well be Developer Documentation and a HowTo. Wiki documents should be created with the following syntax:
/${COMPONENT}/${OPTIONAL_SUB_COMPONENT}/OmgPageThe requirement only stands that the page must start with the $COMPONENT that the document will be owned by.
For example grimoire documentation could be organized as such
/Grimoire/Spell/DETAILS /Grimoire/Spell/DEPENDS /Grimoire/Spell/HISTORY /Grimoire/FUNCTIONS /Grimoire/ChangeLog
This keeps the files related to the grimoire section under the /Grimoire root. That page can be created then to automatically provide an index of the pages within the wiki and relieves the document maintainers of the work of creating and updating pages to find documents.
More generic documentation, that isn't Component specific but is more pertaining to Source Mage as a whole should go through an approval process to be an exception from the norm. More work has to be done to index pages that don't fit under a specific component. A SourceMage section can be created for these documents, but the index page will have to be maintained by hand as the documents within the section can vary wildly.