DragonFly BSD
DragonFly docs List (threaded) for 2005-04
[Date Prev][Date Next]  [Thread Prev][Thread Next]  [Date Index][Thread Index]

Re: Wiki and docs in cvs

From: Bill Hacker <wbh@xxxxxxxxxxxxx>
Date: Tue, 05 Apr 2005 02:18:06 +0800

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.


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. ;-)


[Date Prev][Date Next]  [Thread Prev][Thread Next]  [Date Index][Thread Index]