[opensuse] OpenSUSE Documentation is Bad
Hi, I have noticed that the documentation for openSuse is terribly organized and in many cases outdated. For a newcomer who visits opensuse.org, the first thing they have to click on to get help is "Discover It", which is not very relevant to directing someone new to the wiki. There should be simple designations, such as "Help", "Wiki", "Support" on the main page, or something as such. Once you click on "Discover it", you're directed to a page with a hodgepodge discombobulated kerfuffle of information a new person to openSUSE is most likely not going to find useful. When you click on "Discover It" and are taken to "Main_Page", the title "Main Page" should be titled something relevant. On the main page, the topics "Project" and "Distribution" don't have to be in separate sections, and why is "Wiki" at the bottom? That makes zero sense. I can't even begin to touch on the problems with the complete mess the entire wiki is, but let's do an example. I'm a new user, and I click on "Discover It". How does it make any sense that when clicking on "Discover It" and being taken to the Main_Page wiki, that when clicking on the "wiki" link on the left sidebar, you're then taken to "Wiki > Portal:Wiki"? So, now we're in "Portal:Wiki". We're displaed with a big long mess of explaining structure. How is this relvant to helping a new user, or even an experienced one? It isn't. In the right pain, we're shown "help pages" and "Navigation". So, if the new user got this far which they probably haven't, let's say they click on "13.1" in the right sidebar, because that's the version they have installed or are having trouble installing. We learn that openSUSE is "stabilized", "networked", "evolved", "polished", and the list goes on. That's all find and dandy, but now the user has to scroll all the way down to the bottom of the page to actually find something which may be relevant to the problem they are having. Let's say the use is having a problem with PulseAudio. Nothing relevant to PulseAudio can be found, and still to this day, I can't find where the documentation to PulseAudio is without searching for it on Google. Getting support for openSUSE shouldn't be this painstakingly difficult, and there needs to be be a discussion had about how awful it is right now. If the documentation is bad, people aren't going to want to use the distribution. I am doing some edits to pages in order to improve the ones written in broken English, but I am one little guy and I am unable to do it all myself. There needs to be a concerted effort to get the documentation better than any other distribution, and the stuff needs to be easy to find, easy to navigate, and easy to read. I don't have access to the Main Page, but this is the first thing that needs improvement, and the "Discover It" needs to go. Thank you, Lars Kruczynski -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
Le 11/04/2014 14:26, Lars Kruczynski a écrit :
Hi,
I have noticed that the documentation for openSuse is terribly organized and in many cases outdated. For a newcomer who visits opensuse.org, the first thing they have to click on to get help is "Discover It", which is not very relevant to directing someone new to the wiki. There should be simple designations, such as "Help", "Wiki", "Support" on the main page, or something as such. Once you click on "Discover it", you're directed to a page with a hodgepodge discombobulated kerfuffle of information a new person to openSUSE is most likely not going to find useful. When you click on "Discover It" and are taken to "Main_Page", the title "Main Page" should be titled something relevant. On the main page, the topics "Project" and "Distribution" don't have to be in separate sections, and why is "Wiki" at the bottom? That makes zero sense.
I can't even begin to touch on the problems with the complete mess the entire wiki is, but let's do an example. I'm a new user, and I click on "Discover It". How does it make any sense that when clicking on "Discover It" and being taken to the Main_Page wiki, that when clicking on the "wiki" link on the left sidebar, you're then taken to "Wiki > Portal:Wiki"? So, now we're in "Portal:Wiki". We're displaed with a big long mess of explaining structure. How is this relvant to helping a new user, or even an experienced one? It isn't. In the right pain, we're shown "help pages" and "Navigation". So, if the new user got this far which they probably haven't, let's say they click on "13.1" in the right sidebar, because that's the version they have installed or are having trouble installing. We learn that openSUSE is "stabilized", "networked", "evolved", "polished", and the list goes on. That's all find and dandy, but now the user has to scroll all the way down to the bottom of the page to actually find something which may be relevant to the problem they are having. Let's say the use is having a problem with PulseAudio. Nothing relevant to PulseAudio can be found, and still to this day, I can't find where the documentation to PulseAudio is without searching for it on Google. Getting support for openSUSE shouldn't be this painstakingly difficult, and there needs to be be a discussion had about how awful it is right now. If the documentation is bad, people aren't going to want to use the distribution. I am doing some edits to pages in order to improve the ones written in broken English, but I am one little guy and I am unable to do it all myself. There needs to be a concerted effort to get the documentation better than any other distribution, and the stuff needs to be easy to find, easy to navigate, and easy to read. I don't have access to the Main Page, but this is the first thing that needs improvement, and the "Discover It" needs to go.
Thank you,
Lars Kruczynski
I totaly agree : the OpenSUSE doc is very bad. I can help, if I am not alone. I love documentation work, at work and at home :) -- : ` _..-=-=-=-.._.--. Dsant, from Lyon, France `-._ ___,..-'" -~~` __') forum@votreservice.com jgs `'"---'"`>>"'~~"~"~~>>'` =====================```========```======== -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
On 2014-04-11 14:37, Dsant wrote:
Le 11/04/2014 14:26, Lars Kruczynski a écrit :
Hi,
distribution. I am doing some edits to pages in order to improve the ones written in broken English, but I am one little guy and I am unable to do it all myself. There needs to be a concerted effort to get the documentation better than any other distribution, and the stuff needs to be easy to find, easy to navigate, and easy to read. I don't have access to the Main Page, but this is the first thing that needs improvement, and the "Discover It" needs to go.
I totaly agree : the OpenSUSE doc is very bad.
I can help, if I am not alone. I love documentation work, at work and at home :)
There is currently a discussion on the Project mail list about documentation, I suggest you join it, instead of talking about it on separate places. There is also a "opensuse-web" where writers of the wiki coordinate. It is very low traffic. Volunteers for wiki work are very much needed. -- Cheers / Saludos, Carlos E. R. (from 13.1 x86_64 "Bottle" at Telcontar)
On 11/04/14 14:37, Dsant wrote:
I totaly agree : the OpenSUSE doc is very bad.
I can help, if I am not alone. I love documentation work, at work and at home :)
I'd have to agree that I've always found openSUSE documentation a bit of a mess, where it exists. Tell a lie, in fact my first experience of SuSE was the boxed editions of SuSE Professional 8/9, with the two big manuals contained inside which were written with humour and passion. It's a crying shame that such a thing isn't the first experience of users today. That's not to say that upon first logging in they should be presented with a 500-page PDF file, but the default 'welcome' at least in KDE is very aged and of minimal use, and the web side is, like the OP said, fragmented between forum, wiki and other sites, and not always well organized. Going for the green option on the main openSUSE.org site (assuming somebody's already downloaded / installed the distro) presents a Main Page that isn't very intuitive. If I'm a new user who wants help with, say, configuring my printer, or figuring out graphics issues or fixing broken multimedia, where do I go from this page? It isn't obvious at all. Everything seems very abstract. In my opinion, instead of directing straight to this vague, incoherent and often outdated wiki as the front page, there could be more 'official' information on the site with the wiki proposed as more of a supplementary, user-generated resource. I realise however that that doesn't really fit considering the division between SUSE and the openSUSE user community. I guess I'm still hoping there could in some way be paid SUSE employees working on such things, to add a touch of professionalism. There's probably enough documentation contributors out there who could write good material, but the community project as a whole lacks useful ways to guide collaborators into producing something cohesive. Dsant: Intrigué par votre signature, étant dans la même ville, j'ai accédé sur le site votreservice.com. La page montrée par défaut me semble un peu étrange par rapport à celle trouvé après avoir cliqué sur 'Start' - c'est comment le lien avec OVH? C'est possible que je cherche l'hébergement web à l'avenir et le plan perso semble un bon prix, même si je n'ai pas encore bien étudié les détails. Etes-vous employé d'OVH ou un tiers? Peter -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
Example: http://old-en.opensuse.org/Linuxrc This section to me has always been little clearer than mud: install=nfs://foo/bar?device=eth0 # works with network devices, too install=nfs://foo/bar?device=00:0e:0c:* # matches MAC addresses, too Absent real world examples, I can hardly imagine what they mean. Are the "?device..." portions optional? If not, whose device or MAC address is meant, system installing to, or the server with the source? If optional, is foo interchangeable with an IP address? Later down the page there is more detail about install=, but with nada about nfs. -- "The wise are known for their understanding, and pleasant words are persuasive." Proverbs 16:21 (New Living Translation) Team OS/2 ** Reg. Linux User #211409 ** a11y rocks! Felix Miata *** http://fm.no-ip.com/ -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
On 2014-04-12 06:18, Felix Miata wrote:
Example: http://old-en.opensuse.org/Linuxrc
No, complains about the old-en wiki are not accepted >:-) It is just a frozen, old, wiki. It has been superseded by the new wiki. If you find defects, they can not be corrected. Consider that the old wiki was to be completely removed. Some of us asked for the contents to be accessible somewhere, and they were left intact on a different address. -- Cheers / Saludos, Carlos E. R. (from 13.1 x86_64 "Bottle" at Telcontar)
Felix Miata wrote:
Example: http://old-en.opensuse.org/Linuxrc
This section to me has always been little clearer than mud:
install=nfs://foo/bar?device=eth0 # works with network devices, too install=nfs://foo/bar?device=00:0e:0c:* # matches MAC addresses, too
Absent real world examples, I can hardly imagine what they mean. Are the "?device..." portions optional?
Yes.
If optional, is foo interchangeable with an IP address?
Yes. -- Per Jessen, Zürich (13.1°C) http://www.dns24.ch/ - your free DNS host, made in Switzerland. -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
Example: http://en.opensuse.org/SDB:Linuxrc This section ( identical to its predecessor http://old-en.opensuse.org/Linuxrc ) to me has always been little clearer than mud: install=nfs://foo/bar?device=eth0 # works with network devices, too install=nfs://foo/bar?device=00:0e:0c:* # matches MAC addresses, too Absent real world examples, I can hardly imagine what they mean. Are the "?device..." portions optional? If not, whose device or MAC address is meant, system installing to, or the server with the source? If optional, is foo interchangeable with an IP address? Later down the page there is more detail about install=, but with nada about nfs. -- "The wise are known for their understanding, and pleasant words are persuasive." Proverbs 16:21 (New Living Translation) Team OS/2 ** Reg. Linux User #211409 ** a11y rocks! Felix Miata *** http://fm.no-ip.com/ -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org -- To unsubscribe, e-mail: opensuse+unsubscribe@opensuse.org To contact the owner, e-mail: opensuse+owner@opensuse.org
On 2014-04-12 19:21, Felix Miata wrote:
Example: http://en.opensuse.org/SDB:Linuxrc
This section ( identical to its predecessor http://old-en.opensuse.org/Linuxrc ) to me has always been little clearer than mud:
install=nfs://foo/bar?device=eth0 # works with network devices, too install=nfs://foo/bar?device=00:0e:0c:* # matches MAC addresses, too
Absent real world examples, I can hardly imagine what they mean. Are the "?device..." portions optional? If not, whose device or MAC address is meant, system installing to, or the server with the source? If optional, is foo interchangeable with an IP address?
Later down the page there is more detail about install=, but with nada about nfs.
Not long ago I investigated a bit about linuxrc. I found these references (I have not verified if they still exist):
http://en.opensuse.org/SDB:Linuxrc http://doc.opensuse.org/projects/YaST/SLES9/autoinstall/sles8/html/x1332.htm... http://doc.opensuse.org/projects/autoyast/appendix.linuxrc.html http://www.novell.com/documentation/suse91/suselinux-adminguide/html/ch12s04...
The last link has examples of entering parameters for linuxrc. From the third link: «Unless Linuxrc is in manual mode, it will look for an info file in these locations: first /info on the floppy disk and if that does not exist, for /info in the initrd. After that it parses the kernel command line for parameters. You may change the info file Linuxrc reads by setting the info command line parameter. If you do not want Linuxrc to read the kernel command line (e.g. because you need to specify a kernel parameter that Linuxrc recognizes as well), use linuxrc=nocmdline. » I used a trick found there in order to save log files during installation from DVD to a disk partition, in order to read them after a crash. Yes, the wiki page could be improved, but few people know about linuxrc. And, many wiki pages are locked, edits are not allowed. Sometimes I edit a page, and months later my edits have disappeared, with text I can not agree... Thus I'm discouraged from contributing. -- Cheers / Saludos, Carlos E. R. (from 13.1 x86_64 "Bottle" at Telcontar)
participants (6)
-
Carlos E. R. -
Dsant -
Felix Miata -
Lars Kruczynski -
Per Jessen -
Peter