Uncategorized

Fedora’s Documentation

Do you use Fedora’s documentation at docs.fedoraproject.org?

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?

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.

Discussion

10 thoughts on “Fedora’s Documentation

  1. Make a online survey like any other sites.

    And I first go to Fedora Wiki and follow a link to Fedora docs. And I check the site often, waiting to see a Fedora 10 User Guide.

    Posted by Byte Corrupto | May 30, 2009, 3:30 am
  2. 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:

    http://docs.fedoraproject.org/install-guide/f11/en-US/html/

    compare this page to

    http://en.opensuse.org/Installation/11.1_Live_CD or http://en.opensuse.org/Installation/11.1_DVD_Install. The table of contents for our install guide is almost as long as openSUSE’s entire install instructions with giant screenshots. They found the two most common cases, Live CD and DVD (I’d probably add upgrading from an existing install as well), and documented the most common paths with diagrams and suggestions on what to do.

    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?

    Posted by Ricky Zhou | May 30, 2009, 4:55 am
    • 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.

      Posted by Matěj | June 7, 2009, 5:58 am
  3. Hey.

    I actually wasn’t aware of this, and the Security guide and the SE Linux guide look quite promising. Thanks.

    Posted by Richard | May 30, 2009, 5:05 am
  4. 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.

    Peace,
    Sam

    PS: Props to KDE ;-)

    Posted by Sam | May 30, 2009, 9:18 am
  5. 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 :)

    Posted by bochecha | May 30, 2009, 11:36 am
  6. I’d like to be able to download each doc, and to see them in single page (it’s easier to search a word with one ctrl + F).

    Posted by cirdan | May 30, 2009, 2:20 pm
  7. I like the new Security and SE-Linux documentation, the rest hasn’t been that helpful. I have always liked the documentation in the FreeBSD and Gentoo projects better.

    I wonder if a Fedorapedia (ala Wikipedia) would be a better approach? Perhaps most people don’t have well formed chapters to contribute, but little bits of ideas.

    I’d be willing to put some hours into editing and updating it.

    Posted by Chris | May 30, 2009, 7:30 pm
  8. Honestly, i go to the docs website only when i need to pick an URL from there and pass it to some newbie asking basic questions.

    Posted by Nicu | June 1, 2009, 7:04 am
  9. I use it, but rare because it is not useful search-wize. Search on wiki is mostly useless for me, maybe it works for others but I usually give up or go to google.com and do a search from there.

    I can’t even find pages that I know exist, or they are burried under lots and lots of “bad” links.

    But pages that are up there are of great quality, too bad I can’t find them as easy as I would like.

    Posted by valent | June 1, 2009, 12:18 pm
Follow

Get every new post delivered to your Inbox.

Join 63 other followers

%d bloggers like this: