On Sat, 9 Sep 2006, Shaun McCance wrote: > Date: Sat, 09 Sep 2006 14:32:00 -0500 > From: Shaun McCance <[EMAIL PROTECTED]> > To: Nickolay V. Shmyrev <[EMAIL PROTECTED]> > Cc: [email protected] > Subject: Re: Nine Months in Six Months > > On Sat, 2006-09-09 at 09:41 +0400, Nickolay V. Shmyrev wrote: > > ?? ??????, 09/09/2006 ?? 04:55 +0200, BJ??rn Lindqvist ??????????: > > > On 9/8/06, Don Scorgie <[EMAIL PROTECTED]> wrote:
> > > > Doc people do not have enough time. Its as simple as that. As shaunm > > > > I've known it. Most of the docs are now pretty out of date. Add in a > > > * Five months were developers play and pretty much destroy all the > > > docs we make. Presumably this is not out of malice. Developers who make the changes can take another step beyond the changelog and flag exactly what needs to be updated in the documentation and take out some of the guess work for those interested in improving the documentation. > > > * Four weeks were we can undo the damage caused and make GNOME > > > understandable. One of the ideas I considered in the past was that it should be easier to post frequent documentation point releases. If library.gnome.org ever happens and we had an online copy, showing the most up to date version of the documentation it would serve the same purpose, release early release often. The payoff for smaller improvements to the documentation would increase. > > > Maybe this problem can be solved by elevating the documentations and > > > the translations status in the project? For example, patches are very > > > seldom accepted if they introduce regressions in the software. But Obviously we dont want to turn away contributors but most developers require patches that more than barely work but that actually use the right patch format, correct style/indentation, inlcude comments, and a changelog entry. This could be a small requirement if we figured the right way to go about doing it. > You'll notice one of the new things in my proposal > was the idea of a string review. There are a lot > of crappy strings in our interfaces, often because > many of our programmers just don't have very good > English skills. The supposedly native English speakers are among worst offenders because they often dont even realise when they are using incomprehensible slang, or when they "utilize" poor word choices instead of other suitable words not requiring further localisation. > And that's fine. Hey, my German pretty much sucks, > although I can get by with it. I can't expect the > world to have perfect English. So we'll do some > string reviews instead, where we can fix problems. I dont think anyone is expecting perfection but it is not unreasonble to expect spellchecking, it just isn't particularly convenient at the moment. I think a docbook editor* which could do spelling and grammar checking would help in a big way. I was also thinking documentation is the perfect source to run against GNU Style and Diction[1] (two programs barely anyone seems to have heard of). It would be a big help if the Gnome documentation project could decide on a quantifyable style level we were aiming for against GNU style. What makes the HIG so great is how it empowers** users users out there who want a more usable and consistent Gnome, and gives them a good way to express to developers more specific improvements they would like to see. The right tools and perhaps better knowledge of the Gnome Documentation style guide could help empower users to make things happen. > I find myself shooting down this idea every single > release cycle. How do you think developers can make things easier for documentation writers and conversely are there ways documentation writers can be helped to give developers better feedback? Your the expert, you must have ideas? Sincerely Alan Horkan http://alanhorkan.livejournal.com [1] GNU Style and Diction http://www.gnu.org/software/diction/diction.html * The docbook support in Abiword has been substantially improved as part of the summer of code but I do not know if that would be enough to make it suitable to help with maintaining the Gnome documentation but I like Abiword so I mention it anyway. ** Apologies for the bullshit buzzwords but sometimes they are appropriate. Sincerely Alan Horkan Inkscape http://inkscape.org Abiword http://www.abisource.com Open Clip Art http://OpenClipArt.org Alan's Diary http://advogato.org/person/AlanHorkan/
_______________________________________________ desktop-devel-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/desktop-devel-list
