User Guide update

[Ruediger Landmann]

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.

Cheers
Rudi