[Asterisk-doc] Future of asterisk Document!

[Jared Smith]

On Mon, 2004-05-17 at 14:37, Leif Madsen wrote:
> Comments inline

My comments are gonna be inline as well...  Let's see if I can confuse
everyone by writing back to everyone at once. :-)

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

Yes, I completely agree.  This book is not going to be a "learn linux
and asterisk at the same time" kind of book... it's going to be more of
a "Learning Asterisk for people who already know how to get around in
Linux" book.  If you'd like to write a "Here's all the Linux you'll need
to know to start using Asterisk" book, be my guest.  We've already got
more than enough material to cover, without teaching people how to use
Linux.

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

As I see it, we'll mention a few of the common Linux distributions that
are known to work with Asterisk.  And we'll explain how to check out the
latest version of Asterisk from CVS.  But we're not going to into how to
setup networking under Linux.  If you don't know how to setup networking
under Linux, go buy a book or use google *BEFORE* you even think about
setting up Asterisk.  Would you expect an Apache book to explain how to
setup networking and/or which distribution to use?  Of course not.

If it takes someone two months to learn Linux basics before they start
learning Asterisk, then it's two months well spent.  People *should not*
get the impression that they can setup an Asterisk system overnight with
no previous experience... it just ain't gonna happen.

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

Well said.  'Nuff said.

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

Yes, we'll cover some basics such as required librarires, where the
files get installed, etc. in the installation chapter.  But again, we're
writing this assuming that the reader knows how to manage his own
system.

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

We will definitely explain what a variable is, and hold their hand
through the first extensions.conf chapter.  I want that chapter to be so
blatently obvious that 60-70% of readers will just gloss over it and go
on to the next chapter.  But yes, the reader should have some basic
understanding of programming logic.

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

I agree that we should start from a blank extensions.conf file and work
from there.  At one time, I had the first extensions.conf chapter with a
bunch of *really* simple examples and copious explanation, but someone I
seemed to have misplaced the file before it got checked into CVS. 
Blitzrage, did I happen to send it to you?  (It would have been called
extensions2.xml)

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

There's already a glossary in the back of the book.  Now we just need
people to fill it up with terms!

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

Maybe there's a need for a second document... I don't expect this book
to be perfect for both newbies and gurus.  There's no way we can make
everybody happy.  So again, we've decided to limit the scope of the
documentation to people who already have *some* Linux experience, but
might be new to Asterisk (and telecom in general, from the other emails
I've received).

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



Jared