   Writing Quality Standards 1st Draft (comments)
  If you'd like to comment on the draft Writing Quality Standards, please do so here...   
  Server seems to be down.   ;  I write colour with a 'U' [razz]. Just because you lot in the US like to leave out letters doesn't mean that I want to litter my code with spelling mistakes [grin]. Usually though, I do a conversion macro for those who want to spell it differently.   ;  I'm Australian, so I also typically use 'real' English, but I think for this project we're better off having the lessons and tutorials consistent - plus as mentioned it's spelt without a u in the code, so it'll also mean consistency with that.   ;Quote:Original post by KazgorothI'm Australian, so I also typically use 'real' English, but I think for this project we're better off having the lessons and tutorials consistent - plus as mentioned it's spelt without a u in the code, so it'll also mean consistency with that.I don't mind writing English English translations [wink] Maybe with a header file with typedef'd english equivalents of gl functions [grin]I'm just kidding btw.... sort of. :p   ;  [rant]I disagree with the prohibition of expletives as they form a fundamental part of Microsoft's source code.[/rant]Seems to work :)Regarding Quote:Ideally the written explanation should be able to stand alone I think this highly depends on how we structure the tutorials. Currently the tutorials only stand alone, appart from the net. You need to read the previous tutorials before you attempt any new ones. Obviously making each tutorial independent of every other tutorial is infeasible. If we decide to use tutorial trails, things will get a bit tricky because each trail must build appropriately (difficult for the author of the tutorial). I think we should define recommended reading section at the top of each problem set (tutorials are arranged in groups that address specific problems) that define what is necessary for understanding. If we do this per tutorial, we will have a maintainence nightmare when we try to add a tutorial in the beginner section.   ;Quote:Original post by llvllatrixRegarding Quote:Ideally the written explanation should be able to stand alone I think this highly depends on how we structure the tutorials. Currently the tutorials only stand alone, appart from the net. You need to read the previous tutorials before you attempt any new ones. Obviously making each tutorial independent of every other tutorial is infeasible.Actually, I meant that they should make sense if for some reason someone reads them without the sample source, it's obviously pretty infeasible to have each completely independant from all of the others.  I'll try adjusting the language to better reflect this.Quote:Original post by BBBHere is my suggestion:[...]Thanks for the input, I'll see about making an addition specifically addressing humour, as I do agree that if used appropriately it be be a good way of helping people remember and making things a little less "dry".  Any more thoughts on the matter are of course welcome, I'll let people know when I've made an update to the draft containing some potential guidelines.  I'll also have to talk to Oli about perhaps making some sort of markup available in the design.   ;Quote:Original post by BBB#3: Separate rants from the rest of the text (and don't expect people to read the rants because some will skip them = don't put vital information in them).Any thoughts?No rants.Personal opinions about "X is evil"/"Y is groin-grabbingly awesome" are not really appropriate for the medium.Humor is fine (welcome, even). Fair comparison of advantages and disadvantages of products/techniques/etc is fine. Outright bias and opinionated ranting is absolutely not.Basically, anything that can be inserted into these "rant" tags you suggest, can be cut entirely. This basically includes all Microsoft-bashing and *-bashing/*-worshiping as well as any other off-topic asides that don't add anything to the tutorial.Remember - less is more.   ;  Agreed, no rants. Humor is still very sketchy because of our wide auidence. It may help a few english readers remember the subject but will probably confuse the majority of non-english readers who are attempting the tutorial. Instead we should concentrate on making the subject matter more enjoyable. If that is not possible, then make the dry parts really short.   ;  ||v||atrix is right, the people who're no native speakers of English (me, for instance) won't understand some jokes (and that pisses me off sometimes, when the jokes make up a large part of the text and I can't see what it means), so keep them simple and short or leave them out.And I agree with Andrew, we shouldn't bash anyone(even if he/they would deserve it..) because this might make some of the guys out there putting our work aside.   