xkcd today- lovely.
in [UK Mac]
|
Prev: Unsupported Firefox...
Next: It's here (at last)
From: Ben Shimmin on 24 May 2010 03:11 D.M. Procida <real-not-anti-spam-address(a)apple-juice.co.uk>: > 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. Well, don't come crying to me when Microsoft don't bother implementing two thirds of it in their browser... b. -- <bas(a)bas.me.uk> <URL:http://bas.me.uk/> `Zombies are defined by behavior and can be "explained" by many handy shortcuts: the supernatural, radiation, a virus, space visitors, secret weapons, a Harvard education and so on.' -- Roger Ebert
From: D.M. Procida on 24 May 2010 03:29 Ben Shimmin <bas(a)llamaselector.com> wrote: > D.M. Procida <real-not-anti-spam-address(a)apple-juice.co.uk>: > > 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. > > Well, don't come crying to me when Microsoft don't bother implementing > two thirds of it in their browser... In fact, I'd started to add a sentence wondering whether MS's Internet Explorer developers had only had access to the new and interesting summary, and not the specifications. If only I'd kept it in, I would have discomfited you and WON THE USENET ARGUMENT in advance. Daniele
From: Jim Ellison on 24 May 2010 03:43 xzRowland McDonnell <real-address-in-sig(a)flur.bltigibbet.invalid> wrote: > Tim Streater <timstreater(a)waitrose.com> wrote: > > > real-address-in-sig(a)flur.bltigibbet.invalid (Rowland McDonnell) wrote: > > > > > Tim Streater <timstreater(a)waitrose.com> wrote: > [snip] > > > > The techies like not being bothered by idiots ... > > > > Very often true but not always. > > All sweeping statements are false[1]. > > > > > It's only a bit > > > > later,as the field takes off, that something approaching proper text > > > > books start appearing. > > > > > > But such things accessible to those other than already highly skilled > > > already well informed existing technical experts are very rare. > > > > > > I've read modern computer manuals - there seem to be two types. The > > > `consumer' manuals which are little more than a poorly structured > > > collection of tips and tricks considered `cool' by the author; and the > > > `serious' manuals which might well be more complete but certainly are > > > impenetrable to the layman (i.e., me). > > > > I'd say that's because they're meant to be textbooks. The consumer books > > are a waste of space. > > A textbook, if competently written, is not inaccessible. These computer > manuals are inaccessible. > > I think that they are meant to be concise reference works for the fully > informed experts - not textbooks. > > > > I never had this problem with old-style computer manuals, but something > > > went wrong in the 1980s with writing that sort of thing. It got > > > bureaucratized, did the process, and all the technical manuals I've read > > > recently have been unfit for purpose. All of 'em. > > > > Mmmm, things did get more complex, though, wouldn't you say? > > Erm, nope - the tech got easier to use in itself, but the manuals got > worse. > > The manuals for my HP32E are very much smaller and more useful than the > manual for my HP32S (calculators). The difference? Ten years. They do > pretty much the same job: the 1970s calculator had two excellent little > manuals; the HP32S one whopping great big one which (looking at the > non-programming bit only) used about four times as much text to say a > good deal less. > > The later manual is bigger, contains less information, and is very very > much harder to use and to understand. > > Modern technical manuals are written according to a dysfunctional scheme > that causes them to be created `not fit for purpose'. > > [snip] > > Rowland. > > [1] Yes, I know.
From: Rowland McDonnell on 26 May 2010 11:16 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? Just to be a barrier? <shrug> I've never seen any reason to write specifications in any way other than one which was meant to /useful/. For some reason, in the last few decades, the idea that written documents should be hard to read has grown up - where does this come from? The only reason for doing it that I can see is to exlude people, to make sure that the aristocracy of knowledge have power over us hoi polloi. <shrug> Look at how the bastards behave and *then* try to tell me that's just paranoid raving. 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: Adrian on 26 May 2010 11:19
real-address-in-sig(a)flur.bltigibbet.invalid (Rowland McDonnell) gurgled happily, sounding much like they were saying: >> Their problem, which is a very real one, is that those specs are just >> that; specs. So they have to be full and unambiguous. Readbility must >> necessarily be a very secondary consideration. > Readability is the proper main concern for writing such specs - for > without good readability, the written specs are of inadequate quality > through being unfit for purpose. > > That is, specs are useless if they are not useful. > > Surely even you must admit that, Peter? Specs cannot be useful unless > they are accessible - which includes: readable. > > And - speaking as one who *CAN* produce very very good tech docs when he > puts his mind to it - I can tell you there's simply no excuse for bad > tech docs except a desire to confound and confuse. Although, of course, all tech docs are written with the comprehension level and pre-existing knowledge of a specific target audience in mind. >> Manual writing is a specialised and highly skilled job. They need to >> get a manual writer onto it. But of course that costs money... > They do get the specialists. Unfortunately, the problem is that there > seems to have been a bad culture of technical manual writing that has > taken over - a form of technical writing that is apparently intended to > be a barrier to comprehension to all bar `those in the know'. Not at all. It's just that for much technical documentation to include everything required for a total neophyte to comprehend the concepts, it'd be four foot thick with 99% utterly wasted on 99% of the actual audience. Take an appropriate audience as your baseline, though, and it suddenly becomes far more manageable without any loss of information to those by whom it will primarily be used. |