j4 | If I could walk that WAI I wouldn't need the guidelines

I think the person that wrote that article was having a strop because they'd not been listened to.

(I have no idea how well the new guidelines will work, mind - I've not had a chance to look at them properly.)

Me either -- sniping at the snipers is always easier than reading and understanding, let alone doing a better job of it. ;-)

The current guidelines were fuzzy enough in places, anyway. The new ones seem to be more centred around the user's 'experience', and less around the mechanics underneath the pages. I have no idea whether I'll spend more time, or less, crying over checklists as a result. (And whether they'll give me further ammunition to get the more jarring elements of the site cleaned up, and get a section up for people with learning disabilities, and all the other things I want to do. I suspect not, because we have no time nor money.)

It depends. I spend a lot of my job turning technical information into customer documentation. Sometimes, I can turn huge documents into a tiny paragraph of warning. At other times, it's the other way round. It very much depends on the target audiences for the two documents, and their relative backgrounds.

Techie language isn't necessarily high-density information that the user cares about - it can just be wordy. For example, I sometimes see things which specify exactly what and when can happen where - what actions you can take, what functions you can use, what programming language constructs will work here. From the techie point of view, there's a lot of information there. From the user point of view, summarising this the other way around can be a lot of more useful ("It works on everything except...") or they've specified a lot of things that are exactly how you'd expect them to be. Other times, the technical documents are badly structured (from a user point of view) or repeat themselves a lot.

Some technical documents can be exactly the other way round, though. They assume high level of knowledge in the reader. The explanation of the document is having to provide enough gloss so that it makes sense to a layman (e.g. a business executive who's expected to nod and smile at appropriate points, and know how the buzzwords inter-relate), or to cater for a variety of concerns (e.g. a document that's shared between, and aimed at, technical people and marketing people).

All jolly good points -- and I think this document should fall into the latter category (assuming high level of knowledge, requiring gloss). Though I'd have to look more closely before committing myself to that opinion.

A lot of the tensions in the world of web seem to boil down to the fact that everybody uses the web, and a lot of the people who use it know a little about it (and as we know, a little knowledge is a dangerous thing). It's such an interdisciplinary (bzz!) field that you're invariably going to have lots of people with different backgrounds, expectations, priorities, and languages -- and all too often people don't realise the extent of what they don't know.

Documentation can bridge those gaps, but how often does it actually just introduce another layer of misunderstanding, trying to be all things to everyone and ending up being nothing to anyone?

This post brought to you by the mood 'cynical'. (Tomorrow's scheduled to be a 'positive' day, so I might feel better about it then. You have to alternate, otherwise you either become an evangelist for things that don't work or you sink into the Slough of Despond.)

everybody uses the web

So not only are there are as many opinions as web users, but they're all experts. It sounds like linguistics (everybody knows how to speak) and education (everybody was a child).

Quite -- except that not only do they not realise the depth of the subject, they don't realise its breadth (i.e. that it encompasses a lot of other subjects) as well.

IMO the person with a narrow field of real expertise is worse than the person who doesn't know much about anything. The graphic designer with a fearsome paper portfolio (but who doesn't know anti-aliasing from his elbow) is harder to argue with than the enthusiast who just wants it to look shiny; the BOFH assumes that if it's got computers in it, he automatically knows better than the ponytailed NuMeeja 'professional', and so on through the list of tedious stereotypes.

Me, I know I'm only just beginning to learn just how much I don't know. But in the country of the blind, the one-eyed man will probably be asked to do all the web-browsing.

I think it's like something might be better expressed in French, others in German, but if you don't speak French but do speak German, then you'd rather here the things in the former category expressed in the German.

Indeed, and that's fair enough (we only speak the languages we know!) -- but the problem comes when you have to speak to people who only speak a language other than your own, and both sides are too proud to compromise on some sort of pidgin. And there aren't usually the resources to hire a simultaneous interpreter. :-/

Very true. There so ought be jobs for interpreters for that!

Absolutely! I tried to create a "Speaks-to-programmers" role for myself in my previous job, and the result was that I managed to manoeuvre myself into a blind alley between two promotion streams... My current job does have quite a lot of opportunities for that sort of translation, though -- it's one of the bits I enjoy about it. It's so satisfying when you can find the right analogy and you can practically see the light go on in people's faces.

It's the sort of thing I imagine you being really good at - and a rare skill at that. I think I'm better than most programmers but sometimes sink back into wanting to talk in the most concise language I can. It's a shame most companies don't appreciate how important it is. They don't tend to reward the people who help other people understand eachother or work together.

This reminds me a bit of another pet hate of mine. Programmers who think that you should work everything out for yourself rather than ask, when asking is often quicker and useful for other people. I'm perfectly capable of reverse-engineering a complicated piece of software, but I might have better things to do with my time :-) I often deliberately ask questions I sort of already know the answer to on the forums of the open-source software that I'm working on at the moment, because they're questions where the answers ought to be out there for people to find.

I get annoyed with people who think you should ask rather than working things out for yourself.

If you work things out for yourself you generally end up understand it and can get on with things in future, if you ask you end up with people asking endless streams of trivial questions wasting the time of everyone involved, including the person asking.

But surely it depends so much on the type of question, and who you're asking, and why!

I definitely agree that working things out can lead to greater knowledge. But when the questions are things like "Where is the documentation for X? I have already looked in the following sensible places...", half an hour of fruitless searching through outdated documents on the company X: drive isn't going to teach you anything except that the documentation isn't well-publicised/well-linked/well-presented.

I find it's generally a question of working out what I need to know and how I can best find it out, and -- if some stages of that finding-out involve asking questions of other people -- making it clear to the people I'm asking that I have already checked the obvious places and done the background learning required to make their answer useful. Targeted questions, that the people in the know can answer quickly and painlessly. And if the person answering the question can tell me how to find out the answer, in a way that I can learn from or generalise from, then so much the better.

Also, if you're getting your time wasted by "people asking endless streams of trivial questions", then I'd venture to suggest that you need to manage your time (or your conceptual in-tray) better. Ach, you know all this stuff: don't drop everything to reply to each email that comes in, have templated replies for dealing with the FAQs, switch the phone through to voicemail if you need to carve out some time when you won't be interrupted, etc., etc.

And if enough people are asking me the same 'obvious' questions over and over, then I find it's worth considering (not agonising over, just re-examining the question) whether either a) the answer isn't as obvious as I think it is, or b) it isn't clear who people should be asking or where they should be looking; and maybe I need to think about ways of pushing that knowledge out more proactively to the people who need it. If the one person who knows the answer can communicate it to all the people who need to know it, then less time overall is wasted than if either that person answers the same question n times, or if n people work it out the hard way for themselves.

Even in your documentation example, some fruitless searching through outdated documents is going to teach you a lot about where all the outdated documents are, and how to find things.

Targetted questions are worse in some ways - if I want to do X, and ask someone a very specific question they can quickly answer, tomorrow I'm going to want to do XY, which is incredibly similar to X. If I'd spent more time doing research I'd probably know the answer already, but if I just found out about X, I'm going to have to go back and ask another question.

Most of the time management advice doesn't apply to people who come and talk to you, which is the main method of communication I have with people asking questions.

And I think people waste their own time - I think an awful lot of people who ask others how to do things would ACHIEVE THEIR OWN GOALS FASTER if they "worked it out the hard way". I vary myself in how much I do research and how much I ask people how to do it, and I almost always seem to be more productive when I do more research.

some fruitless searching through outdated documents is going to teach you a lot about where all the outdated documents are

Yeeess. How much use is that, really, unless you're the person with ability/responsibility to update (or mandate the update of) the documentation?

and how to find things

But I already know how to find things! :-) Generally if I can't find it in half an hour's searching, I'd be willing to bet money that it either isn't there or I'm missing some key piece of information that I don't know enough about to know how to find it. Is it really better use of people's-time-in-general for me to spend a long time bashing my head against a bootstrapping problem with the searching, when somebody else could answer the question in two seconds? (NB, I don't tend to ask phone/face-to-face questions. I figure if I email somebody with a question, they can answer it in their own time.)

Most of the time management advice doesn't apply to people who come and talk to you, which is the main method of communication I have with people asking questions.

Hrm. Can you stick a "Do not disturb" sign on your door? Or tell people "I'm in the middle of something right now, if you still haven't found it in an hour's time give me a call and I'll get back to you?" ... If you've already thought about all this and you know there's no solution, how do you cope with the non-stop annoyance?

Agreed on the points about research, and people wasting their own time. But, well, your job is probably very different from mine, but here I have to deal with a lot of people who a) genuinely don't have time to go away and learn the things they're asking me (because it's not a big part of their job - even if they sometimes wish it was), or b) simply don't want to learn (and if I tell them "go away and learn" will only pester me more loudly and more insistently). I try to give people answers which point them in the direction of finding things out themselves, and like I said somewhere up there in the comments, it's so satisfying for me when I see the light go on as they realise "I get this! I could learn more about this! I would be able to do this bit of my job so much quicker if I got my head round this stuff!" If they want to learn, I'm happy to spend a bit more time guiding them, if I can; if they don't, I figure it's probably in my interests to answer them as quickly and painlessly as possible to get them out of the way.

If they come with the same "read the manual for me" questions time and time again, though, I find the following approach works quite well as a discouraging tactic:

Them: "How do I do X?"
Me: "Hmmm, let's see... that'd be in the manual... [open document]... and probably in the section of the manual labelled 'X' ... [read slowly, scrolling back and forth a bit so they can't quite pick the bit they want out themself over my shoulder] ... Ah yes, here we are, 'How do I do X?'. So... yeah... [read a bit more, reading out useless phrases occasionally] ... yeah, it looks like what you do is ... [then finally read the relevant bit out]."

Make it slow and painful, and eventually they work out that they can read the docs faster, or Just Fucking Google It (http://justfuckinggoogleit.com/).

Can you stick a "Do not disturb" sign on your door?

I've heard of these "doors", but I've only encountered one workplace in my life that didn't use open plan offices (and I didn't take the job because it sucked otherwise)

I use headphones as a virtual door -- let the guy ask the question while I continue to type distractedly (for extra points, type accurately and fast while looking at them -- it freaks people out), then take the headphones out, and say "Sorry, can you repeat that, please?"

(I'm usually a helpful kind of person. But I have off-days. :-> )

I use that technique too if people ask me questions that are easy to look up. Much better to show them indirectly what they should be doing than tell them to RTFM.

Yep, I think we're talking about different sorts of questions. I wouldn't expect to teach a fellow programmer a new language that I knew for instance because that's not my job. But I would help them if they got stuck. I'm talking two minute answers here not one hour ones.

You should tell people that you're too busy if that's the case :-)

But as Janet says it depends whether I'll actually genuinely learn anything useful from working it out for myself. Some questions I will, others I won't. I've done enough working things out for myself in the past that usually I won't learn anything.

To be honest, a lot of questions I ask are because code isn't very well written or user interfaces are stupid and I think if people write bad code or user interfaces and want other people to use what they've done, they should expect to answer questions about how they work :-)

There's somehow a semi-pervasive culture among programmers that you have to work out everything yourself - it's almost about proving that you're clever enough to be able to do so. I really hate that culture - it's so competitive rather than cooperative. It's like people who assume you are stupid because you don't know certain things. I suppose I get this a bit having gone into programming from a maths background. There are weird gaps in what I know about, but it's not because I'm incapable of understanding what's in those gaps.

It depends.

Exactly. I've been asked to take the same piece of base documentation and both expend it out into excruciating detail for people who can't be bothered reading the code and summarise it for a non-technical audience. Both are "explanations" of the original. (Hmm. This might suggest that the reason no-one seems to read my documentation is that I'm pitching it between two acceptable levels.)

People don't read documentation because they are lazy, no matter how appropriately it's pitched...

Also, sometimes, because they don't know where to find the documentation. Admittedly that can sometimes be overcome by a concerted effort of anti-laziness, but if the documentation's hidden in ~~a disused lavatory~~ the X: drive, or the "Misc" section of your wiki, then it's not much use to man or leopard.

That's certainly true; indeed just the other day I responded to someone's suggestion that we write a generatekey man page by pointing them at Devel.GenerateKey2ManPage. Without being able to peer into the person's head I couldn't say for sure but I suspect the problem was more that it hadn't occurred to them that the document existed than that they hadn't tried to look for it. But long experience shows that very often people come to the author before trying to read the docs even when they have good reason to believe they exist...

There are two ways forward.

Have two documents.
Have an executive summary, followed by a more thorough explanation.

One of the difficulties with some of the work I do is that the same manual goes to customers who can, at one end, be high-tech engineers who've been working with the relevant technology all their life. All they need to know is how our gadgets map to the previous generation of technology and they're away. At the other end, we can, quite literally, be giving the same product to a husband and wife company who work with it in their spare time. (I've heard tales of one piece of hardware being in a room with a tablecloth on it...)

This leads to a number of problems, which become more obvious when we have to add new bits and pieces to any given section of a document. Some people don't want, or care about, all the warnings we need to give to another group of customers, because it's bloody obvious to them. The best effort we can muster here is to have sub-sections that can be easily skipped over when the techies realise it's just explaining the differences between two perfectly obvious components.

Business executives are expected to know how technical buzzwords interrelate? I think I'd class any high-level executive who reliably knew things like that among the top 10% for knowledgeability. (Which is not to say it wouldn't be a jolly good thing if the rest did as well.)

I think they are (or at least should be) expected to know what fields the buzzwords pertain to, so that they a) don't make a tit of themselves in front of people who do know what they're talking about, and b) know where to delegate the details.

[FX: hollow laughter from all information professionals]

This reminds me of the time when I had quite a length conversation about XML with my father (whose director of an IT consultancy company and isn't technical any longer), followed by him asking me what an iPod was.

When I say "inter-relate", I mean in the same way that Arthur Weasley understands how muggle artefacts inter-relate.

*laughs*

If I could walk that WAI I wouldn't need the guidelines

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject

no subject