[asterisk-doc] Web-based Documentation -- Need Help

[Leif Madsen]

On 7/12/06, Jim Van Meggelen <jim at vanmeggelen.ca> wrote:
> >   Have you actually looked at what I've done?  It is there,
> > just not as
> >   filled out as I think it needs to be:
> >
> >      http://mph.gotdns.com:82/manual/en/
>
> I did indeed. One of the concerns that I had was that it appeared to have a
> lot of duplication. I am not saying that that is a bad thing, but I would
> want to be absolutely clear on who the audience is. From that it will be a
> lot easier to understand what belongs in the book, and what does not. Trying
> to be all things to all people caused us a lot of problems early on in the
> docs project. The task was just too huge. If there was one thing we
> determined to do in future efforts, it was to state the audience for a
> particular volume, and make sure we stayed within that parameter for all
> effort within that scope.

Exactly! So what IS the scope of the web documentation? We already
have doxygen documentation hosted on the Asterisk.org website -- so we
don't need to cover documenting the actual functions in Asterisk --
that is already being done (although I'm sure they would love some
help fleshing some of it out from people with the know how)

What really seems to make sense for the web portion (and what I
envisioned from the beginning) is the ability for someone to type in
either a dialplan appliction or function, get some information about
it, and a simple dialplan example of how it works (a la PHP's function
search). The PHP site also has the ability for people to comment and
provide their own examples, situations and issues with a particular
function -- and this is the kind of thing I'd like to see.

The wiki makes no sense for this kind of behaviour, but with the PHP
style documentation it's a perfect forum.

So as Jim states -- a narrow, focused scope is required. You will not
be able to be everything to everyone -- we tried it, and it simply can
not, and will not, work. You will become easily overwhelmed, and
instead of contributing, as you obviously want to, there will just be
too much to do, and things will come to a grinding halt.

My suggestion is to take what I've proposed and start with that -- it
would be a huge benefit to the community! I'd love to be able to just
go to a website and type in the dialplan function or application I'm
looking for, get some information on it, and a simple example of how
to use it, and its options. That'd be a huge step forward, and
something that is totally doable!

Leif Madsen.