[asterisk-dev] Asterisk.org online Doxygen Docs

[Leif Madsen]

On 10/10/12 07:40 AM, Matthew Jordan wrote:
> On 10/10/2012 12:56 AM, Olle E. Johansson wrote:
>> 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.

100% agreed. If the documentation is in more than 1 place, then you're 
doing it wrong.

>> 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.

Also agreed. I thought we were exporting the documentation in the wiki 
into PDF and TXT files at one point to satisfy the requirement of 
permitting documentation to be distributed with releases at the least?

-- 
Leif Madsen
http://www.oreilly.com/catalog/asterisk