I’ve grown fairly accustomed to the fact that most Open Source projects tend to have a poor documentation. Sure, if you look at the code itself, you’ll find a plethora of code documentation, explaining how certain pieces of the code work, however, when it comes to operational documentation – that portion lacks tremendously.

In this case, I’d like to examine two of the Open Source projects I’ve lately been utilizing more and more, mainly Kamalio (AKA: OpenSER) and AdHearsion. These two project represet two edge cases in the Open Source world. While OpenSER is strictly a SIP Proxy and Registrar, controlled entirely by a configuration file and database, AdHearsion is a programmatic API based on Ruby, built to provide developers an easy traversal into the Asterisk and Open Source telephony application development world.

Kamalio (AKA: OpenSER)

While Kamalio (AKA: OpenSER) is one the more popular SIP proxies of the world, it’s documentation lacks proper configuration examples. If you visit the Kamalio project website, you’ll find a mixture of documents, describing the various features and how to activate these. You will find some simple to following guides on how to integrate Kamalio with other projects, such as Asterisk – however – there are no easy to follow, beginner level tutorials.

This reminded me much of the Asterisk early days, where the dialplan language seemed like this horrific mixture of INI type directives and formats and the logic behind it illuded most people. As time progressed, many people started donating documentation and configurations examples to these, many companies started rendering Asterisk support and consulting services and slowly Asterisk became more and

more widely adopted.

For some strange reason, the community surrounding the Kamalio project doesn’t provide documentation that is usable by newbie users. Think about it, if I’m a newbie user, what kind of documentation am I looking for:

• Compile, install and execute Kamalio correctly – documentation for this is available.
• Setup a basic system for routing calls between registered users – documentation is available.
• Setup a basic system to route calls outbound to the PSTN – documentation missing.
• Setup a basic system to support Radius based AAA functions – documentation missing.
• Setup a basic system to support internal and external call routing – documentation missing.

In other words, three of the most basic tutorials are simply missing. One may argue that Radius isn’t basic and that MySQL support is more basic and provided – true. However, if I’m trying to integrate Kamalio into an existing ISP/Carrier infrastructure, it is fairly basic that I already have a RADIUS server on the network – and I’d like to use that.

The only piece of valid documentation that I managed to gather was a book from Packt Publishing called: “Building telephony systems with OpenSER”, and even that talks way too much about MySerWeb, a WEB based frontend to OpenSER.

Adhearsion

I admit it, I’m an Adhearsion newbie – well, I’m also a Ruby newbie – but that’s something completely different. Before we start talking about Adhearsion’s documentation, let’s talk about something really annoying about the Adhearsion website – the URLs are confusing!

If you go about and browse to http://www.adhearsion.com, you are automatically redirected to http://jicksta.com/, which is Jay’s blog. Now, as much as I do respect Jay, this is a really weird way of getting people to visit your blog – isn’t it? Now, if you visit http://adhearsion.com, you reach your true destination – The Adhearsion project home page. Ok, I may be nitpicking here – but I’ll write this off as a configuration error somewhere (DNS, Apache, index file, etc).

Now, Adhearsion is a wonderful example of how to do documentation for a project: easy to follow tutorials, a full API documentation (slightly complicated to follow, however), an installation guide that even a newbie can follow in 5 minutes – in other words, all the makings of a really usefull tool, built by people who have usability and ease of development at their priority.

I really hope that as time progresses, we’ll see more documentation on the Adhearsion website, especially one that is pointed at real newbies. A tutorial that I feel is in order is “Adhearsion for PHPAGI developers”. The traversal from PHP to Ruby is hard enough, so traversing from PHPAGI to Adhearsion is a complete change of though patterns and skill sets.

You are probably wondering why I’m talking and learning Adhearsion, after all, I did write a book about PHPAGI. Well, after meeting Jason Goecke at Amoocon, I’ve been convinced by him to give Adhearsion a try – and I’ve decided to adopt it. I’ll be launching the www.adhearsion.org.il soon (well, at least the minute I fee comfortable with Adhearsion).