[asterisk-doc] Web-based Documentation -- Need Help
Peter Beckman
beckman at purplecow.com
Wed Jul 12 19:13:49 MST 2006
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/
---------------------------------------------------------------------------
More information about the asterisk-doc
mailing list