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.
>
> 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
討論串 (同標題文章)
完整討論串 (本文為第 3 之 12 篇)：