[asterisk-doc] Who's Willing to Contribute ?

[Leif Madsen]

Robert Broyles wrote:
> Sorry in advance for any grammer/spelling mistakes. (I've been at it for 
> almost 18 hours now.)

No problem! Thanks for getting this thread started. I have some ideas I'll be 
elaborating on in-line.

Let me start that there has been some work going on in the background to get a 
new AsteriskDocs.org site up and running which would ideally become the 
'de-facto' location for Asterisk documentation. However, that goal is a ways 
out, so lets start with just getting a site up :)  I have been working on that 
in my spare time, and have also thought quite extensively about what that would 
look like, and have spoken to many people about the way forward.

I'll explain some of my thoughts throughout this email in response to your 
questions and suggestions.

> My thoughts are basically this...
> 
> 1) We can start from scratch, and create a new single wiki, which is 
> recognized as the most comprehensive guide to Asterisk.

I've never really liked the idea of a wiki for the Asterisk community, because 
we already have one -- and it doesn't work. Most information is based on 
Asterisk 1.2, and has become quite stagnant, and is rarely updated. I think we 
need a new approach for Asterisk documentation that is not wiki based. At least 
for now.

> 2) We can expand further on voip-info.org.

Yes we could also do that. In fact I would encourage ANYONE to update 
voip-info.org in any way possible to help with the documentation front there. 
However, that is not the approach I wish to take. An Asterisk wiki already 
exists, and for whatever reason it hasn't worked until now. I'm not interested 
in duplicating effort using a method that hasn't proven itself (in the context 
of Asterisk of course -- it works great for wikipedia obviously).

> Regardless of which option we do, regular 'audits' of the documentation 
> is done, to ensure that the latest  and most accurate information is 
> available.

I agree, and I have some ways of making some of the things you mention below 
more readily available and up-to-date.

One of the things I've found that causes a great deal of inconsistency and 
errors is the fact that was have documentation for Asterisk in many locations. 
We have the source code (documentation for dialplan applications, CLI commands, 
dialplan functions, manager commands, etc...), we have the 'doc' directory in 
the source tree, we have the voip-info.com wiki, and we have the O'Reilly book.

I think the way to get all this information accurate, up to date, and consistent 
across the many platforms is to centralize the documentation somehow, or at 
least pseudo-centralize it. By doing this, we would be able to "update once, 
distribute many" so that all levels of documentation (whether they be in 
Asterisk software, in the O'Reilly Book, or on the Asterisk Docs website) are 
accurate and up to date.

This is already somewhat possible. A few developers (lead by eliel on IRC from 
what I can tell), have started with creating an XML type markup in the Asterisk 
code base which allows the documentation from the dialplan applications and 
functions (and could then be spread to the CLI commands, Manager commands, AGI 
commands, etc...) to be exported out of the source code, and into things like 
HTML pages, PDF books, etc...

Using this approach, we could use a web frame work like Drupal (to be consistent 
with the Asterisk.org site which is also Drupal based; my preference) and import 
the documentation from the Asterisk source code from the markup language, and 
get it into a web page available for wider viewing.

 From this approach, we could then use the PHP style commenting system 
(php.net), thereby allowing people to comment on errors, and provide useful 
commentary. Those comments could then be monitored by 'documentation marshals' 
who could then get the relative changes acknowledged upstream, put back into the 
Asterisk code base (central documentation repo), and from there, when the pages 
were rebuilt (nightly? weekly?) then the documentation on the Asterisk Docs site 
would immediately become up to date.

Additionally, since A:TFoT (Asterisk: The Future of Telephony) is written in 
DocBook, we could potentially synchronize the documentation from the appendices 
with the documentation in the Asterisk source code, thereby keeping changes to 
the book in sync with Asterisk documentation, and vice-versa. This would be 
advantages as any update to the book would get pushed back down to Asterisk, and 
any updates to the Asterisk source would get pushed back up to the book. Both 
locations would benefit from this.

> What information will be available?
> Everything about Asterisk.
>    - Guide to setup/install of Asterisk (Using the Realtime Engine, AEL, 
> etc)

I like this idea. I've been thinking of the Asterisk Docs website as a spot 
where articles could be contributed for guides of how to setup new features that 
are being contributed to Asterisk on a nearly weekly basis. Each new feature 
added could potentially have it's own guide (or at least article) in the site.

I'd like to see this as kind of "extending" the book so that things that might 
not fit into the book, or which people want to know more about could have some 
sort of article or guide that extends beyond the introduction provided in A:TFoT.

>    - Troubleshooting/debugging guide, common issues and their 
> resolution, etc

Again, a great idea, and could be a "book" of articles in itself. The Drupal 
framework makes this quite trivial as you can create a "book" inside, and then 
create pages that link up within the book framework on the site.

>    - Each dialplan application, explanation of it's use, it's 
> parameters/options, examples of use.

See my lengthy description above of how I imagine this to be accomplished.

>    - depreciated functions, and detailed alternative methods

This would really just be an expansion of the current documentation of dialplan 
applications, functions, etc... and simply needs us to update the primary 
locations of that documentation.

> Some of this stuff seems silly, but the point it to make the information 
> available to even the newbies. Someone mentioned in a previous thread 
> that alot of the information on voip-info.org is written for advanced 
> users, and it assumes too much about the reader, and their skillset. 
> This only leads to more silly questions from the reader.

I can agree with that. I don't believe that lowering the barrier of entry for 
users is silly at all. That is actually how the Asterisk Documentation Project 
came to be, and from that, A:TFoT.

> Anyway, this is my start. I am at least attempting to improve the 
> documentation on Asterisk.  Anyone go any other suggestions?

I have a few :)  See above!



So, how do we get where we want to go?

The first step is really to get some sort of module for Drupal that allows the 
importation of documentation from DocBook (or some other XML type markup 
language like what is being used in the Asterisk source code) into the website 
so that we can start the process of 'centralizing' the source of documentation. 
We would use the Asterisk Docs site to give access to A:TFoT, and would further 
expand on that wealth of knowledge using articles and guides which would be in a 
CMS such as Drupal. From there, other pages of reference would be built and 
imported into Drupal (read only, commenting system available), but the source of 
the documentation would live in Asterisk source code. This way the documentation 
on the Asterisk Docs site is the exact same as the Asterisk source (and thus the 
same as what you would see when you type something like 'core show application 
Dial' from the Asterisk CLI).

There is a module for Drupal called 'Book Import/Export' that may be the start 
of the framework for getting this information out of Asterisk source and into 
Asterisk Docs (see http://drupal.org/node/286592). However that module appears 
to be the start, and incomplete, so someone would have to take that on and get 
us a working module for our purposes.

Any other suggests for CMS's that already have this functionality would be 
welcome, but I've been researching (lightly) for the last few months, and have 
yet to find anything that does this.

That is where, IMHO, we have to start.

Leif Madsen.
http://www.asteriskdocs.org/