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@opensuse.org For additional commands, e-mail: opensuse-wiki+help@opensuse.org