[asterisk-dev] Asterisk.org online Doxygen Docs

[Matthew Jordan]

On 10/02/2012 08:50 AM, Andrew Latham wrote:
> On Tue, Oct 2, 2012 at 9:43 AM, Andrew Latham <lathama at gmail.com> wrote:

> 
> BTW
> 
> One page I did add last night was
> http://www.asterisk.org/doxygen/trunk/asterisk_community_resources.html
> and I would enjoy feed back to the ticket
> https://issues.asterisk.org/jira/browse/ASTERISK-20259 if you feel
> something needs added, removed or updated there.
> 

So, I'm not entirely sure that the Asterisk Community Resources page is
appropriate for doxygen documentation.

1) It reproduces content already on the mailman list page - which is
linked from that document.  If lists are added or removed, the content
in doxygen is (once again) out of date.  In general, information should
only exist in a single place.

2) Community members may find their way to community related information
via files included with the source, but they're much more likely to find
it via a more traditional website.  Having it in doxygen once again
results in reproduction of information.

While I'm thrilled that you've taken on a lot of documentation cleanup
work, I think we need to be careful about reproducing documentation that
either already exists or belongs in a different location.  In general,
the doxygen produced documentation is a resource that documents and
tracks the version of the code its associated with.  This means that
while its appropriate for documenting the APIs (headers) in Asterisk, I
don't think its appropriate for information that does not uniquely
reside in the Asterisk repository.

-- 
Matthew Jordan
Digium, Inc. | Engineering Manager
445 Jan Davis Drive NW - Huntsville, AL 35806 - USA
Check us out at: http://digium.com & http://asterisk.org