xkcd today- lovely.
in [UK Mac]
|
Prev: Unsupported Firefox...
Next: It's here (at last)
From: Rowland McDonnell on 26 May 2010 12:28 Richard Tobin <richard(a)cogsci.ed.ac.uk> wrote: > Ian Piper <ianpiper(a)mac.com> wrote: > > >I find the same with the W3C documents: they confuse comprehensiveness > >with comprehensibility. They *may* achieve one of these but definitely > >not the other! > > You should try editing one. You write what seems a perfectly clear > sentence, and then someone points out an imprecision or ambiguity > which has to be corrected. In a textbook you can make an imprecise > statement and clarify it later; if you do that in a standard you > get complaints. You have to be explicit about everything. And that is the only possible excuse for writing a hard-to-read standards document: the need to remove ambuguity. Meeting that requirement while also ensuring it's easy to comprehend is a right sod at times. There aren't any other excuses. > And you also get people complaining about statements which are correct > but aren't expressed in the way they'd like. Proper writers are needed on the job. > If you, as editor, > disagree - perhaps you think their change makes it less clear - then > the standards process (which aims for consensus) makes it very > time-consuming to proceed in the face of a determined objector. Eek. Yers, I can dig that. Still, one can always cause the process to grind to a halt in the hope that anyone pratting around will see the error of their ways eventually. > It's > often easier to give in over such points, but it doesn't make for > readable standards. Standards documents need strong editors. -- Remove the animal for email address: rowland.mcdonnell(a)dog.physics.org Sorry - the spam got to me http://www.mag-uk.org http://www.bmf.co.uk UK biker? Join MAG and the BMF and stop the Eurocrats banning biking
From: D.M. Procida on 26 May 2010 12:32 Rowland McDonnell <real-address-in-sig(a)flur.bltigibbet.invalid> wrote: > D.M. Procida <real-not-anti-spam-address(a)apple-juice.co.uk> wrote: > > > Ben Shimmin <bas(a)llamaselector.com> wrote: > > > > > Ian Piper <ianpiper(a)mac.com>: > > > > > > [...] > > > > > > > I find the same with the W3C documents: they confuse comprehensiveness > > > > with comprehensibility. They *may* achieve one of these but definitely > > > > not the other! > > > > > > The HTML5 spec looks to be the worst yet. There's no way I'm going to > > > read that all the way through -- I'm just going to buy a book which > > > summarises what's new and interesting. > > > > Well, what do you need - specifications, or information about the new > > and interesting? You won't generally find one in the other. > > > > Specifications documents need to be comprehensive, rather than readily > > comprehensible. > > Who ever came up with that idea? > > Seems to me that a spec document must be readily comprehensible if it's > to be useful - and if it's not useful, what was the point in creating > it? It needs to be comprehensible to the people who have the skills to make use of it, but it need not be comprehensible to anyone else. It's not human nature to be good at assimilating the content of exhaustive technical documents. It's not my human nature, certainly. Daniele
From: Richard Tobin on 26 May 2010 13:15 In article <1jj3zbx.395r7h1y3u5vkN%real-address-in-sig(a)flur.bltigibbet.invalid>, Rowland McDonnell <real-address-in-sig(a)flur.bltigibbet.invalid> wrote: >> And you also get people complaining about statements which are correct >> but aren't expressed in the way they'd like. >Proper writers are needed on the job. Many companies and universities generously allow employees to work on standards in addition to their "real" work. These people are experts in the technical subject, but their writing abilities vary. Paying "proper writers" as well is generally out of the question, and of course would still require the technical experts to check every sentence. -- Richard
From: Rowland McDonnell on 26 May 2010 13:14 D.M. Procida <real-not-anti-spam-address(a)apple-juice.co.uk> wrote: > Rowland McDonnell <real-address-in-sig(a)flur.bltigibbet.invalid> wrote: > > > D.M. Procida <real-not-anti-spam-address(a)apple-juice.co.uk> wrote: > > > > > Ben Shimmin <bas(a)llamaselector.com> wrote: > > > > > > > Ian Piper <ianpiper(a)mac.com>: > > > > > > > > [...] > > > > > > > > > I find the same with the W3C documents: they confuse comprehensiveness > > > > > with comprehensibility. They *may* achieve one of these but definitely > > > > > not the other! > > > > > > > > The HTML5 spec looks to be the worst yet. There's no way I'm going to > > > > read that all the way through -- I'm just going to buy a book which > > > > summarises what's new and interesting. > > > > > > Well, what do you need - specifications, or information about the new > > > and interesting? You won't generally find one in the other. > > > > > > Specifications documents need to be comprehensive, rather than readily > > > comprehensible. > > > > Who ever came up with that idea? > > > > Seems to me that a spec document must be readily comprehensible if it's > > to be useful - and if it's not useful, what was the point in creating > > it? > > It needs to be comprehensible to the people who have the skills to make > use of it, but it need not be comprehensible to anyone else. Yes indeed - but modern tech docs fail to meet that spec. > It's not human nature to be good at assimilating the content of > exhaustive technical documents. All such claims about `human nature' are cobblers, and you know it. So how about less dishonesty in future, eh? > It's not my human nature, certainly. Phooey. No such thing as `human nature'. Just because you find modern tech docs to be hard to understand does not mean it has to be this way. Old style exhaustive technical documentation is written using a different outlook, different structures, different aims. Old style *good* tech docs are easy for me to assimilate. Very easy, as it happens. I find modern technical documentation to be nearly impossible to assimilate - I can only do it if I write my own manual explaining what I want to do, and I can do that only by working very hard studying the documentation and investigating the equipment concerned. It's a huge job: the documentation is so poor as to be a barrier in almost all cases. And this is because the documentation has changed radically - it's a fault in the writing. Rowland. -- Remove the animal for email address: rowland.mcdonnell(a)dog.physics.org Sorry - the spam got to me http://www.mag-uk.org http://www.bmf.co.uk UK biker? Join MAG and the BMF and stop the Eurocrats banning biking
From: Rowland McDonnell on 26 May 2010 14:15
Richard Tobin <richard(a)cogsci.ed.ac.uk> wrote: > Rowland McDonnell <real-address-in-sig(a)flur.bltigibbet.invalid> wrote: > > >> And you also get people complaining about statements which are correct > >> but aren't expressed in the way they'd like. > > >Proper writers are needed on the job. > > Many companies and universities generously allow employees to work on > standards in addition to their "real" work. These people are experts > in the technical subject, but their writing abilities vary. I spy a big red herring - so what? And, for that matter, what about my various other points that you chosen to ignore without comment and without even mentioning that you were rudely ignoring them? Anyway, back to your point even though you rudely dismissed my points without comment: They go about the job in a fashion intended to be hard to understand - they follow the standard process, you see, and it's meant to be a barrier to comprehension. It's also meant to be quick and easy to produce. No thought is given to the read side of it - these documents are written for the convenience of the author(s). That is the wrong attitude to take. Thing is, the process used does produce documents that can easily be verified to have negligible ambuguity where it matters. Check it out - I'm sure that's the reason they write 'em like that, convenience for the authors. > Paying > "proper writers" as well is generally out of the question, Quite irrelevant - the very best technical authors are those who are not employed as such. The very best are engineers with a bent for writing, who are also interested in communicating their ideas. Those who go into technical writing tend to have no idea what their audience needs from their writing, since they are mostly not very technically minded/competent people themselves: technical authors I have known lack the mindset even to understand that there is such a thing as `deep technical understanding'. > and of > course would still require the technical experts to check every > sentence. Every sentence is subjected to minute scrutiny by a lot of people in the case of all RFCs. So that objection is null. What's a `proper writer'? I am one such - a trained, experienced professional technical writer, me. It's nothing special, the writing stuff. The writing ability of `proper writers' varies. When I refer to `proper writers', I don't mean `those employed primarily to write' because that sort of writer is often very bad. As I wrote before, and as you snipped rudely without comment: ------------------------------------------------------------ And that is the only possible excuse for writing a hard-to-read standards document: the need to remove ambuguity. Meeting that requirement while also ensuring it's easy to comprehend is a right sod at times. ------------------------------------------------------------ Thing is, bearing that in mind, I reckon it'd be easy to write tech docs that are an order of magnitude easier to understand than RFCs. They're written using a style that is deliberately obfuscated and hard to understand. Rowland. -- Remove the animal for email address: rowland.mcdonnell(a)dog.physics.org Sorry - the spam got to me http://www.mag-uk.org http://www.bmf.co.uk UK biker? Join MAG and the BMF and stop the Eurocrats banning biking |