Rajko M. wrote:

We can't expect that every potential wiki contributor goes trough training to be able to write articles, but we need consistent style guide.

1. openSUSE Style Guide

I just read again the style guide and find it very good. What do you want to add/remove? jdd -- http://www.dodin.net --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-wiki+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-wiki+help@opensuse.org

Rajko M. wrote:

few more things looking on Wikipedia solution,

may be it's for that it's good :-))

The subpages is OK to use for one level, for instance:

true, most of the time

When I started Portal it looked fine to use subpages, now I'm sure it was not good idea.

this explain why such guide is good, but must stay simple. nearly nobody read it, neither the regular authors (that think they don't need it - one important rule: read the manual again each year :-) it's better simply to ask here if somebody don't know howto cope with a problem. but in fact most of the time, people write a page because he have just found a solution to a problem, and do this in a hurry. We can't appoint rewriters it's the drawback of a wiki. At a time I thought it was possible to maintain indexes, but now I think it's nearly impoossible if not automated by a script. thankfully, google is very good (but makes time to index) and it's better to have a bad written docmumentation than no documentation at all :-)) jdd -- http://www.dodin.net --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-wiki+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-wiki+help@opensuse.org

In order to accomplish administration tasks such as setting up a web server, build server, performing a backup using the Yast Backup Module, or securing my system, I often refer to the Configuration or HOWTO sections in the Documentation and follow instructions.

it's better simply to ask here if somebody don't know howto cope with a problem.

I think that most of the time people ask for help because the documentation is not clear or complete. Asking for help in the mailing lists is necessary when problems occur for users, however, the mailing lists cannot be considered a persistent body of knowledge and so the problem resolution should be documented in the wiki so that future users attempting to accomplish the same task do not experience the problems that have already been resolved and hence do not have to ask a question that has already been answered.

but in fact most of the time, people write a page because he have just found a solution to a problem, and do this in a hurry.

This is true, and often people don't want to write documentation they would rather move on to their next most important task. However the point of a wiki is meant to be a mutable resource that can be edited and added to by many people, so a rough problem solution is better than no problem solution that should hopefully improve over time.

We can't appoint rewriters

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. Its the least that one could do for getting free help. Sort of a barter system or reciprocal altruism. A person who agrees to help with wiki documentation should get a little more priority and attention than a person who just wants free help. Getting priority would provide incentive for the person with the problem to contribute to the wiki. Ive seen other mailing lists or user groups with point systems, maybe something like that could be employed here to motivate wiki contribution.

From Wikipedia: http://en.wikipedia.org/wiki/Reciprocal_altruism

In evolutionary biology reciprocal altruism is a form of altruism in which one organism provides a benefit to another without expecting any immediate payment or compensation. However, reciprocal altruism is not unconditional. Firstly the act of altruism must give rise to a surplus of cooperation, in the sense that the gains to the beneficiary must be perceived to be meaningfully larger than the costs to the benefactor. Secondly the act of altruism should be reciprocated by the original beneficiary if the situation is later reversed. Failure to do so will usually cause the original benefactor to withdraw future acts of altruism. --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-wiki+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-wiki+help@opensuse.org

...

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