On Wed, 12 Jul 2006, Leif Madsen wrote:
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)
Doxygen isn't friendly, except to us geeks. Those graphs? Not useful
when I'm writing an extensions.conf dialplan. Where is the docs on
Dial()? Can I just type "dial" in the search box and it come up with the
docs? Oh wait, no search box. Show me a page that looks like this in
Doxygen:
http://mph.gotdns.com:82/manual/en/function.dial.php
Best I could find:
http://www.asterisk.org/doxygen/app__dial_8c.html
How are #include files relevant to me using Dial() in my dialplan?
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.
That's my goal. But why not make it just as comprehensive as the PHP
documentation? http://php.net/manual/en/ Includes Install, Language
Reference (needed less for Asterisk, but AEL, variable usage and modifiers
go there), etc. That mother is comprehensive, and that's what I think we
both love about it.
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.
I have no problem breaking things up for people who are easily
overwhelmed.
I need people for each of these areas:
* Continuous Updating Application Reference to meet with current code,
both in SVN and released -- includes monitoring svn-commits list
* A masterful coder who can write scripts to scrape out things from the
current Asterisk code base, such as .conf samples, and being able to
determine when an Application came into or fell out of the code (ie
0.x, 1.x < 1.2 or 1.x >= 1.2.9)
* Anyone who wants to grab stuff from the wiki and find a good place
for it in the organizational structure
* Editors -- people who check to see if the docs are correct and well
written, suggest changes, etc.
It can't be all done at once, this is an ever-evolving project. It's
going to be somewhat thin until we get a base we are all proud of and
people start using. THEN we'll start filling portions out, updating, etc.
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!
That part is already done -- enter "Dial" in the "search for" box at the
top of the page, and Voila. I just need some people to step up to copy
the DocBook code generated by one of the Asterisk developers and edit it
into the current code to finish up the Application reference.
With that, we can launch this puppy. The question is, where...
Beckman
---------------------------------------------------------------------------
Peter Beckman Internet Guy
[EMAIL PROTECTED] http://www.purplecow.com/
---------------------------------------------------------------------------
_______________________________________________
--Bandwidth and Colocation provided by Easynews.com --
asterisk-doc mailing list
To UNSUBSCRIBE or update options visit:
http://lists.digium.com/mailman/listinfo/asterisk-doc
