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

[Peter Beckman]

On Wed, 12 Jul 2006, Jim Van Meggelen wrote:

>> I disagree.  While it makes no sense to write what can be copied, I
>> think having a location to have as much as possible is the goal.
>
> I agree, but A:TFoT is already there, so why repeat that? I guess our
> goal was to produce an Asterisk library, so since we have the first book
> (and it's audience covered), why not move on to the next thing.

  Because (a) it's not in a web-friendly format, (b) it's searchable only
  within Acrobat, (c) Google doesn' index it, (d) there is no Table of
  Contents.

  I think the content is great, but accessability and organization is
  needed.

  If we get to the point where stuff we're writing is covered in your book,
  I'll formally ask permission to skim it for inclusion.

> The audience for the next book that the docs project should address would
> be those folks who have successfully gotten Asterisk up and running, and
> want to take their skills to the next level.

  And that's great -- I'm building a reference library.  If you need to know
  something about extensions.conf, there is a section for you.  If you need
  to know the current working parameters for Dial, they are fully
  documented on a single page.

> Writers are needed more!

  Sure, but as you've pointed out, a lot of documentation is already
  written, it just is spread all over the place -- the wiki, the docs in the
  Asterisk code, the A:TFoT book, etc.  I'm working on trimming and
  unifying, so editors are very useful.

  Copy-and-pasters are good too!

>> 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.

  I'm not looking to write a book.  Books can quickly fall out of date, as
  you've said.  When you wrote the book, 1.2 wasn't even out, and now we're
  at 1.4, and the book hasn't been updated.  This is a reference manual.

  I want this documentation to be an ever-evolving beast, that updates as
  the code changes, documents change-in-user-interface history, etc.  It
  keeps up and outlines new features, etc.

  Much of the work and framework is already done.  Now it just needs to be
  filled out, some more automation built, and some coordination with
  developers to make sure the docs stay up to date with the code.

  The audience?  Anyone who is using asterisk.  It's a reference manual that
  includes simple installation procedures, caveats, and simple usage
  examples for coding Asterisk.

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