Re: Using wiki to encourage users to contribute to documentation.
On Sun, 6 Jul 2003, Andrew Ballantine wrote:
> I recently attended a Linux user conference in Birmingham UK, where I met
> Martin Michlmayr and he encouraged me to describe my idea for wiki generated
> documentation.
Hi, Andrew __
Glad to make your acquaintance.
This idea has in fact already been kicked around a number of times over the
past three years, by both the debian and linux documentation projects, and
various wikis have been set up to do just this. (The relevant archives will
tell you more.)
Some have come and gone; others are still around.
None has (as yet) made any great impact on the documentation scene.
See: http://startext.demon.co.uk/distwiki/, for example.
The LDP used to have an excellent text-wiki set up by David Merrill (it was a
wiki which accepted SGML markup as well as wikitext markup), but it has now
unfortunately gone into limbo. It had great promise; and may even yet be
resuscitated under the lampadas project (q.v.)
It was, however, not Debian specific.
However, I believe the University of Waikato (NZ) still has a wiki where the
totality of existing Debian (woody) documentation may be called up and edited:
www.wlug.co.nz I think. (As I remember, it is also linked to the NewbieDoc
project.)
> Please do not interpret the contribution as hostile. I genuinely
> want to help improve the quality of Debian's documentation.
I doubt very much whether anyone is likely to consider your comments as
hostile at all. The reaction is rather -- join the gang!
There is an enormous amount of work to be done -- and a huge access bottleneck
to be worked around -- and as you so rightly point out, wiki-editing is the
perfect answer.
> As a new, interested user
> I have browsed quite a lot of Debian and Linux documentation and most of it
> is quite difficult to read and understand for the new user.
Yes. Which is why it is vitally important that new, 'uncontaminated'
(sorry!) users get the opportunity to have a voice whilst that voice is still
fresh and useful to others in their situation, *and can find somewhere where
they can express themselves immediately*.
> When I looked at
> the possibility of contributing to the LDP (Linux Documentation Project) it
> looked quite intimidating so I shied off.
Oh. (Out of interest, what exactly did you find intimidating? Markup
schemas? Or the whole CVS process for finding and accessing documents? I'd
be interested to know, as I don't find it intimidating myself, so I've
obviously got a blind spot to the difficulties new users and others
encounter.)
> The whole point about a Wiki is that you can contribute immediately.
Exactly.
Mind you, there are writers who are so fiercely possessive of "their" text
that the idea of wiki-editing is total anathema to them; these will never
accept the idea. Then there are those writers steeped in bureaucratic tech
doc procedures to the point that open editing, wiki-style, is perceived as
being the work of the devil, akin to Total Anarchy And Chaos To Be Avoided At
All Costs; or at best, a braindead product of _really_ fluffy minds.
Nevertheless, the fact is that for fast co-operative creative authoring,
experience shows that wikis are hard to beat.
> You
> don't need permission and you don't have to wait while you get authorised,
> rubber stamped, sanitised and what ever other hoops might be provided to
> jump through.
Yup. Feel free to add anything you would like -- new documents, amendments
-- whatever, to the startext.demon.co.uk/distwiki site.
> I agree that a Wiki could very easily get out of control if not supervised,
> but moderated sensitively it could produce some excellent results.
In point of fact, practical experience shows that this fear is unfounded. In
three years of using fully publicly accessible wikis for documentation
purposes, the only 'problem' I have ever had is someone who went through one
particular document, carefully replacing every occurrence of 'GNU/Linux' with
'Linux'. I just as carefully went through again, re-inserting the original
text. The incident was not repeated.
> Not only
> could a Wiki environment be used to document existing versions of the
> system, it could be used by users to define how they would like the next
> version to behave.
Nice idea. (But do developers read the documentation for their products, I
wonder?)
> here I am concerned with generating the content rather
> than getting bogged down with how it get translated, stored, distributed
> etc.
Absolutely. Couldn't agree more. Plus instant proof-reading of said
contnet by experienced eyes.
> I also appreciate that the choice of wiki engine is critical to give the
> right control
.. not sure I agree with you here. Reasons?
> and the ability to convert the content to the desired mark-up
> language for easy processing to other document types.
This is the most important feature -- maybe you could talk to David Merrill
about how he produced his wiki-text engine? (dmerrill@lupercalia.net from
memory.)
Cheers,
--
Martin Wheeler - StarTEXT / AVALONIX - Glastonbury - BA6 9PH - England
msw@startext.demon.co.uk http://startext.demon.co.uk/
GPG pub key : 8D6B948B ECC6 D98E 4CC8 60E3 7E32 D594 BB27 3368 8D6B 948B
- Share your knowledge. It's a way of achieving immortality. -
Reply to: