Re: quo vadis, docs

We've been talking about doing usability studies on GNOME. Maybe it makes sense to do one on the website. One of the "personas" being tested could be someone who runs into a problem in the documentation and want to give feedback.


2009/2/9 Matteo Settenvini <matteo-ml member fsf org>
On lun, 2009-02-09 at 11:00 -0600, Shaun McCance wrote:
> We do get volunteers on a semi-regular basis, but we inevitably
> lose them.  It would be useful to identify why we lose them and
> fix those problems.  I'll readily admit that I'm partially at
> fault for not taking enough time to train them.  But there are
> a lot of hoops you have to jump through to start working on our
> documentation, and most people just don't care that much.

My complaints:

* DocBook is hard for beginners; I think there was a project called
"FoisGras" or something near that that did try to make things better.
People in 2009 expect to write docs into, not Emacs. And
the XML markup, easy as it could be, confuses the hell out of my mother.
@Luis and @Dan: she actually *DOES READ THE DOCS* because she learnt
that F1 can help you. Moreover, I'm what you'd call a power user, and
sometimes *I READ DOCUMENTATION TOO*, simply because some options are
too cryptic to understand even in GNOME. The manual I read the most?
NetworkManager. Technical terms are always hard; a glossary would help.

And I don't want to learn how to use git in order to contribute to
documentation, or whatever other automake/autoconf/xml2po/xgettext black
magic some uber-geek thinks it's cool this week (I'm obviously
exaggerating; after all, I'm a geek at the core too).

Add to this that a lot of users which read the documentation aren't
native language speakers (they don't even know English well), and so
they read the docs translated in their language...

The problem is, if you find a problem with the documentation, it doesn't
even crosses in your mind to report a bug; you take that the application
is working correctly, and someone will in due time fix that outdated
documentation. It's not a bug with the app; it's a problem with the doc.
It's a culture-related problem, I guess (hey, from tomorrow I promise to
start reporting documentation bugs).
However, I'm all beyond this culture. Bugs are for applications, not for
documentation, in my mind. Documentation should be fixed just by a
couple of clicks, not through an overly-complicated process.

By the way, has *ANYONE* tried to click on the "Contribute" links into ? No? Yup, broken links. I've
not fixed these myself just so you can still try them; however, this is
just a small example of something that make people who have searched
across a dozen pages in to contribute running off

(By the way, has anyone ever counted the number of clicks to get to a
certain goal inside the GNOME website? It's astounding the depth you can
get. If someone has ever studied something of web-marketing, you know
why I see this as horrific. We should "sell" our goals just like a
traditional company would.)

The actual process:
* surf the web for half an hour in order to understand how to contribute
* understand what package you want to contribute
* learn to use a couple of VCSs.
* use svn (now) or git (tomorrow) to download the sources
* learn docbook
* write the doc
* check them just to be sure you don't have a parsing error
* learn what is a patch, and how to make one
* create a patch
* submit a bug
* attach a patch
* hope it'll get in, freezes and all the rest scattered here and there.

Should really be:
* open documentation, see that it's wrong
* click on the upper-right link "Fix it!"
* the first time, insert your bugzilla username and password
* edit the page in the english locale
* you edit the page inside yelp
* (automatic submittal to the bug system, or to a wiki)
* message to the user "your bug id is #######. thanks for contributing!
You've helped to make GNOME better: you've made a difference."

Take a look at how Monodoc allows you to change documentation. Maybe the
best thing we could do is to set up a wiki with some XSLT stylesheets.

* you don't have a clear "start here" banner on your map in the GNOME
frontpage. People like to do things which are advertised as cool, not as
boring or complex. The "contributing" link is the *last* one in, whereas it should be a big colourful
button on the top of the page.

And talks about IRC,
mailing lists, handbooks... my mother doesn't know what IRC is. Is it a
small furry animal?

> > Plus, a prioritisation of documents for pre-release updates.
> The whole idea of Pulse was always to show what documentation
> needs the most love, which I think is about the closest we can
> come to a prioritization system.

Or, we can try to build also a community. People like statistics;
sometimes competition is a good way to have some work done. Look at
wikipedia, for example. Individuals race on who has the most number of
articles reviewed/written.
And the overall quality is quite good.

> --
> Shaun

Shaun is right, and I've always respected his work the most. It's hard;
and it's also more hard than it should be due to how the system works.

However, I give my spare time to work on anything anyone of you thinks
needs to be done. I'm not a native English speaker, but I'll do my best
to check my grammar.


desktop-devel-list mailing list
desktop-devel-list gnome org

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