I’ve been a part of the Asterisk project for many years now, over 10 in fact. I’ve seen it evolve and grow and one of those areas which has changed that I’d like to focus on today is documentation. When Asterisk started out documentation was not as complete or as detailed as it is today and in some cases it was not even strictly required or enforced. As time went on this changed. We gained embedded XML documentation (which I’ll talk about later), a wiki, automatic updating, and guides. The documentation of today is vastly different to how it used to be so lets dive in!

The Wiki

The wiki is a Confluence based wiki system which is the official Asterisk location for all sorts of documentation and notes. We have reference material, how-tos, tips for configuring things, and notes taken from meetings (AstriDevCon). This is the place you should start with when trying to find information on something.

Reference Documentation

As I mentioned earlier the Asterisk project switched to using embedded XML documentation many years ago. This puts the documentation for items directly in the source code and allows us to do a few things. We can enforce that documentation has to exist for anything new that is added. In fact Asterisk won’t even start if you have not documented what you have added. This ensures we don’t fall behind. It also allows documentation to go through the same review process that code does so we can try to make it as best as possible. Finally it allows us to extract the documentation from the source code and put it on the wiki in an automated fashion. Each night a process runs that takes the latest source code, extracts the documentation, and publishes it to the wiki. The wiki can therefore never be out of date with the source code.

The reference documentation is broken up into different areas depending on what you are looking for. Choose based on what you are looking for and you will find the documentation for it. An example would be documentation for the Dial application. It would be under “Dialplan Applications”.

Guides

The guides on the wiki focus on a specific topic and take you through setting it up. These are hand-written and usually also include configuration examples and screenshots. A popular page for this is the WebRTC tutorial page. If you are looking to migrate from chan_sip to chan_pjsip you may want to take a look at the “PJSIP Configuration Wizard” page which can reduce the amount of work you need to do to migrate over. Guides generally live in the specific area for what they are mainly focused on. PJSIP being a major one.

Developer Documentation

Documentation targeted for developers also exists on the wiki and it can serve as a good brainstorming area for discussion. When something new is being thought about or proposed a wiki page is generally created which describes it, how it would work, how it would be configured, and how it would be used. There are also pages which can help developers out when they are looking for how to do something. An example of this would be the “Create a new resource with ARI” page.

Super Awesome Company

The Super Awesome Company is a reference use case that can be used by deployers as a basis for configuring Asterisk for a specific use case. The wiki documents the specific use case.

Configuration Files In Asterisk

The Asterisk project also includes sample configuration files and basic PBX configuration files. In the past we only had samples but with the addition of Super Awesome Company things were moved on. Sample files now live in the “configs/samples” directory while Super Awesome Company is in “configs/basic-pbx“.

Sample Configuration Files

The sample configuration files serve to document configuration file options or interactions in a bit more detail. They are manually modified when a new option is added or an existing one is changed. If you find that the reference documentation is not detailed enough for your liking you can look at the sample configuration file to see if more information is available that may answer a question you have about an option. The PJSIP sample configuration is a great example of this.

Super Awesome Company

While the wiki documents the Super Awesome Company use case there are actually Asterisk configuration files in the source tree which configure Asterisk to match the use case. These can be used as a basis for your own configuration as they incorporate the recommended way of doing common things.

Discourse

While not a traditional documentation source our discourse site is a treasure trove of information. You can search for questions that are relevant to what you are wanting to know more about or having a problem with.

How You Can Help

The Asterisk project doesn’t just accept code contributions. We also accept documentation contributions!

If you come across a wiki page that has an error or could be improved please leave a comment so it can be fixed. If you would like to more actively participate we can also grant wiki access for direct editing. This is not done automatically to ensure that wiki content remains of a high quality.

If you come across an error in the reference documentation or sample configuration files you can file an issue on the issue tracker and maybe even submit a change to directly fix it.

Participating on discourse is also a way to help with documentation. This helps other people out immediately but also helps others out if they go looking in the future.