rough draft of gnome-display-properties

[Phil Bull]

Hi Vikram, Dougie,

I disagree with both of you!

While all three of the sections Vikram wrote are really great
explanations of their respective subjects, they don't help the user in
any way. Very few users go to the documentation to find explanations of
a concept. If you were wondering what X11 was, what would you do?

a) Click System -> Preferences -> Display. Click the Help button. Wait
~5-10 seconds for the help browser to come up. Hope that there is a
topic on X11. Try and find the topic on X11.
b) Search Google or Wikipedia for "X11". Find an answer instantly.

If you don't know what X11 is, how would you even know to look in the
Display preferences help?

This isn't the sort of help that we need to be providing for our users.
People interested in learning about how the system works will go and
read a book or a webpage. The people we are targeting have a question or
a problem and want to know what they need to answer it or fix it. They
don't particularly care *why* they need to do the things that we tell
them, they just want to get it over and done with quickly so they can
return to whatever they were doing before they ran in to this problem.

Here's Shaun McCance's take on things [1]. PLEASE read at least the
first three sections, it explains the situation much better than I just
did.

In an effort to help people write the sort of help that users are
looking for, I've been working on a guide, which you can find a draft of
here [2]. This is based on discussions I've had with professional
technical writers, and techniques which I've learned about on technical
writing websites. I've been using my own guide to help me create some
documentation for GNOME, which I'm planning to release shortly. In the
mean time, please read the guide and let me know what you think!

Thanks,

Phil

[1] - http://www.gnome.org/~shaunm/quack/mallard.xml
[2] -
https://wiki.ubuntu.com/Philbull?action=AttachFile&do=get&target=WD-draft-Sept.odt

-- 
Phil Bull
https://launchpad.net/people/philbull