When it comes to Asterisk one of the complaints that I’ve seen over the years is that the documentation sucks or that it isn’t good enough. I’d like to show how far we’ve come as a project.
The Asterisk Wiki
Asterisk has a wiki! Did you know this? I have a feeling based on what I read that not many people do. It’s located at wiki.asterisk.org and has pages on configuration, development, releases, as well as the below generated documentation. It’s actually overwhelming how much information there is.
Within Asterisk there is documentation for everything. Dialplan applications, dialplan functions, and now in the future configuration files themselves. This is stored as XML and is used to provide the built-in help information. This XML is also parsed out of the tree and placed on the Asterisk wiki. This allows the documentation to remain in sync between everywhere. Want to see an example? Take a gander at the Asterisk 11 ConfBridge documentation.
Enforcing Documentation Requirement
Newer parts of the codebase that have XML documentation now require documentation to exist. The only way to get around it is to explicitly mark something as being undocumented. Asterisk will not start if you don’t do so. If you mark something as undocumented that should be documented you’ll inevitably get a finding during the below code review.
Code reviews don’t just encompass code, they also encompass the documentation provided with them. If something is not documented that should be or if the documentation is unclear then the documentation is changed before going into the tree.
I can’t write this blog post without recognizing that Asterisk: The Definitive Guide has helped numerous people navigate the maze that is configuring Asterisk. Go grab a copy and support the authors, who are Asterisk community members.
As you might have guessed though by the title of this post… there’s never enough documentation and the documentation that does exist can be updated, tweaked, and improved.
So where do we go from here?
What is missing? What is hidden? What is wrong?
That’s the question and where you can potentially help!
If you’d like to contribute to Asterisk documentation don’t hesitate to publish a message to the asterisk-dev mailing list. Documentation in the tree, wiki pages, anything you feel comfortable with.