[Asterisk-doc] "The Extensions.conf Cookbook" chapter

[Greg Varga]

On Tue, 30 Dec 2003 10:16:06 -0700, Jared Smith wrote:

[snip]
>> It might be a good idea to pick Marks brain and see if the function
>> style is the preferred method for the future and stick to just that
>> method. Maybe a note about old methods, but all examples should fit to
>> the preferred method. It ties into my comment about consistent spelling
>> and capitalization. It should be fairly difficult to tell where
>> different authors start and stop other than maybe a few nuances in word
>> choice or sentence structure.
>
>Agreed. Do we do Dial(foo|bar|widget) or Dial(foo,bar,widget) or
>Dial,foo,bar,widget?  I know which one I prefer... What do the rest of
>you think?

I think we should standardize the doc to one way (personally I don't
care) but tell the readers that they can use whatever format they want
- and list those formats.

I'm a coder, so I use the Dial(foo,bar,widget) way, but thats just me.
:)

[snip]
>Maybe we need two cookbooks... a "Gentle Examples for Beginning Cooks"
>chapter and a "Awesome Recipes for Experienced Chefs" chapter?  Or
>should we just make one giant cookbook, that starts off simple and then
>gets hairy at the end?

Hmmm I like the first personally... But thats only because I learn this
sort of stuff really fast.  So I do an overview of the "basics" and
move on to the "advance" stuff asap.  But other then that, I can use
either layout.


>> While this might be helpful, but in a print form this is a lot of space
>> that is not much more than what the cookbook and a few pieces will be.
>> Not to mention there is a sample that comes with the asterisk source. 
>
>Unfortunately, the sample that comes with the asterisk source has very
>little explanation.  Somewhere in the book we should have a couple of
>well-documented sample configurations, so that people can at least get
>to the "Look! I made a phone ring!" stage.  I don't really care if this
>gets pushed to an Appendix or maybe even just the website... but it
>ought to be *somewhere*.  (Or, maybe we just point them to one of the
>other third-party Asterisk websites?!?)

I think the book should have the sample configs.  I'm not talking about
"Hey, here is a load of sample configs that have comments in them!"...

What I was thinking was we could put down two or three example
configurations in an appendix, all with network/server layouts,
configs, and all the documentation that is required.  Then throughout
the whole book, we can refer to those configs so any of our examples. 
Stating partial config's when we need to, and refering them to the full
blown config in the appendix.

So, for example...  The first "Config" would be very simple and would
be the most used example throughout the book. This example would be the
"Starter Kit".  A second config might have a T1, etc.   A Third config
might have multiple Asterisk Servers, the ability to do Fall Over to
other servers, etc.

We would - of course - also offer online in a downloadable format for
their ease.  This would allow the book to be very structured, and easy
to read because the reader would not have to worry about 100 diffrent
example configs/setups because 100 diffrent people wrote the book.


--Greg
-------------------------------------
Greg Varga
Author for RocketryNews
http://www.rocketrynews.com
CAR # 677
-------------------------------------