[Asterisk-doc] A new contribution to the effort

[Jared Smith]

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