[asterisk-dev] Asterisk.org online Doxygen Docs

[Jonathan Rose]

----- Original Message -----
From: "Olle E. Johansson" <oej at edvina.net>
To: "Asterisk Developers Mailing List" <asterisk-dev at lists.digium.com>
Cc: "Olle E. Johansson" <oej at edvina.net>
Sent: Wednesday, October 10, 2012 8:42:41 AM
Subject: Re: [asterisk-dev] Asterisk.org online Doxygen Docs


10 okt 2012 kl. 13:40 skrev Matthew Jordan <mjordan at digium.com>:

> On 10/10/2012 12:56 AM, Olle E. Johansson wrote:
>> 
>> 10 okt 2012 kl. 04:54 skrev Matthew Jordan <mjordan at digium.com>:
>> 
>> 
>> 
>> I think you are wrong. Since there was a reduction in documentation in the source
>> code - the wiki move - it can't hurt to add. Do remember that the code lives it's own
>> life and is quite often the only thing people have.
> 
> At the same time, having things documented in multiple places is why
> things often end up out of sync.  It is a large enough task to keep
> documentation up to date and accurate in a single place; having to do so
> in multiple places doesn't seem sustainable.
> 
>> I encourage any attempt to expand the in-source documentation. I still miss the
>> channel variable document that used to live in the source. It should come back,
>> so it's always available for anyone.
> 
> The channel variable document was quite good (although it wasn't in
> doxygen either, but that's a different problem).  Most of the
> information contained in it is on the wiki; however, I'm sure there's
> something in it that isn't.  That may be the case for other documents as
> well.
> 
> In general, I'd prefer to focus on putting that information on the wiki.
> It provides much greater flexibility not only in keeping the
> information up to date, i.e., you don't have to have subversion commit
> access to make documentation updates, but it also has the ability to
> embed diagrams, code markup, tables, etc.
> 
> I understand some people prefer this information to live in the source
> tree - however, what I want to avoid is doubling the maintenance effort
> on documentation.  If there's a way to accomplish that without having to
> enter the information in multiple locations, I'd support it.
> 

Moving all information to the wiki took away an important function to keep
development resources in sync - the ability to check that documentation
followed the commit. And the wiki is still not always reachable (and last time
I checked the PDF it was horrible) in places where people work with asterisk
trying to fix bugs.

The channelvariables document was something I kept tight control over.
Every time someone committed something that touch a chan var I made
sure that it was documented. Taking it from the source added extra burden
and I haven't checked since. Importing it from the source to the wiki
makes more sense for that type of document. Updates follows the dev
process.

/O
--
_____________________________________________________________________
-- Bandwidth and Colocation Provided by http://www.api-digital.com --

asterisk-dev mailing list
To UNSUBSCRIBE or update options visit:
   http://lists.digium.com/mailman/listinfo/asterisk-dev