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 OpenOffice.org, 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 http://live.gnome.org/DocumentationProject ? 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 live.gnome.org to contribute running off screaming. (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 http://www.gnome.org/community/, whereas it should be a big colourful button on the top of the page. And http://live.gnome.org/DocumentationProject/Join 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. Matteo
Attachment:
signature.asc
Description: This is a digitally signed message part