[Asterisk-doc] Future of asterisk Document!

[Steven Critchfield]

On Mon, 2004-05-17 at 08:44, Ariel Batista wrote:
> Sorry that this is a new thread! But the one over the conference did not
> seem correct for my statements.  Please note that I am fairly new to
> Asterisk about 10 months and only about the same for Linux!  With very
> little known about telephones.  I come from the Microsoft Network
> Engineering Group. (MSCE, Citrix, Novell (from 2.1 to 5.0)  I have been
> working with networks for more then 16 years now! So there is some
> information about Linux has filter in during that time.  But I am what you
> call the normal IT person that would be in charge of the new companies
> Internet/Software phone switch! I lost allot of time due to there is no real
> documentation.  I almost just pulled the plug on this installation due to
> this!  I found out about the Sunday night call this morning! I don't check
> my emails during the weekend.  Most IT people leave work and hope to forget
> it during the weekend.

I think you should realize that you have lived in your own echo chamber
for what is normal. While I don't know if it is normal, just about every
person I know that is in IT is available through the weekend as well.
The difference is that we may not be monitoring our work mail, we are
monitoring some email address. Then again, about every one I spend very
much time with are hosting providers of sometime and we all end up
updating stuff on our private sites through the weekend as well.

> 1) First problem is assuming Linux or FreeBSD or any Unix clone know-how!
> 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!  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).

There are books already written for using CVS, distro support, and any
number of normal linux usage. I think our current scope of covering
asterisk will be more than enough. I have an emense amount of shelf
space devoted to unix topics and programming language. I don't need
another book to cover the simple things about linux in detail just to
get the need information. We don't need to specify a specific distro. I
doubt everyone here would agree to what is the right distro, and we need
everyone here to contribute, not argue.    

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

Please check out what has currently been written. There is already a
fair amount written, and I think we have good examples in the sections
that need examples.

> 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 I'm not on track with the rest of the intent anymore, but I think
we are striving for deadtree documentation. I don't think we will go for
writting two books.

-- 
Steven Critchfield <critch@basesys.com>