Fedora’s Documentation

How often? How do you get there – do you visit it directly, link from fedoraproject.org, or link from somewhere else? Why do you go to docs.fpo? (Looking to solve a specific problem, looking to learn more in general about a specific part of Fedora, etc.) What do you like best about it? What do you dislike about it? If you could improve anything about it, what would you improve?

Rate this:

Share this:

Like this:

LikeLoading...

Related

About Máirín Duffy

Máirín is a principal interaction designer at Red Hat. She is passionate about software freedom and free & open source tools, particularly in the creative domain: her favorite application is Inkscape. You can read more from Máirín on her blog at blog.linuxgrrl.com.

My main complaint with documentation is the various documents tend to be huge book-size manuals that try to account for just about every single case and variation, which can look very intimidating to users. Take the install guide, for example:

Also in this vein, I’d like to see some bits of our documentation become more task-oriented. Say I want to setup an Apache server on my Fedora install. Right now, a Google search for fedora apache or fedora httpd both give pages of largely outdated and sometimes wrong instructions from third party sites for doing this. Perform a similar search for opensuse apache, and the first two results are http://en.opensuse.org/Apache and http://en.opensuse.org/Apache_Quickstart_HOWTO, which walks you through installing the proper packages, opening ports in the firewall, as well as the distro-specific locations of logs and config files.

Imagine if a user searching for these sorts of common tasks/setups could come across some these types of step-by-step instructions written by people more experienced in “doing things the Fedora way.” Wouldn’t that be a great experience for new users?

Actually, http://en.opensuse.org/Installation/11.1_Live_CD seems to me so bad, that I cannot understand why (otherwise rather clueful) SUSe folks made it. Or, it might be good for advertising as http://shots.osdir.com/, but who would be informed by series of screenshots which he can make himself just by clicking “Next” button? Documentation should be for the moments when you need to do unattended HTTP installation from boot.iso and you don’t know how to make kickstart file.

So, yes, it might be there as PR or something for somebody who doesn’t know what is Fedora about, but it is not documentation.

What should fedora’s documentation aspire to? A COMPLETE AND DETAILED DESCRIPTION OF THE DESKTOPS FUNCTIONALITY. FULL STOP.

But this means documenting Gnome in Detail. Gnome as it applies to the Fedora Desktop. ‘Gnome Help’ is a start. But it is lacking to say the least.

Many may argue that it’s not Fedora responsibility to document gnome, But Gnome is the fedora Desktop, so it better get done. And done good.

Once the manual is complete, and I mean complete, it is then and only then that Fedora should start tackling the other areas that are currently being addressed by places like FedoraSolved, FedoraForum, bugzilla, mailing lists, and blogs.

I use it rarely. In fact, I think I used it 2 or 3 times in the 3 years I’ve been using Fedora.

If I wanted to get there, I’d simply type the URL directly.

Why don’t I visit it more often ? Well, Fedora is great, I’m having less trouble with each release :)

And when I do find myself in trouble, I prefer using the french community wiki, forums or IRC. First, it’s more fun to interact with someone instead of just reading, second they are in my own language.

What I like about docs.fp.o is that they are really well written and the page style is sober, yet good looking.

What could be improved is to have them up-to-date (the F9 user guide is a draft, F10 user guide is « comming soon » and localized. But hey, there are only so many hours a day and the docs team is composed of a finite amount of people. They are already doing a great job :)