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
--
fedora-docs-list mailing list
fedora-docs-list@xxxxxxxxxx
To unsubscribe:
https://www.redhat.com/mailman/listinfo/fedora-docs-list
