asterisk users - Jan 2009 - Improving asterisk documentation - sources and what the community can do

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-users/attachments/20090128/b2c1d3b2/attachment.htm

> www.voip-info.org
[...]
> 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... 
Absolutely.  
What I tend to do is the make contributions to a particular page
whenever I encountered a problem that is not documented in voip-info or
if that part is outdated.  That gives me incentive to improve that part
of the doc.

On Wed, Jan 28, 2009 at 7:56 AM, D Tucny <d at tucny.com>
wrote:
> There have been a number of comments recently about a shortage of
> documentation on Asterisk, so I wanted to cover briefly the documentation
We are drowning in it compared tot he situation four years ago when
you either read the source or suffered the slings and arrows of
outrageous IRC users on #asterisk :)
> If anyone has any other sources of information, or any other suggestions
for
> improving the documentation, I'd like to see them...
One big problem in the world is that not everyone can learn quickly
from materials written in a foreign language. It would be a kind
service to the community if those of you who know about them could
post links to foregin learning sources. Here is the only one I am
aware of:

http://www.das-asterisk-buch.de/

Stefan Wintermeyer wrote the above book and when it came out it was
also translated into English and I can vouch for the quality of the
work. Here is an article from the same folks about voice prompts, one
of many languiage-specific issues of asterisk:

http://www.amooma.de/asterisk/sprachbausteine/

/r