Hi All,<br><br>There have been a number of comments recently about a shortage of documentation on Asterisk, so I wanted to cover briefly the documentation options available and suggest what they are useful for and how they can be improved...<br>
<br>Documentation sources:<br><a href="http://www.asteriskdocs.org/">http://www.asteriskdocs.org/</a><br>- Not much there at the moment, due to come back up with new content in 2009...<br>- Should be a good location for concentrating documentation effort<br>
- links to the Asterisk Book<br>- asterisk-doc mailing list exists too, but, also seems dead...<br>- Difficult to see how to contribute at the moment<br><br>The Asterisk Book (2nd edition)<br>- Available to buy and to download for free as a PDF<br>
- Provides a good overview of the concepts for manager/beginner level<br>- Provides a guide to getting Asterisk up and running<br>- Refers to a single version of asterisk (1.4)<br>- Is a static document with a reasonably long release cycle<br>
- Difficult to see how to contribute<br><br>Docs that come with asterisk<br>- README contains basic installation process<br>- UPGRADE-* covers some of the changes between major versions<br>- docs/* has a range of docs, some out of date and with holes in it's coverage<br>
- embedded documentation as seen with core show application and core show function, good basic reference information, but, not always the most convenient place to get to it<br>- Updated documentation can be fed in by the community through patches and additional docs<br>
<br><a href="http://www.voip-info.org">www.voip-info.org</a><br>- Variable levels of information about different topics, some detailed, some with hardly any information<br>- Missing information, no content at all for some commands/functions/features...<br>
- Inconsistent information, different pages say different things about the same thing...<br>- Lack of detail about applicable versions, not always obvious that things have changed between versions or have been removed or deprecated<br>
- Structure has become a bit messy and could use some attention<br>- Some large pages that can prove troublesome to update<br>- Should be able to hold as much information as anyone would want with full details, examples and highlighted version differences...<br>
- Generally easy for anyone to update if they register an account<br><br>So, the easiest way that people could contribute to improving Asterisk documentation right now would appear to be by improving articles on www.voip-info.org... <br>
<br>It would still be good to get the documentation process back up and running, but, until that's there, I'd like to propose that people have a look over the content at <a href="http://www.voip-info.org">www.voip-info.org</a> and see if there's anything they can see that could be improved... It would probably be useful to have templates of some sort for things such as applications and functions, but, I'm not sure how easy they are to setup with the wiki software in use there, I'll have a look in a bit, but, if anyone knows, some info on that could be a useful start...<br>
I've already spent some time trying to update some of the reference info, such as making a start on updating the applications page, but, there is so much that could be improved that all together, there will be quite a lot of effort involved in getting it tidy... I'm going to continue to work on it, but, if others also dig in it shouldn't take too long to get the reference documentation there up to a decent level...<br>
<br>If anyone has any other sources of information, or any other suggestions for improving the documentation, I'd like to see them...<br><br>d<br><br>