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

[Peter Beckman]

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
beckman at purplecow.com                             http://www.purplecow.com/
---------------------------------------------------------------------------