[Asterisk-doc] A new contribution to the effort

[William Suffill]

Wow Pete returns from the shadows. Glad to see ya back.

On Fri, 16 Jul 2004 14:03:27 -0400, Peter Grace <pgrace@fierymoon.com> wrote:
> 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
> >
> >
> 
> _______________________________________________
> Asterisk-Doc mailing list
> Asterisk-Doc@lists.digium.com
> http://lists.digium.com/mailman/listinfo/asterisk-doc
>