[Asterisk-doc] I'd like to "Get Involved" :-)

[Leif Madsen]

On 3/28/06, Peter Beckman <beckman at purplecow.com> wrote:
>  Though not very useful for those of us who just want very fast, HTML-based access
>  to functions, config files, etc.  Have you ever seen the PHP.net
>  documentation?
>
>  Go to php.net/substr and it takes you directly to a page all about the
>  substr function.  Examples, notices about versions this function is
>  supported in, caveats, comments, etc.
>
>  That's why I want to help write DocBook-based documentation for Asterisk,
>  so Asterisk can have the same, easy to read, online documentation.

Fantastic idea!!!

I have a few issues with the idea though.

First -- what does PHP.net use for their backend to control all of this?

Second -- how do they keep PHP documentation current / in-sync with
that which is distributed with PHP itself?

Third -- Does PHP use DocBook to control all this documentation
content? If not, what do they use, and how easy will it be to allow
certain people access to changing things directly -- what about
community submitted documentation? Would be nice to allow people to
submit corrections, but allow the administrators the ability to
approve / review submissions before they get "published"

I really like the idea, especially since php.net has the nice feature
of allowing people to post to the various functions with comments that
usually includes useful examples of how to use the function. I can
envision the same thing for the dialplan functions and applications.

How might we approach the configuration files and the options
associated with them in this manner as well -- the php.net style seems
like it'd work well with the dialplan applications and functions, but
not sure about the configuration files themselves.

I like the idea -- lets see if there is a relatively easy way to
implement it without requiring much in terms of overhead work with
most time spent actually writing the documentation (and not dealing
with DocBook syntax etc.. which I think turns off a lot of people).

I'm not opposed to changing the backend if it would help.

Leif Madsen
http://www.leifmadsen.com
http://www.oreilly.com/catalog/asterisk