[Asterisk-doc] A new contribution to the effort

[Peter Grace]

Ping!  Haven't said hello in many months, I'm lurking on the list.

Hell, it looks good to me.   I agree that keeping the terms in there is 
better than "dummying it down" -- it's better to have documentation 
jam-packed with knowledge as long as there's a reference section to 
explain what each term is.  Better to have a technical manual than a 
"rah-rah this is great, but we wont tell you precisely why!" kind of 
document.

Leif, I haven't forgotten that I owe the project a few sections on HDLC!

Pete (km-)

Jared Smith wrote:

>On Thu, 2004-07-15 at 21:48 -0400, jim@digitalchemy.ca wrote:
>  
>
>>I'll do what I can. The XML-ish documentation format is still a bit strange to me so if it 
>>works for you I'll just post whatever I've got to the list as text. Meantime I'll see if I 
>>can get CVS figured out.
>>    
>>
>
>Yes, the XML-ish format (known as DocBook) is a little strange, but
>doesn't take long to learn.  In the meantime, feel free to post plain
>text to the list and either Blitzrage or myself will convert them to
>DocBook.
>
>There should be some basic instructions for CVS on the website.  If
>something doesn't make sense, just ask on the IRC channel.
>
>
>  
>
>>Yeah I know what you mean. I found a few sentences were a bit heavy. On the other 
>>hand, only a few paragraphs on and we're telling the reader that they'd better 
>>understand Linux and Telephony if they want Asterisk to make sense. So we're not 
>>introducing anything in the intro that isn't prerequisite knowledge anyhow. 
>>    
>>
>
>Hmmmn... just because a person has some basic telephony knowledge
>doesn't mean they know what these are.  On the other hand, we'll have a
>glossary they can use to look terms like these.  They're probably fine
>like they are.
>
>  
>
>>With any body of writing one has to decide who the audience is and write for them. If 
>>we're assuming telecom knowledge, then I'd argue that PRI, IVR and CTI are terms 
>>we can reasonably expect the reader to be familiar with. 
>>    
>>
>
>I'm assuming *basic* telecom knowledge, but a lot of our audience will
>never have touched a PRI or a channel bank or know the difference
>between FXO and FXS.  If they already knew all that stuff, they probably
>wouldn't need a book like this to learn Asterisk. :-)
>
>  
>
>>If it's generally felt that those terms are too heavy for the intro then I'll have another 
>>go at the relevant sentences. 
>>    
>>
>
>I think they're probably fine.  I propose we leave them in there.
>
>-Jared
>
>_______________________________________________
>Asterisk-Doc mailing list
>Asterisk-Doc@lists.digium.com
>http://lists.digium.com/mailman/listinfo/asterisk-doc
>  
>