Hi I still have this on my todo list ... I post it here to hear your opinions, and because we have only the SDB namespace atm. Did i miss something? To be honest i thought it would be much more, but i don't know what else to write :-) --- Howto/SDB/FAQ? There is some confusion about the definition of howtos, SDB articles and FAQs. This page tries to explain the main differences between the different styles to write documentation. Why a different namespace for them Working with namespaces makes searching much easier and you can see on the first look what it is. The different types howto From the wikipedia definition "A how-to is an informal, often short, description of how to accomplish some specific task. They are generally meant to help non-experts, and may leave out details that are only important to experts, and may be greatly simplified from an overall discussion of the topic." This describes perfectly an SDB article :-) Anyhow, most howtos are much more for experts and often more verbose. An example for an howto is SDB:Wireless_LANs_with_SuSE_Linux. So howtos in the openSUSE wiki are more verbose than SDB articles. If you just want to write a short article consider to put it into the SDB. Howtos have a separate namespace, so all Howtos should start with howto: SDB article SDB (Support Database) was a SUSE invention. The goal is to provide a short and easy to read article for the customer/user how to fix a problem. The focus was to make it easy and to use graphical tools where possible. A SDB article should be always problem related. Because there was only the SDB before the openSUSE wiki, you will find also some articles which are from the definition a howto. Check the SDB:Howto for more information about SDB articles. SDB have a separate namespace, so all SDB articles should start with SDB:. FAQ A FAQ (Frequently Asked Questions) follow a different style. Example: Q: Is it possible to install SUSE Linux on a computer with a i486 CPU? A: No, SUSE Linux support CPUs from Pentium 1 (and compatible ones) on. FAQs are a good way to summarise topics. It could make sense even if a howto or SDB article already exist. Some howtos include a FAQ, usually at the end of the howto. FAQs have a separate namespace, so all FAQs should start with FAQ:. -- with kind regards, ---------------------------------------------------------------------- Martin Lasarsch, Subsystems +49 911 74053 181 +49 179 206 74 74 SUSE LINUX GmbH, Maxfeldstr. 5 90409 Nuremberg martin.lasarsch@suse.de ---------------------------------------------------------------------- simply change to www.suse.de
Martin Lasarsch wrote:
Hi
I still have this on my todo list ... I post it here to hear your opinions, and because we have only the SDB namespace atm.
Did i miss something? To be honest i thought it would be much more, but i don't know what else to write :-)
very good idea to discuss this, I think ATM our wiki needs some formating guidelines (over what has already be done)
--- Howto/SDB/FAQ? There is some confusion about the definition of howtos, SDB articles and FAQs. This page tries to explain the main differences between the different styles to write documentation.
Why a different namespace for them Working with namespaces makes searching much easier and you can see on the first look what it is.
I think it's a bad idea. namespaces are short in number, difficult to deal with (needs an admin change to config files) and not done for this. much better is the use of categories and sub-categories, pages and sub-pages. don't make a mistake - I'm not a mediawiki guru and discovered this only fiew days ago :-), I've still much to learn :-) the start is from: http://fr.opensuse.org/Special:Uncategorizedcategories (replace fr by en if you want, but I experimented on fr wiki) this links you the the first level categories. clicking on one of them send you to the sub-categories of this one, and so on. three or four levels are the best. see mediawiki help for details. When the layout bug will be fixed, this should be much fancier, now you have to scroll down to see the links :-(.
The different types
howto From the wikipedia definition "A how-to is an informal, often short, description of how to accomplish some specific task. They are generally meant to help non-experts, and may leave out details that are only important to experts, and may be greatly simplified from an overall discussion of the topic." This describes perfectly an SDB article :-)
no. look at the "informal". SDB articles are very formal and should stay like this, it's a very good thing.
Anyhow, most howtos are much more for experts and often more verbose.
true for the verbose part :-) (and I was a linuxdoc HOWTO writer :-) I think of some particular sorts of pages: * SDB is really a special kind, that could need a special maintenance team, because they are intimidating at first (the "formal" aspect, the SDB HOWTO IS intimidating :-) * usual pages. one subject=one page, formalised as the writer needs * Longer pages. When a page is more than two screen hight (approx), it's better to split the page. These are HOWTO and the howto index page can be like this: http://fr.opensuse.org/Comment_faire or that one http://fr.opensuse.org/Comment_faire/Mini_manuels this sub page makes it easy to see that the pages are related, it's also easier to categories them (may be making only the main page in a category, I dn't know for sure, I'm experimenting) * tips and tricks: there the contents are very short, so several by page, splitted on the title level. FAQ is a sort of tips & tricks, but with a little different layout the strong point of using categories is that it's easy, don't change the content of the pages, so it's easy to experiment, change mind... We can even have more than one tree, the tree search can be by user level or distro ID or... jdd -- http://www.dodin.net http://dodin.org/galerie_photo_web/expo/index.html http://lucien.dodin.net http://fr.susewiki.org/index.php?title=Gérer_ses_photos
Am Dienstag, 7. März 2006 17:10 schrieb jdd:
Martin Lasarsch wrote:
Hi
I still have this on my todo list ... I post it here to hear your opinions, and because we have only the SDB namespace atm.
Did i miss something? To be honest i thought it would be much more, but i don't know what else to write :-)
very good idea to discuss this, I think ATM our wiki needs some formating guidelines (over what has already be done)
--- Howto/SDB/FAQ? There is some confusion about the definition of howtos, SDB articles and FAQs. This page tries to explain the main differences between the different styles to write documentation.
Why a different namespace for them Working with namespaces makes searching much easier and you can see on the first look what it is.
I think it's a bad idea. namespaces are short in number, difficult to deal with (needs an admin change to config files) and not done for this. much better is the use of categories and sub-categories, pages and sub-pages.
don't make a mistake - I'm not a mediawiki guru and discovered this only fiew days ago :-), I've still much to learn :-)
Sorry for the delay, much to do .. bla bla ... Ok, i added the namespaces to our staging wiki. As soon this is also on opensuse.org i will put the howto online. The adding is no problem, and the default namespaces are limited, but you can add more if you want. So no problem here imho. As i said before, the main advantage is to limit the search. Imho this makes this valuable to the wiki. I realize that with another namespace ppl will maybe not using it, we will see :-) Or any strong objections from your side? -- with kind regards, ---------------------------------------------------------------------- Martin Lasarsch, Subsystems SUSE LINUX GmbH, Maxfeldstr. 5 90409 Nuremberg martin.lasarsch@suse.de ---------------------------------------------------------------------- simply change to www.suse.de
Martin Lasarsch wrote:
Or any strong objections from your side?
not on mine :-) jdd -- http://www.dodin.net http://dodin.org/galerie_photo_web/expo/index.html http://lucien.dodin.net http://fr.susewiki.org/index.php?title=Gérer_ses_photos
participants (2)
-
jdd
-
Martin Lasarsch