Re: A new strategy for internals documentation

On Fri, Aug 9, 2013 at 3:31 PM, Stan Shebs <[email protected]> wrote:

>  If there were
> a half-dozen files to edit in sync, these days there is more likely to
> be intense pressure to refactor that code and bring it back down to one
> place to edit

to me this is the most important thing, that anything that belongs in
the source code, shouldn't need to be duplicated in the manual, and
have to be kept in sync.  I personally don't care if that manual is
wiki/texinfo but by removing all the stuff thats already in/belongs in
the source code, the manual will be smaller and easier to keep in
sync.

as I said I don't care much about wiki/texinfo argument but it would
be nice if the manual could link directly to the doxygen
documentation, in those places where there is currently duplicate
information.  The wiki makes that very easy with hyperlinks,  If its
easy with texinfo thats fine with me too...

I don't think doxygen is the greatest thing ever, but if it gives the
internals manual an iota of a chance at staying relevent by drawing a
line in the sand the manual does not cross and reducing the churn, it
will be worth its while.