[Asterisk-doc] As promised, some internals docs

[Jim Van Meggelen]

asterisk-doc-bounces at lists.digium.com wrote:
> Made 2 commits today. One was the initial outline from Nick
> Bachmann. The second was my format section.
> 
> As a first run, please give feedback on style and all as I
> feel it may need more direction.

This looks like the foundation of the perfect evolution of the work
begun in Volume I. I guess this'll be Volume II in the libarary (do we
want to get this on the website?).

One of the things we found when we began Volume I was that the problem
with trying to document Asterisk was simply too huge. What we did was
define some potential audiences for Asterisk documentation (newbies,
technicians, developers, hobbyists, etc.) and select the audience that
we felt was most in need. The next step was to develop a reasonable goal
for our audience to achieve by reading our book, and focus exclusively
on that. 

We decided that Volume I (which still needs a title, really) would be
addressed to newbs. More specifically, the audience for Volume I was
someone with Linux know-how, but almost no Asterisk experience, and the
goal was to walk the reader through the creation of an Asterisk system
with FXO, FXS, IAX and SIP interfaces. The document would deliver a
basic, working Asterisk system, with the reader having experienced a
rudimentary walkthrough of key steps in the process of building an
Asterisk PBX.

For Volume I, we always found it so much easier to perform editorial
tasks because the most wonderful stuff would sometimes be removed simply
because it did not fit the audience or goals. This would usually end up
getting dumped in the Hitchhiker's Guide, so that someone later on might
find a way to make use of it, but volume one would always have clearly
defined prameters that we could refer to when deciding what belonged,
and what did not.

In the same vein, I imagine that Volume II: Asterisk Internals needs to
have a specific audience and a specific goal that will have been
achieved when the reader has finished the book. Is this to be a
reference guide? Or a more in-depth continuation of Volume I? Either
goal would be valuable (many others come to mind as well), but the kind
of scope-creep that made the Hitchhiker's Guide so cumbersome will be a
constant danger here as well, unless the audience and goals are defined
right from the beginning.

Jared, Leif and I have had numerous conversations about the goals of the
documentation project, and we are delighted to see that the dream of a
library is taking shape with efforts such as yours. What we envision is
an environment where future contributors can quickly decide where to
submit work that they are creating. If the goals and audience for each
document are clearly stated, an author can then determine whether what
they want to do would best be added to an existing work, or whether a
new volume is needed.

>From the layout I've seen so far, the audience for Volume II might be
someone who is interested in understanding the development of Asterisk,
and wants to know how to contribute. Almost a -dev newbie as opposed to
a -user newbie. The goal might be to provide an understanding of the
technologies in use in Asterisk, the cultural environment of each
component (everybody loves IAX - many (most?) hate H.323 - nobody
understands Sphinx), and perhaps suggestions as to where contributions
are most needed. A discussion about STABLE vs. HEAD from a developer's
perspective (perhaps mentioning the Asterisk Mainenance Crew) might fit
in somehow as well. I betcha a discussion on licensing would be fun for
somebody ;-P

I don't want to say that this *should* be the goal - I'm just
brainstorming here. Personally, I feel that the Author needs to the
final authority on the goal, as it's the passion for the subject that
drives the effort. With multiple authors, the goal is simply decided as
a team. If agreement cannot be reached, that might be a good thing, as
possibly what we have are the seeds of two books!

Anyhow, this is fantastic stuff, and looks poised to take AsteriskDocs
to the next level!

Regards,

Jim.


--
Jim Van Meggelen
jim at vanmeggelen.ca

-- 
No virus found in this outgoing message.
Checked by AVG Anti-Virus.
Version: 7.0.300 / Virus Database: 265.8.5 - Release Date: 03/02/2005