DragonFly docs List (threaded) for 2005-04
Re: Wiki and docs in cvs
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
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
changes. Many if not most will actually NOT be. libs yes, apps not,
It is 'highly important' to reflect any changes in the handbook or wiki
code changes actually affect what is being described in a way the reader
care about, and/or be affected by.
BUT - if we are doing a good job of writing a handbook, it will for the
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
and having a ready environment to encourage a contribution when time and
If we start putting artificial 'freezes' on docs, they might as well be
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
Code writers may be orderly, methodical folk, even if/as/when quite mad.
Prose and technical writers, OTOH, are artists - mad or otherwise. ;-)