Wiki and docs in cvs
wbh at conducive.org
Mon Apr 4 15:23:48 PDT 2005
Eduardo Tongson wrote:
Think that through. Sounds good in concept, but how many 'sets' of docs
need to exist?
2, something like release and devel
Which implies a 'frozen' Release set for each and every release, though.
Lots of stuff in the attic.
I seriously doubt they would see much use. I've lived with manually
the periodic updates to a nine-foot-long shelf of Armed Service
Department of Defense Procurement Regulations, Signal Corps site
manuals, and FCC and ATT tariffs in earlier lives.
My kid bother once worked for an outfit called 'Loose Leaf Updates'
where he made regular rounds updating those, plus microfiche and CD's
for everything from law offices to aircraft maintenance manuals.
*Nobody* wanted last week's docs.
But *everybody* wants this weeks doc's to have a mention of what 'used
to be' - or at least any recent enough 'used to be' that might bite them
in the ass if they are not fully current. Identified changes, IOW, not
just that two 'as built' will differ in several unmentioned places.
In fact, it is often just that very comparison note that decides a
sysadmin when it is the right time (for them) to udate.
So - I suggest the docs should always be just *one* set, and as current
as we can humanly make them, even to the extent of including mention of
'coming attractions' and 'work still in progress' or 'wishlisted
features' that might be worth risking or avoiding, depending on
The key, in my view, is the embedded 'change 23' notes, not 'see doc
1.1.01.25' ... which is probably 99% identical with the one immediately
before or after, and does NOT call attention to *which* 1% has changed.
Do we 'diff' the docs? And how would even that tell us which of the
diffs were the ones we needed to read?
Will anyone even read, for example, all three scattered *paragraphs* (if
they can even figure out which three and where to look) that cover the
differences germane to their needs?
A single, up-to-date copy, *with notes*, would make finding relevant
things far easier. Anything else may be unmaintainable anyway - we will
ahve a new releae before we have gotten the last three covered properly.
Have a look, for a decent example, at the online Exim 4.X spec, wherein
new additions and changes show up (for a time) in contrasting color, and
with explanatory notes and hints as to what legacy behaviour might be
affected, where appropriate.
Those Exim docs do need work overall, but that particular tool is very
much more practical and effective than the 'accounting' principle of
'closing the books' for each period.
More information about the Docs