Re: A new strategy for internals documentation

[Stan Shebs <stanshebs@earthlink.net>]

On 8/8/13 6:29 PM, John Gilmore wrote:
> The real issue is not about where the information is stored.  The real
> issue is that people are evolving the code base without evolving the
> matching documentation.  This is accepted to be a sin with regard to
> the "Debugging with GDB" manual, which IS required to be complete,
> definitive, tutorial, and readable.  Could I gently suggest that
> contributors who make patches that evolve e.g. the symbol table handling,
> but who don't document their improvements in Gdbint, be gently reminded
> to improve and resubmit their patch by including a patch to gdbint as well?  

In theory that's always been the case, but once the manual fell out of
sync, it was easy to reply with "my change refers to material not in the
manual" or "I don't have the time nor understanding to get the internals
manual back up to date".  We also have never had consensus among the
maintainers whether this was something to enforce, and it
only take one maintainer approving patches (or committing their own)
that change the internals, and the manual immediately stop reflecting
reality.

> I started the GDB Internals manual.  Why?  Because we had no place to
> record textual explanations about why and how GDB is internally
> structured.

The ironic thing is that no one working on a new free software project
today would react to that situation by saying "we need an internals
manual".  The project would add a wiki page, send an email, or maybe a
blog posting, or a long comment block in the source code.  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, which would then be the place for the documentation about it.

While your detailed points are logically valid, we have twenty years of
empirical experience that says reality is not conforming to what we
originally imagined.  So I've suggested a Plan B where we try a couple
alternatives that are known to have a good track record in other
projects; they do not entail massive commitments or even very much
change initially.  If neither work out, then we shrug, drop them, and
think of a Plan C to try instead.

Stan
stan@codesourcery.com