[asterisk-dev] How much backporting of Doxygen updates should I do?

[Matthew Jordan]

On 10/30/2012 10:56 AM, Andrew Latham wrote:
> All
> 
> I have been hammering away on the Doxygen docs and still have a lot to
> do.  I have stripped away layers of defunct documentation and noted
> where there are swaths missing.  How far back in the Asterisk branches
> should i push my updates.  A large portion of the work is _NOT_ code
> specific.  For example many text files were removed in the 1.6.2
> release but still mentioned in the Doxygen documentation.

I think I might need to clarify something here again.

Documentation that is not code specific should not duplicate content
anywhere else, particularly content that exists on the Asterisk website
or the Asterisk wiki.  (The same, in reverse, applies to code
documentation - but that's a different story).

The reason why that content was removed may be a bit murky, but for
several years now the content has been migrated to other sources.
Reversing this change is not appropriate.  Having content duplicated is
not appropriate.

If you would like the content on the wiki delivered with the source
that's fine - a roundtrip mechanism can be worked out that exports the
content into the source tree.  But wholesale replacing the /doc folder
was not the intent of the janitor project on the wiki, nor is it a
change that I want to see occur.

All that being said, if the content does not belong on the Asterisk
website or the Asterisk wiki, then its certainly a candidate for
inclusion in the Asterisk source.  However, I feel like we're getting
dangerously close to including content that was removed from that
location a long time ago for a reason, and I really don't want to have
that debate again.

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