discuss: Planning to publish new document
Subject:
Re: Planning to publish new document
From:
David Lawyer ####@####.####
Date:
28 Feb 2003 23:41:51 -0000
Message-Id: <20030228232825.GD677@lafn.org>
On Tue, Feb 25, 2003 at 09:16:24PM -0500, Derek Hans wrote:
> Hi,
>
> I was just wondering - did anyone ever consider using Wiki-style
> editing for the documentation? I have the impression that this would
> have several advantages.
>
> It would simplify / make possible the collaboration of several authors
> during the initial creation of new documentation.
With wiki, there is no negotiations for the overall organization and
layout of the doc. One person can likely do a better job for this.
> It would simplify the maintenance of the documents, as the changes can be
> made directly online.
Sending email to the author by clicking on the email is fairly simple
too.
> It would encourage other people to add their own experiences /
> information they would have found useful while they were solving a
> problem for which they used the documentation.
They might clutter up the doc with info that only applies to their
particular case while ignoring generalized info.
> It would help keeping the documentation up to date, as users that notice
> information that is out of date could immediately change them.
True. But a fully automated submission system can let authors update
whenever they modify their docs.
> By letting others easily contribute to the content, this would diminish
> the workload on the official maintainer.
Yes, but the official maintainer needs to check out what's been
modified.
> The review process should also be simplified by its use.
No. By submitting comments directly to the maintainer, the maintainer
acts as a reviewer and filter for changes proposed by the readers.
>
> In general, wiki-based documentation simply has the possibility of being
> richer and more dynamic, content-wise.
More dynamic, yes. But it can also be more fragmented and possibly with
more errors.
>
> If people want to download the documentation, a zipped file of the
> current state could be created on the fly, or, if this is too resource
> heavy, a monthly snapshot could be made that is used for download
> purposes during the following month. This could also be used by mirrors.
There needs to be a master copy which people modify. Since wikis use a
crude form of markup language. This is another burden on people making
changes. Writing directly to the author avoids this.
There are also positive aspects of wikis. Lampadas is supposed to
provide this for authors who want it and I think it's an OK idea.
David Lawyer
