Skip to main content

Documentation Guidelines

About​

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.

Contributors can add anything that will help users to install, configure and use FreeSWITCH™. We do request that you follow some guidelines when creating content.

caution

Ads to third-party software are currently forbidden.

Goals and why this page exists​

There are multiple goals with the wiki based documentation effort.

  1. We want to be able to provide quality documentation that is easy to navigate through on the web.
  2. 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.
  3. We want to set an example in the open source community with easy-to-read and understand documentation. Many projects, especially open source ones, have limited documentation or highly unusable documentation. As a community we can create documentation that is of the highest quality.

Guidelines​

Keep It Professional​

When adding documentation please keep comments professional. Things that are not acceptable include:

  • Jokes, especially at the expense of other software projects.
  • Profanity.
  • Slang (colloquialisms can be difficult to understand and translate).

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 web page.

FreeSWITCH™ is a trademark of OSTAG. Please be kind in helping OSTAG maintain its trademark status by ensuring the ™ symbol appears wherever FreeSWITCH™ is used in wiki editing by using the code ™.

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." For example: "JavaScript Example answeringmachine.js"

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 :)