[asterisk-doc] I am new to asterisk..Please help me..

[Peter Beckman]

On Tue, 11 Jul 2006, asterisk wrote:

> Peter Beckman wrote:
>>>> What I am seeing is that you guys are (mostly) still alive! :) This is
>>>> about the quietest list in the civilized world.
>>>
>>>   Wow, this is the first thread on this list in a long time.
>>>
>
> we are quiet because we are very busy and hard working (around VoIP,
> Asterisk, Internet, e.t.c), and maybe talking not enough.

  Trust me, I'm not just sitting here playing Sudoku waiting for a reply. :-)

> But I think this discussion means we think documentation is VERY
> important part of Asterisk.  There is some old rules about this:
>
> 1. Make documentation in parallel with coding.

  That's the goal of my project -- build the docs in DocBook XML format,
  build tools around it to export it into whatever -- HTML, Text, PDF.

  Then once it is up-to-date or as close as it can be, focus on getting
  developers to mark their svn-commits with some sort of key sequence such
  as *d* or *D* to mark the commit as a change in the way asterisk works or
  in documentation.

  Then we just monitor the svn-commits list, create a ticket for every *D*
  svn commit, and then modify the docs or close the ticket if no changes
  are needed.

> 2. Make docs even before coding.

  Good luck.  I don't know if the dev team writes docs before coding, but I
  haven't seen where they do it if they do.  Not that that is bad, but I
  think it is a pipe-dream anytime soon.

> This is because you have to know where are you going and documentation is
> your roadmap.

  Leave that to the -dev team -- they seem to know where they are going.
  Their system just doesn't generate the kind of documentation I hope for
  Asterisk, which would include examples, caveats, links to other
  applications, etc.

Beckman
---------------------------------------------------------------------------
Peter Beckman                                                  Internet Guy
beckman at purplecow.com                             http://www.purplecow.com/
---------------------------------------------------------------------------