On Fri, 26 Oct 2007, Diego Novillo wrote: > So, I think the problem goes a bit beyond mere documentation of how a > module works at a high level. I would like to have a navigable > document that also describes the flow of things, interfaces and > helpers. Starting at main.c:main() and ending at toplev.c:finalize().
Something like this is a key element for documentation, but it's hard to do the way we have been documenting things indeed. That sounds like a very good idea. > - Navigable. That seems to ask for, at least on the module level and below, for something similar to literary programming or we'll run out of sync quickly. > - Close correspondence to mainline. > > This is where it gets hard. We need to have a way of enforcing code > updates that change internal or external API properties to be > reflected in the document. With this I don't mean that every single > patch should be accompanied with a documentation change. However, if > a patch refactors a module and its internal interfaces are changed, > then the patch should be accompanied with a change to the > documentation. I guess that's my main concern as well: how can we keep the various bits of documentation -- comments in the code, texinfo, and your proposed one -- in sync and do so without adding much effort for individual contributors? Another concern is the question of copyright assignments. We are requiring these for texinfo changes, but do not have anything in place for the Wiki. If we now get significantly improved documentation on the latter, we may not be able to move that into the regular manuals. Is this an issue? Gerald
