Re: Wiki and docs in cvs

[Bill Hacker <wbh@xxxxxxxxxxxxx>]

Hummel Tom wrote:

> though i'm not a dev, i have 2 thoughts on that too.
>
>
> > Should we look at a "release cycle", similar to what's happening with the
> > software?  i.e. declare a few weeks of typo-fixing, and then move the
> > documentation at that point into a separate copy, associated with that
> > release of DragonFly?
>
>
> I think that's a great idea, while time is passing by, programs change
> and i often found outdated documentation which is not tagged as such.
>
>
> > This way, documentation matches a particular release.  This may become
> > more significant as more radical features get moved in...  There's also
> > the bonus of regular cleanups for the docs.
>
>
> I think a typo-fixing-only period will stop people adding new topics,
> and in the worst case forgetting about them.
> IMHO it would be a nice idea to fork the Wiki/doc at that time, so new
> pages can be created without interfering with the
> "documentation-feature-freeze" for the soon to be released version.
>
> tom

I don't think that is going to actually work - at least not as 
expected/wanted.

It is *required* for 'latest' or 'changelog' in source tarballs.

It is a 'very good idea' for any man pages that actually are affected by 
code
changes.  Many if not most will actually NOT be.  libs yes, apps not, 
utils maybe.

It is 'highly important' to reflect any changes in the handbook or wiki 
IF/AS/WHEN
code changes actually affect what is being described in a way the reader 
would notice,
care about, and/or be affected by.

BUT - if we are doing a good job of writing a handbook, it will for the 
most part
be sufficiently general that not a lot of code changes actually require 
a change in
describing what a module does, or even in many cases how it does it.

The hard parts with writing docs are getting started, keeping the 
momentum going,
and having a ready environment to encourage a contribution when time and 
mood permit.

If we start putting artificial 'freezes' on docs, they might as well be 
permanent freezes.

It is more important that docs continue to live, learn, and grow more 
useful than be
in perfect sync.  They are neither read in real-time nor compiled with 
the code.

Code writers may be orderly, methodical folk, even if/as/when quite mad.

Prose and technical writers, OTOH, are artists - mad or otherwise.  ;-)

Bill