Crowd-sourcing proof-reading the HIG
 

Hi all,

There's a bug open that the Maemo HIG needs proof-reading by native speakers
I just created a wiki page to track a crowd-sourced proof-reading effort and proof-read the Introduction and made some suggested changes.

Do any native speakers have some time to help with this, pick a section, and make some suggested changes? The changes I'd like to see made are not so much with the content, as with grammar, fluidity & style.

If you feel up to the task, and you have 10 minutes to spare for a section, please sign your name after a section (to let someone know you're working on it), make the text of the section a clickable link to the text, add the "notes" link after it, and click on it to start writing your suggested improvements. If you can only partly proof-read, don't worry about it, do what you can, add a note at the end saying how far you got, and save your work.

I'll be keeping tabs on the index page, spotting if people put dibs on a section and then don't finish notes, so we don't end up with unfinished work, and we'll start getting changes integrated next week to make sure that the changes are integrated into the final version of the HIG.

Thanks all!
Dave.

Re: Crowd-sourcing proof-reading the HIG
 

I'll try to do some.

First sentence:
ouch!

Re: Crowd-sourcing proof-reading the HIG
 

I proofread text professionally and I'm more than willing to proofread the entire thing. I'm a native speaker and longtime Maemo user. I'll start working on it this weekend. I just ask that someone check it all afterwards to make sure that none of the meaning has been lost with my changes.

EDIT: Oh wow... yeah... this might be less proof-reading and more rewriting, but hope you like what I come up with whenever I finish it.

Re: Crowd-sourcing proof-reading the HIG
 

OK, so I've done a bit so far (and anyone is free to change even more, I'm not thrilled with some of the wording)

It seems that the best way to do this is to copy the original text into a wiki page, do some minimal wiki markup (use ==Title== and ===Section=== headings where appropriate, and maybe do some HTML links), then save the original text.

Then edit the page, and save your edits when you're done, along with a clear description in the comments field.

By doing this, your edits to the text will display clearly in the "history" page, all nicely marked up for anyone wanting to see what you did.

So, proofreaders, please copy over the raw text, save, then edit!

(Dave, can you put those instructions on the wiki page?)

Re: Crowd-sourcing proof-reading the HIG
 

Probably also worth emphasising - if using the wiki - to save often to make conflicts easier to resolve.

However, I wonder if one of the proper real-time online collaborative editings systems (e.g. as a baseline, Google Docs) would be easier.

It's also disheartening - seeing zerojay (welcome back!) and qole's summaries - that something quite so... Finglish has been put out at all.

Re: Crowd-sourcing proof-reading the HIG
 

It's not always fair to expect the well-meaning people working on Maemo to always have perfect English considering Maemo has always been such a global project... but that's okay so long as it's remotely understandable. I deal with having to decypher way worse anyways, so this really isn't that bad.

(Yeah, guess I am back. Thanks... after waiting a full year for my N810 developer discount to come through, the battery on the new tablet died less than a month after receiving it. I was sure it was dead for good... but then it came back to life just yesterday! Wow... I'm so far behind, lol.)

Re: Crowd-sourcing proof-reading the HIG
 

I've said it before, and I'll probably end up saying it again, but it's good to see you around again, zerojay. :)

Re: Crowd-sourcing proof-reading the HIG
 

Hi,

I disagree - we have a tool, we should use it. And, as Murray pointed out on the mailing list, this will be a good test case for the nascent plan to have the official docs in the wiki.

That's quite unfair. First, it's not Finglish, it's Spanglish. The HIG was written by the authors listed on the front page, Ivan and Joaquim from Igalia, and was based on the GNOME HIG.

The whole point is to turn a quite long, difficult & tedious process into one which is easier, because it's spread out over many people.

zerojay: Thanks for your offer to proof-read the whiole thing! I'd suggest proceeding section by section, staking claim in the cover sheet first, saving your work after each section - to reduce any chance that you're working on the same chapter as someone else (say, me, qole or Murray).

We'll all have a chance to review corrections afterwards.

Thanks!
Dave.

Re: Crowd-sourcing proof-reading the HIG
 

The use of a wiki for the long-term maintenance of a document (something I'd argued for for most of the pages on maemo.org) is a different use case from a lot of people working simultaneously on the same section of document.

If you've got processes in place to minimise the number of edit conflicts; fine - otherwise, I'm pretty certain changes will be lost. Mediawiki just isn't good at highlighting the differences between two conflicting saves - requiring the author to remember many of their changes. (IME, anyway)

OK, it's Spanglish. However I'm still disappointed: not at the folks at Igalia but that I strongly believe the success of a platform - especially a mobile platform - is based on the development tools & infrastructure.

Complex, semi-documented APIs; unclear HIGs; poor IDEs are fundamental problems, which aren't necessary ("accidental" rather than "essential" complexity).

Such problems increase the activation energy and willpower required by a developer; and that's bound to dissuade some developers from persevering.

That's why I'm disappointed [at Nokia].

Re: Crowd-sourcing proof-reading the HIG
 

And that's why we're proof-reading it to ensure it reads well. And we'll solve the other issues one by one over time, as the resources needed to keep them up to date are made public.

Dave.

Re: Crowd-sourcing proof-reading the HIG
 

Well, what I'll do is just do the whole thing since it doesn't seem to be that long... I'll post it and I'll let you guys decide if you want to use the whole thing, cherry pick certain parts or whatever you want.

Re: Crowd-sourcing proof-reading the HIG
 

Hi zerojay,

Thanks again for the offer - the issue, though, is concurrency. If you do the whole thing, there's a high chance that you will be duplicating work someone else has already done, which would be a shame. If you do section by section in the wiki, it may well happen that everyone else will let you away with it anyway ;)

Re: Crowd-sourcing proof-reading the HIG
 

Hi all,

It's been a couple of weeks, and aside from Qole's early burst, there hasn't been much movement on proof-reading the HIG.

Anyone have some time to pick at some sections today? I'll do some before the Sprint meeting next Tuesday, but I've been swamped with Gran Canaria Summit organising stuff for the past couple of weeks, so a helping hand would be appreciated.

Thanks!
Dave.

Re: Crowd-sourcing proof-reading the HIG
 

Dave,

I was planning on it, but I've been busy this week. I'll try to get to some sections today.

Tim

Re: Crowd-sourcing proof-reading the HIG
 

I just assumed zerojay was going to do a bunch of proofreading... He talked like he was going to do the whole thing... :) I can do some more, if you want...

But I thought the point of this was supposed to be crowdsourcing, and I'm not much of a crowd.

Re: Crowd-sourcing proof-reading the HIG
 

From Wikipedia.
So by the definition, you and Tim are a Crowd :D

Re: Crowd-sourcing proof-reading the HIG
 

And me, don't forget me.

They say three's a crowd.

Dave.

Re: Crowd-sourcing proof-reading the HIG
 

Yep, that was before two of the games I was working on hit crunch time. Working 13 days straight, including weekends and public holidays and at least 2 extra hours per day... so yeah... my head is going to explode. :)

Re: Crowd-sourcing proof-reading the HIG
 

OK, I did a big text dump, chapters 4-6 have the original text added, please begin editing!

My favorite chapter title? "Menu Items Sensitiveness"

Re: Crowd-sourcing proof-reading the HIG
 

Re: Crowd-sourcing proof-reading the HIG
 

Sorry... Looking at the wiki page late in the game... Are we now doing complete edits of the text? It appears that the original text is posted and the "Notes" text is an exact copy. Which chapters are actually complete at this point?

Edit: Ah, ok... The sections with signatures are the completed one. Sorry.

Thanks,
Tim

Re: Crowd-sourcing proof-reading the HIG
 

There was me thinking that link referred to "a game of bingo gone horribly wrong"...

Re: Crowd-sourcing proof-reading the HIG
 

Question: Are we being asked to provide better section titles as well? Or just body text?

Tim

Re: Crowd-sourcing proof-reading the HIG
 

All right... I've just completed a few chapters. I didn't change any section names, although I wanted to. More later.

Tim

Re: Crowd-sourcing proof-reading the HIG
 

Hi guys,

I'm Joaquim Rocha, one of the authors of Hildon HIG and I wanted to say I really appreciate the effort you're doing on reviewing the HIG's English.

I must also say I hadn't replied yet to this thread because some of the comments and attitudes expressed here that really made me sad. I and Iván put a lot of effort into the documentation and while there is, of course, room for improvement, I think it is not as bad as people have been saying here. The whole project from the beginning was intended to be just an initial draft from which things should be improved and fine tuned.
I think the comments towards our nationalities are pretty sad as well. Some of you started by saying the docs were written in Finlish, then turned to Spanglish when I'm not even Spanish. Iván is Spanish and I think that "Spanglish" really puts down one's work and effort on doing something write.
It is clear to me that some people like to criticize for free and in a negative way with all the safety and easiness of the ol'internet, instead of improving what's actually wrong.

Having said that, I need to thank Dave Neary for opening this thread and encouraging me to reply. Thank you to all the people who have been working to improve the documentation. We appreciate it.

Cheers,

--
Joaquim Rocha

Re: Crowd-sourcing proof-reading the HIG
 

Your efforts are appreciated, and it wasn't clear that you and Iván has been doing so much in your spare time.

Negative comments aren't directed at the author - but at Nokia for under-investing in such a core deliverable for a consistent platform. Human interface guidelines have never been well invested in, despite numerous offers to do so over the past 4 years.

Finally, FWIW, "Finglish" is a term which has been used a number of times on #maemo to describe the text which oftens comes out of Nokia's delivered applications and is meant in a fun - not derogatory - way.

It's not clear why it should be proof-read for free, when it wasn't produced in a collaborative manner (although the community will, because it benefits being clear). For example, if a reviewer disagrees with a point, can that be changed? I doubt it, as this will have evolved out of Nokia's "UI Specifcations" (and one would hope Nokia's apps are consistent with it).

Re: Crowd-sourcing proof-reading the HIG
 

These are really good points. And, as one of the contributors to the proof reading, I must say that there are several areas that I feel should be reconfigured, rewritten, and/or rethought. This has nothing to do with the amount of hard work that was put into the original document. It's just that some items appear not to have enough context or they weren't thought out completely.

If we can make suggested changes to content (and not just vocabulary and grammar), please let me know, as I would love to help out.

Thanks!
Tim

Re: Crowd-sourcing proof-reading the HIG
 

Nevertheless, all work is done by individuals, so when something which wasn't there before appears, the first reaction shpould presumably be "Thanks! This is a great start" rather than "this is rubbish".

The sooner we realise that the best way to have community co-production of Maemo is to have Nokia employees and contractors be considered as members of the community (both by themselves and community members), the better.

The HIG doesn't need to be proof-read. It would be better with some changes in language. The Maemo community has for years begged for Nokia to give more ways for people to help themselves more easily. Publishing documents like the HIG under a free documentation licence, and encouraging co-creation of the document, is one more way for people to help themselves.

No-one is requiring the community to proof-read the HIG. I thought it might be something which would fulfill a number of goals:

1. Be a fun way to help out if you only have a few minutes to give, and quickly see your suggestion make the project better
2. Have a concrete example to show to Nokia management of the community making Maemo better
3. Generate a better document for developers of Maemo applications

If you want to wait until there are documentation resources for revising the document, then wait. If you want to make a better document for everyone involved, then help out. This is not Nokia looking for free labour, it's us taking what we're given and improving it if we're unhappy with it.

Cheers,
Dave.

Re: Crowd-sourcing proof-reading the HIG
 

I don't think most of us are putting down the hard work the paid contractors did to produce the initial draft of the Maemo HIG.

But, I'm sorry, but it really does need to be proof read and corrected by native speakers. The grammar and syntax are very strange.

I think we are mostly shocked that this proofreading wasn't done before the document was released by Nokia.

It would be a completely different story if this document was produced by volunteers as a community-driven effort, instead of an official Nokia developers' document.

I'm glad this thread keeps getting bumped, it reminds me to go and do a bit more work on it.

Re: Crowd-sourcing proof-reading the HIG
 

Honestly, between "release early, release often" and "don't release until it's perfect" (which it never is), I am happy to encourage Nokia in the first direction. I would hope that any efforts in that sense are welcomed by the community, rather than criticised, since criticism will only convince people that they should not be releasing betas and alphas of things that aren't ready yet.

Cheers,
Dave.

Re: Crowd-sourcing proof-reading the HIG
 

Dave: very good points. Thanks.

Re: Crowd-sourcing proof-reading the HIG
 

Many thanks to Tim Samoff and Alan Bruce, who along with myself have proof-read the entirity of the Hildon HIG. I talked to Joaquim at GUADEC, and he had already integrated the changes which were available at that point, I will ping himself and Ivan again to get the more recent changes intgrated and get their feedback on the work that's been done so far.

As an added bonus, we have the entire text of the HIG in the wiki now, so suggestions for improving it, sections that could be added, etc. can be added to Talk pages, please feel free to make suggestions & improvements, and I will make sure that they get rolled upstream once in a while.

The new version of the HIG, complete with our work, will be published soon.

Cheers,
Dave.

Re: Crowd-sourcing proof-reading the HIG
 

With screen shots! :D

...still needs a little work (I've been busy), but it sure is sweet to see this happen!

Tim

Re: Crowd-sourcing proof-reading the HIG
 

Please (Nokia) guys, feel free to bring us more to check/do. A said earlier, we're more than happy to do the work for the community. (Wish I had the time to do what I was going to, but it got done quickly enough anyways.)

Re: Crowd-sourcing proof-reading the HIG
 

Hi Zerojay,

While this worked well because it was announced, and I did some basic infrastructure for it on the wiki, nothing I did needed special access to anything. I just copied text from a DocBook document over to the wiki, and invited people to contribute, and got the authors to buy into it.

If there is any document that you're unhappy with, please create a bug, and we will do the same thing again, no problem.

For released docs, this is great, of course. The problem is when we're fixing released documentation which is substantially different from the "private" in-progress documentation, and we don't have an up-to-date version online. That's where I'm working with Nokia to ensure that things are done in a way which allows us to contribute.

Cheers,
Dave.

Re: Crowd-sourcing proof-reading the HIG
 

Is there any way we can extend this to the strings used by the default applications as well as localization without needing to wait until a release to file a bug and then hope that maybe the next release a few months down the line will fix it, as has been the case before?

I fully realize that something like Freemantle and the device it runs on will need to stay an internal secret so that you don't give away anything to the competition, but I want to see Freemantle be *everything* it could be. I don't want to notice a thousand little English errors, as small as they might be, all over the operating system. Is there anything we can work out to make this happen?

Re: Crowd-sourcing proof-reading the HIG
 

The Fremantle betas and alphas were released for that purpose. Most of Fremantle has already been released for review and patches.

Have you installed a beta image and had a look around, by any chance?

Thanks,
Dave.

Re: Crowd-sourcing proof-reading the HIG
 

Hey, I was talking to X-Fade about this a while back. We were thinking that the new package management interface would be a good way to do this. Basically, you find an app and leave a comment to what you would like to see changed (description strings, localization notes, etc.). These comments go directly to the package maintainer, so hopefully they'll act on suggestions.

Initially, I was wondering if Bugzilla would be better for this, but keeping all of the suggestions/notes attached to the packages in the management interface works just as well.

Does that make sense?

Tim

Re: Crowd-sourcing proof-reading the HIG
 

I don't use Debian but another flavor of Linux (ArchLinux), so installing/running the SDK ends up being *far* from trivial, but I tried. Also from my previous experience, the SDK lacks a *ton* of default apps, so a lot of this checking can't even be done anyways, though I hope that's not the case with the Freemantle SDK.

Bugzilla's good for leaving changes we'd like to see since it supports attaching patches and so on... Tim, I guess it depends on whether or not application developers want to have *another* place to check for fixes, bugs, etc...

Re: Crowd-sourcing proof-reading the HIG
 

Except that these things aren't exactly application "bugs," but rather subjective (mostly), human "bugs." So... For now, I say that we should use it and see what happens.

Tim