[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

Re: User Guide update

Some thoughts on the UG, based on what I saw while converting it to build in Publican and publishing it for the F11 release:

A large part of the document is made up of listing the contents of the main menus of applications. The examples that Matthew pointed to in OpenOffice and KMyMoney are quite typical. As far as I can see, this material is pretty much useless to anybody. Anyone who wants to see what's offered under these menus is going to click on the menu, not look it up in documentation. Furthermore, as Matthew has already pointed out, most of this stuff is intuitive to anyone who has much experience with any recent, mainstream desktop on any platform, and is also a maintenance nightmare to keep up-to-date. Finally, the way that much of this has been written attempts to turn menu entries into connected English prose. Most of the time, this comes out OK, but my hat is off to those dedicated souls who have managed to translate the result into any other language! I strongly believe that all of this should go. Show no mercy.

The User Guide really needs to be re-thought on a fundamental level and deliberately planned out. The key questions are "who do we envisage reading this book?" and "what do we think that they need to know about Fedora from it?"

Off the top of my head (and all IMHO only):

I envisage two main groups of people in the target audience: people who have emigrated from other operating systems (primarily Windows) and a smaller group of people who have never owned a computer before (in particular, I'm thinking of socially disadvantaged people who might have received a rebuilt PC with Fedora on it).

To paraphrase an old retail maxim, nobody owns a computer to own a computer — people own computers to do stuff with them. Documentation needs to remain task-oriented.

So, what both groups that I named above need to know about Fedora is:

* Some background knowledge about Fedora, and Linux in general, eg:
* This is a totally different environment from Windows and Mac -- you can't expect software designed for those platforms to work on your computer, and need to be careful with hardware
* Task -- so where do I get software from?
* Task -- if I want to buy a printer, how do I know it will work with Linux?
* Task -- how do I perform the tasks that I used to do on a Windows computer, or that people say I need to have Microsoft Word for? How do I access my old files? * Linux is very secure -- the viruses and spyware that are part of the Windows world won't trouble you here.
* Task -- how do I make my computer safe from viruses and hackers?
(All the tasks above will be covered later in the doc; for now, it's enough to touch on these questions and refer readers to the relevant sections)

* Finding their way around the desktops -- this should cover all desktops that people in the target audiences are likely to encounter. From what I've seen, Xfce (and increasingly LXDE) are popular choices for old machines rebuilt by charities. For each desktop: * Task -- how do I know which of these applies to me? (screenshots are vital here) * Task -- how do I turn off/restart my computer? (I've seen even experienced Windows users baffled by this in GNOME...)
* Task -- how do I find the programs?
* Task -- how do I get new programs if I can't buy them at the store?
* Task -- how do I find my documents?
* Task -- how do I personalise my desktop -- change the wallpaper? change the screen saver? (This is very important to many people, I think it helps them "own" the machine) * Task -- how do I transfer a document to or from this floppy disk/CD/Flash drive? (and you might be surprised at how many people are still using floppies in these audiences) * Task -- how do I keep my computer up-to-date? How do I upgrade to a new version of Fedora (and will I have to pay for this?)

* Performing common tasks on the desktops (the stated raison d'etre for this book) -- again, this should cover each desktop that people in the target audiences are likely to encounter, and each desktop should have a separate section. Applications that are widely used on multiple desktops (for example, OpenOffice) should appear under each desktop -- common text can be xi:included into multiple sections of the document. For each task, only the default application for that task on that desktop needs to be discussed, plus any really widely-used application that's likely to show up on multiple desktops (OpenOffice, Firefox, and Thunderbird are the only ones that spring to mind). I think that the general categories identified in the User Guide in its current form are pretty good, and for most applications, I think there's at least some usable text in the doc already. The emphasis here is very definitely not to be comprehensive, but to point out major features and tell users where to find more in-depth help. In every case, the task is similar, for example:
* Task -- how do I write/edit/print documents?
* Task -- how do I transfer music to my MP3 player?
* Task -- how do I view/edit/print my digital photos?
* Task -- how do I access the web?
* Task -- how do I get/send email?
* Task -- where do I find games?

All of the above is only a rough outline straight off the top of my head; it's not meant to be anything more than a starting point for a content definition.

I agree with John that it would be nice to engage with upstream communities for some of this. For example, when we describe a particular desktop, I think we really should try to develop some common text that would be useful for other distros too. However, I think there's value in a distinctly Fedora User Guide -- that branding is valuable, and it imparts confidence to users that "yes, this book applies to me and to my computer". So while (for example), we might share a general description of the KDE desktop with/from the upstream community, a KDE User Guide will no doubt go into far more detail than we would ever want to.

Finally, I hope it goes without saying that none of the above is intended to detract in any way from the hard work and dedication that people have put into developing the User Guide. With a little more direction and definition, the genuinely good and useful content that already exists in the guide can be brought into focus and become useful to people starting out in Fedora.


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]