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

[Jim Van Meggelen]

> -----Original Message-----
> From: Peter Beckman [mailto:beckman at purplecow.com] 
> Sent: July 12, 2006 2:01 PM
> To: Discussions regarding The Asterisk Documentation Project
> Subject: RE: [asterisk-doc] Web-based Documentation -- Need Help
> 
> On Wed, 12 Jul 2006, Jim Van Meggelen wrote:
> 
> > The thing to avoid is to write what has already been covered 
> > elsewhere. What goes in asteriskdocs should be what is 
> missing from A:TFoT.
> 
>   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.

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.

> > We are working on a cookbook for O'Reilly, which will not hit the 
> > shelves for a while; so rest assured there is writing going 
> on, just 
> > not here. I do not have enough bandwidth to write more than 
> I already 
> > am, but I would be delighted to provide some editorial assistance. 
> > People probably don't realize how an editor can fix up a lot of the 
> > stuff that makes people think they can't write. If someone 
> takes the 
> > time to write something, even if it has poor grammar and spelling 
> > mistakes and would upset your English teacher, it is no big 
> deal. That can easily be fixed during the editing process.
> 
>   Amen.  Editors are needed.

Writers are needed more!

> > One person I think we should try to rope in is Ira. He say he can't 
> > write but from what I have seen I beg to differ ;-). Also, 
> he has some 
> > good ideas about what was missing from A:TFoT, which is 
> exactly what 
> > we want to move towards.
> >
> > A section of all the asterisk functions, and neat stuff that can be 
> > done with variables would be useful.
> 
>   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.

Jim



-- 
No virus found in this outgoing message.
Checked by AVG Free Edition.
Version: 7.1.394 / Virus Database: 268.9.10/386 - Release Date: 12/07/2006