Documentation guidelines
From FreeSWITCH Wiki
First of all, thanks for wanting to share your knowledge. The wiki is growing each day and these guidelines will help us to get that knowledge documented in a structured way. You can add anything that will help users to install, configure and use FreeSWITCH™. Ads to third-party software are currently forbidden; we might create a page for ads in the future. We do request that you follow some guidelines when creating content.
Contents |
Goals and why this page exists
There are multiple goals with the wiki based documentation effort. First we want to be able to provide quality documentation that is easy to navigate through on the web. Secondly we also want to be able to create a PDF manual that contains all the documentation within it. This PDF file would be suitable for printing and putting into a binder. Lastly we want a professional touch to the documentation. Many projects, especially open source ones, have limited documentation or highly unusable documentation. We want to set an example in the open source community with easy-to-read and understand documentation. As a community we can create documentation that is of the highest quality.
Wiki Markup
- Wiki Markup. This is the place to start if you are unfamiliar with wiki markup.
Titles
When selecting a title it is important to select something relevant to the subject you are writing about. It is also important for searching and automated PDF documentation efforts that the titles follow a few basic rules.
- If its a module, use the module name such as mod_dptools
- If its an Object, use the Object name such as Session.answer (with a . but without parens)
- Use the proper case and spelling of the object, don't CamelCase the word unless it is that way such as Session.apiExecute
- Do not use the title to describe the operation of the subject, only use it for its name. Descriptions should be in the page itself.
- If the object has an underscore '_' in its name, use it when creating the title e.g. mod_sofia, however do not use it at any other time.
- Do not prefix anything with FreeSWITCH™ unless its meaning would be unclear otherwise. Everything on this wiki is about FreeSWITCH™
- Use the singular of example not examples since more people will search for the singular and not the plural
Page Content
Do not create a page which only reads 'see this other page'. If you see a page that does that, change whatever links to it to point to the correct place. This is not just for wiki readability, but also for the PDF where these pages look even worse than on a webpage.
FreeSWITCH™ is a trademark of OSTAG. Be kind in helping OSTAG maintain its trademark status and add && after the word FreeSWITCH™.
Avoid creating hundreds of small pages
Sometimes a small page is required, however when you are describing a single entity, such as mod_dptools, which contains a bunch of small functions, it would be better to create one page that covers that, and link each object to the section using the # operator. Searching will work for these sub elements as well.
Examples
Examples should be in the format of "Language Example Name" e.g. "JavaScript Example answeringmachine.js"
Categories
Put one or more categories on each page. This will improve searching. Categories should be added to the bottom of the page.
Remember to check existing categories to prevent multiple categories with the same meaning.
Currently existing categories: Special:Categories
More info
http://meta.wikimedia.org/wiki/Categories
Try to avoid FAQs
Most of the time a FAQ is not required for something. FAQs are helpful in some circumstances, however when writing documentation a FAQ can be less helpful than a proper explanation of the technology and addressing the potential questions by explaining the information without a Q/A session typed into a page. If the technology is properly explained there should not be any frequently asked questions, if there are, then the documentation needs to be revised :)
