[asterisk-doc] Improving asterisk documentation - sources and what the community can do

[D Tucny]

Hi All,

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

Documentation sources:
http://www.asteriskdocs.org/
- Not much there at the moment, due to come back up with new content in
2009...
- Should be a good location for concentrating documentation effort
- links to the Asterisk Book
- asterisk-doc mailing list exists too, but, also seems dead...
- Difficult to see how to contribute at the moment

The Asterisk Book (2nd edition)
- Available to buy and to download for free as a PDF
- Provides a good overview of the concepts for manager/beginner level
- Provides a guide to getting Asterisk up and running
- Refers to a single version of asterisk (1.4)
- Is a static document with a reasonably long release cycle
- Difficult to see how to contribute

Docs that come with asterisk
- README contains basic installation process
- UPGRADE-* covers some of the changes between major versions
- docs/* has a range of docs, some out of date and with holes in it's
coverage
- 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
- Updated documentation can be fed in by the community through patches and
additional docs

www.voip-info.org
- Variable levels of information about different topics, some detailed, some
with hardly any information
- Missing information, no content at all for some
commands/functions/features...
- Inconsistent information, different pages say different things about the
same thing...
- Lack of detail about applicable versions, not always obvious that things
have changed between versions or have been removed or deprecated
- Structure has become a bit messy and could use some attention
- Some large pages that can prove troublesome to update
- Should be able to hold as much information as anyone would want with full
details, examples and highlighted version differences...
- Generally easy for anyone to update if they register an account

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

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 www.voip-info.org 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...
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...

If anyone has any other sources of information, or any other suggestions for
improving the documentation, I'd like to see them...

d
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.digium.com/pipermail/asterisk-doc/attachments/20090128/b2c1d3b2/attachment.htm