[Asterisk-doc] Future of asterisk Document!

[Leif Madsen]

Comments inline

> -----Original Message-----
> From: asterisk-doc-admin@lists.digium.com [mailto:asterisk-doc-
> admin@lists.digium.com] On Behalf Of Ariel Batista
> Sent: Monday, May 17, 2004 9:44 AM
> To: Asterisk Docs
> Subject: [Asterisk-doc] Future of asterisk Document!
> 1) First problem is assuming Linux or FreeBSD or any Unix clone know-how!

Actually, that MUST be assumed.  I have seen 100's of books of how to use
Linux.  If you are new to Linux, I think you need to learn that first.  The
book will be large enough to begin with.

> There too many distro's that Asterisk is being used for that this gets
> clouded!  Let me try to explain!  Updates, CVS, Networking all play a part
> in getting Asterisk correctly up and running.  Without these covered in
> some
> way will put a person at least 2 month behind!  

The intent of the book is to learn Asterisk, not Linux.  If you need to
learn Linux, buy an Intro to Linux book.


> There is many ways to
> install and put files in Linux.  /urs/src/  /home/urs/scr /urs/local/scr
> just a few of the starting points I have found between RH 9, Fedora,
> Slackware, Debian.  FreeBSD I have never tried and frankly feel that we
> need
> to get to a point that we say this works on this and only this distro!  We
> should  tread this product like a server and just have the server do
> Asterisk! Plain and simple lets get this down to basic's.  What does a
> server do! Well you will need to have the following installed libraries.
> This is almost not stated any place. You just say pick your favorite Linux
> build and work from that! (This is wrong due to most come configured with
> either kde or gnome one them).

I agree we need to get down to basic's, but again, not in the form of Linux.
This is a book about Asterisk.  Second, why are you using KDE or Gnome on a
server?

> 2) This should be put in a easy to read format! With many examples not
> just
> do GotoIF(Condition?label1:label2)  This almost drives someone nuts!
> Remember we are trying to install this product for the first time! Not
> assuming they have programming skills!  

I am *NOT* a programmer, but I think any competent IT person needs to
understand what a variable is.

> The samples when we install
> asterisk
> and make samples have good information. But it does not explain logic that
> is needed.  We need to start listing why we do something!  This will allow
> people to learn the rules quicker.

I honestly would prefer to stay away from the sample configuration files
that come with Asterisk.  I think they are a great reference, but too many
people assume they are meant to be plugged in and used to have an Asterisk
system running in 10 minutes.  Starting from blank configuration files is
the best way to learn and not get confused (IMHO).

> 3) Index of telephone terms should be one of the first things we need to
> state. Maybe a good place to go to the back and go through the terms we
> need.  TDM, VoIp, GSM Ulaw, Alaw g.729, ztdummy,zapata after the first few
> pages we are again over loaded with new terms.  So we need to have a good
> section for the terms.

I agree that we should have a terms section, but it seems appropriate for an
appendix (we have a lot of appendices as it is now, but hopefully these
won't seem so large once we actually write some of the chapters).

> 4) Maybe we should have 2 documents.  One for the newbie which is what is
> really needed now! 2nd is for advanced users!  Lets please the first one
> first! Newbie is what we need to start addressing. In the very first pages
> we need to have links to the Wiki, (It took me 2 months to understand what
> people were saying go to the wiki) examples digiums web pages, How to get
> on
> the mailing list, how to go to the IRC all this needs to be explained.
> Also
> the correct place for getting the CVS's or RPM what ever is needed to get
> started.

Let's just worry about getting one book done first :)  As for taking two
months for what people were talking about with the Wiki... I probably would
have just asked what it was if I didn't understand.

We can combine the information from all sources to make sure we cover as
many bases as possible.  A references section seems to be appropriate, but
we are supposed to be writing out own manual.  I've been avoiding looking at
anything from the Wiki because of this.  It's not that I'm not trying to
learn Asterisk, but I just don't want to be regurgitating words that someone
else already wrote (unless they submit it to the project on their own).

Thank you for your thoughts though!  There is some good idea's in there, but
I don't think we should hold someone's hand all the way through.  We have to
assume that someone is competent enough in some aspect of computers to build
from.  If all books started from the absolute beginning, there'd be a lot of
wasted time writing information that is easily accessible by other means.

I'm not Linux *or* Asterisk guru... I'm simply trying to make some time to
help and organize a project.  It's going to be up to some of the more
advanced users of Asterisk to help me out.  I'm still learning too :)

Thanks!
Leif Madsen aka blitzrage.