RE: Using wiki to encourage users to contribute to documentation.
Martin,
Thank you for greeting me so warmly. You posed several questions in your
mail which I have answered below:
> 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.)
>
I wonder if they were promoted in any way. I only heard about wiki in a
magazine article.
> 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.
>
Interesting, the subject of this wiki is some history and a guided tour of
distributions. It is interesting to the experienced Linux user, but far too
confusing to the newcomer. Sorry if that hurts.
> 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.
>
Now this did manage to catch my eye because I know the benefits of SGML as I
was using it pre-PC. However I understood that it would convert the wiki to
SGML. I had assumed that the LDP would allow use of the wiki on another
website if it seemed useful for the purpose.
> 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.)
>
This web site has disappeared. Couldn't find any ref to Debian in University
of Waikato search either.
> > 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 LDP Author Guide made me think, "I'm not sure that I want to even start
reading this."
I think the thing that strikes me most about almost every bit of Linux
documentation that I have seen on the web is it lack of structure. What I
mean is huge paragraphs will masses of abbreviations and brackets etc. It
looks a mess. The LDP Author Guide is an excellent example.
As a Computer Consultant I have to write documents for director, managing
directors and chairmen to read. The content has to be brief concise and to
the point.
It should be laid out so that there are not large chunks of text and above
all there must be a logical flow.
So there is:
a brief introduction
a reasoned explanation of what we are trying to achieve
and
a conclusion which includes the bottom line.
> > 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.
>
I fully understand all those people. I can be possessive about my text. We
all have to learn not to take criticism personally. I'm still learning, but
I do usually come around because the purpose of a document is to
communicate. If it isn't communicating. it isn't working. Anyway we seem to
be in agreement.
> > 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 will have another look at your 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?)
>
That is my whole point. If the developer were asked to read the user
document prior to coding they would get a much better understanding of the
users requirements. I have spent too many years reading project
specifications only to reach the end with still no concept of what the
project really does or , more importantly HOW it will do it. Of course,
someone does need to ensure that the resulting project does actually do what
the documentation says. (a problem that Microsoft still fails to solve which
is why I am so interested in Linux)
> > 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?
>
Different wikis are implemented in different ways. http://www.wikipedia.org/
has the facility to discuss a page as well as edit it. Too often in wiki
people start discussing the document on the page which doesn't improve
readability. When I get more experienced with wiki I will know what features
are needed.
> > 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.)
>
Thanks for the pointer. And thanks for your encouragement
Kind regards,
Andrew Ballantine
andrewballantine@btconnect.com
Reply to: