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

Click here to expand Table of 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.

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

Wiki Markup​

  • Check out the brief Wiki_tutorial. It contains helpful information and links to get you started.

Also, as of March 23, 2012, David Knell assisted with getting GeSHi syntax highlighting working. Here are some quick examples:

Without syntax highlighting

The following wiki markup...
<pre>
<include>
<param>value</param>
<stuff foo="bar">etc.</stuff>
</include>
<pre>

Yields this output...

<include>
  <param>value</param>
  <stuff foo="bar">etc.</stuff>
</include>

With syntax highlighting

This markup...
<source lang="xml">
<include>
<param>value</param>
<stuff foo="bar">etc.</stuff>
</include>
</source>

Yields this output...

<include>
  <param>value</param>
  <stuff foo="bar">etc.</stuff>
</include>

Languages values include: c, perl, python, lua, and many more.

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" e.g. "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 :)