[opensuse-wiki] We need consent how to write articles
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 This is important for wiki maintainers, so that they all can act in the same way. The article http://en.opensuse.org/OpenSUSE_Style_Guide was written when wiki had few contributors, now it should be rewritten. The guide should be modular, ie. main article that will give basic instructions that are easy to follow and list topic details for editors on other pages. I would base guide on Wikipedia experience as much as possible. 1-1. Article title length, form and capitalization. Some examples of very long titles and titles with different style for the same purpose can be found on http://en.opensuse.org/Portal/All 1-2. Use of subpages With single benefit that we have bread crumbs to go back, titles are getting out of control. Title became information container about all topics discussed. That doesn't help to find a page, one has to provide index anyway. 2. This also brings another question that was presented before about new namespaces like: Bugs: For what it is already used title form "Bugs: ..." Applications: For applications reviews. Software: as alternative to Applications with wider use Development: For all development related articles. KDE: GNOME: X: HCL: Usability: Translation: Education: -- Regards, Rajko. --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-wiki+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-wiki+help@opensuse.org
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.
problem with guides is that nobody read them :-(
1-1. Article title length, form and capitalization. Some examples of very long titles and titles with different style for the same purpose can be found on http://en.opensuse.org/Portal/All
beginning with the home page... "Welcome" should be neough, given it's noted "openSUSE" everywhere :-)
1-2. Use of subpages With single benefit that we have bread crumbs to go back, titles are getting out of control.
sub pages are nice for closely related stuff, like a big howto divided in several chapters Title became information container about all topics discussed.
That doesn't help to find a page, one has to provide index anyway.
this should if the search engine was right. but it's not even able to find titles (at least not always)
2. This also brings another question that was presented before about new namespaces like:
I really don't see any benefit in using several namespaces. even SDB is worthless (as a name space) jdd -- http://www.dodin.net --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-wiki+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-wiki+help@opensuse.org
On Sunday 02 December 2007, jdd wrote: Hi,
beginning with the home page... "Welcome" should be neough, given it's noted "openSUSE" everywhere :-)
don't forget about external search engines. I'd rather prefer to see "Welcome to openSUSE" instead of just "Welcome" in Google... . -- Regards Frank Frank Sundermeyer, Technical Writer, Documentation SUSE Linux Products GmbH, Maxfeldstr. 5, D-90409 Nuernberg Tel: +49-911-74053-0, Fax: +49-911-7417755; http://www.opensuse.org/ SUSE LINUX Products GmbH, GF: Markus Rex, HRB 16746 (AG Nürnberg) Reality is always controlled by the people who are most insane (Dogbert) --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-wiki+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-wiki+help@opensuse.org
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
On Sunday 02 December 2007 02:27:44 pm jdd wrote:
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?
I wrote long addition on title and section capitalization, usage of fonts, and few more things looking on Wikipedia solution, as they have far more experience with style, but that was never published and now I decided to start over. For instance they insist on capitals only for nouns that are names. It is normal to write them starting with capital letters in any language and that rule is easy to remember. The subpages is OK to use for one level, for instance: "YaST" "YaST/Control Center" "YaST/Commands" "YaST/Modules" but now anything about YaST is prefixed with YaST/.../... which looks fine for people used to files system paths, but otherwise has no estetic value and spoils readability of title. Besides that leads to oversized titles, where article subject is hidden in path, title very soon breaks in 2 lines, etc. Even above example look better like this: "YaST" "YaST Control Center" "YaST Commands" "YaST Modules" The navigation bar with list of pages in group, like http://en.opensuse.org/Download , is in any case much better option than one way bread crumbs, as you have to provide links to subpages anyway. When I started Portal it looked fine to use subpages, now I'm sure it was not good idea. -- Regards, Rajko --------------------------------------------------------------------- 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
Razi Khaja wrote:
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.
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 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 :-( jdd -- http://www.dodin.net --------------------------------------------------------------------- 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
Razi Khaja wrote:
The use of a template might guide writers to follow a layout.
there is one for the SDB. Frankly, I don't like this. I think most writers must have style freedom. We already have a CSS that give a lot of similar layout. I think the better thing we need is a good page and we can't have it if we set burden on the writer. I personnaly don't like the wiki anonymous way of life, so I mostly write on my own wiki Documentation don't have to be dusty :-)) and boring :-)) we need robust doc (complete, understandable), the rest... templates in mediawiki are not the kind of beast you think
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".
as far as you understand, I think this is a good thing. In the true life, people may use different wording and you nhave to understand them all writing in the wiki is a voluntary task, don't make the writers run away :-)) jdd -- http://www.dodin.net --------------------------------------------------------------------- To unsubscribe, e-mail: opensuse-wiki+unsubscribe@opensuse.org For additional commands, e-mail: opensuse-wiki+help@opensuse.org
participants (4)
-
Frank Sundermeyer
-
jdd
-
Rajko M.
-
Razi Khaja