[asterisk-dev] Feedback requested for future 1.6 API

[John Todd]

On Mar 2, 2009, at 4:16 PM, Tilghman Lesher wrote:

> On Monday 02 March 2009 06:18:22 am Nicolas Chapleau wrote:
>> AFAIAC, I prefer good ol' HTML pages for documentation as well as a  
>> single
>> repository (web site). Why not update the voip-info wiki to include a
>> section on changes from 1.4 to 1.6 and update it as requested? This  
>> way
>> it's dynamic (if someone updates it), simple and there's only one  
>> place to
>> go. My 2 cents worth.
>
> While voip-info.org may be a place where it gets replicated, I'd  
> prefer not
> using that site for official documentation.  Asterisk.org would  
> certainly be
> a better place, but in general, documentation that relates to specific
> releases should always be included with the release itself.  As to  
> the format,
> that really is left up to the implementer, as there are advocates  
> for every
> single format available for documentation, but nothing substitutes  
> for the
> willingness of an individual to actually put pen to paper and write  
> the
> documentation.  I'd rather have every individual advocating a  
> particular
> format to write the documentation in that format and have too much
> documentation than to specify a format that nobody has time to learn  
> and
> having none.



I'd tend to agree with Tilghman on this on all counts.

I believe that any download of the source should include as full a set  
of documentation as would be required by a developer to understand and  
evaluate the code.  (Note that this is different than "How to use  
Asterisk", which is possibly better handled by multiple external  
resources like websites, books, videos, etc.)

I also believe that the format should be simple, or well-known, or  
both.   We've been using doxygen - is this too complex a markup  
language such that it discourages people?

I think the OpenDoc format included with the distribution is  
admirable, but I think it introduces another format that perhaps is  
designed for purely human consumption - or am I wrong?  It seems that  
doxygen is easily parsed into other formats.  I don't know if it  
passes Tilghman's tests of ease, though.  I would suggest that at  
least everyone attempt to write docs in some standard format, but if  
that is too difficult then "some" is better than "none", no matter  
what the format.

JT

---
John Todd                       email:jtodd at digium.com
Digium, Inc. | Asterisk Open Source Community Director
445 Jan Davis Drive NW -  Huntsville AL 35806  -   USA
direct: +1-256-428-6083         http://www.digium.com/