Mailinglist Archive: opensuse-wiki (26 mails)

< Previous Next >
Re: [opensuse-wiki] We need consent how to write articles
  • From: "Razi Khaja" <razi.khaja@xxxxxxxxx>
  • Date: Mon, 3 Dec 2007 08:28:02 -0500
  • Message-id: <62e9dabc0712030528s2eeff450h980b3866b0cff8df@xxxxxxxxxxxxxx>
When you help someone with a problem, you should enlist that person to
correct and complete the parts of the wiki documentation that they had
problems with.

I do, probably others also, and many people do. We could also link a
wiki page to the relevant mailing list archives.


I do also.

I often think browsing archives and making wiki pages from them could
be valuable, but this is a hudge task I never had time to complete :-(


Thats a great idea! To go into the archives is a huge task, but to
create a references section that links to newer posts in the mailing
list archive shouldn't be too difficult as long as lots of people
consistently create the links and over time could amass into a large
enough body of knowledge that wiki maintainers might have enough
material to draw on to write comprehensive documentation.


I think that most of the time people ask for help because the
documentation is not clear or complete.

notice you are here on the opensuse-wiki list, devoted to the
administration of the wiki, and we speak of guiding users to better write.


I understand that we're talking about writing better, concisely and
consistently across multiple wiki pages.

A wiki page recommending a particular style may not be enough, since
wiki writers might only read the style guide once.

The use of a template might guide writers to follow a layout. So a new
HOWTO document would have to have particular sections. When a wiki
user creates a HOWTO, a template automatically creates certain
sections or headers that have to be filled out. [Unfortunately I dont
know enough about MediaWiki to implement something like this, but if
someone knows this/figures it out, they should document it ;)] A FAQ
would have a different layout and required sections.

Aiding writers in the quality of their writing and consistency is much
more difficult.

Maybe one way to accomplish consistency in the documentation is to
modularize the documentatiton for atomic tasks.

So for example some wiki pages start with "Open Yast", others say
"Start Yast", another says "Start up YaST", another says "Fire up
Yast", another says "As root Install Amanda through Yast".
Consistently, the idea is to "Start YaST". When I say modularize the
documentation, I mean that it should be documented in one place all of
the common paths to "Start YaST" and also to enter the root password.
In effect this would be a "HOWTO: Start YaST". (Here starting YaST is
just an example, we could be talking about doing something else like
adding a software repository or even something more complex)

Next, you would have to define (somehow in MediaWiki) a controlled
vocabulary, so that whenever writers want to say something like "Fire
up Yast" they cant or shouldn't, they can only choose from the
controlled vocabulary to say "Start YaST". Writing "Start YaST" might
either link to the "HOWTO: Start YaST" or includes the contents of
that HOWTO in this wiki page.

In general terms, each of the mini HOWTOs should be of the form
"HOWTO: Do Something" where the "Do Something" is an imperative or
directive.

Then suppose that you have identified many atomic tasks, each with
their own HOWTO, you could build larger documentation by utilizing the
HOWTOs of the atomic tasks. An example of a larger task might be
"HOWTO: Setup a MySQL Server" (it should include say HOWTO: Start
Yast, HOWTO: Install a Package and documentation on doing post install
things like setting the database-root password).

To further illustrate this idea, suppose one person would like
document "HOWTO: Setup a LAMP Server" and another person would like to
document "HOWTO: Setup a TRAC Server" (with a MySQL backend), in both
of these cases, writers would need to "include" the documentation on
"HOWTO: Setup a MySQL Server" and consistency in wiki documentation
might be acheived.

Anyway I have written too much, and this would be difficult to
implement ... and just an idea to ponder... and worse, its beginning
to sound like building a wiki front end to an operating system using
MediaWiki. And still I have not addressed the quality of writing.
---------------------------------------------------------------------
To unsubscribe, e-mail: opensuse-wiki+unsubscribe@xxxxxxxxxxxx
For additional commands, e-mail: opensuse-wiki+help@xxxxxxxxxxxx

< Previous Next >
List Navigation
Follow Ups