Re: Wiki and docs in cvs

[Bill Hacker <wbh@xxxxxxxxxxxxx>]

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 
applying
the periodic updates to a nine-foot-long shelf of Armed Service 
Procurement Regulations,
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 
individual needs.

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.

Bill