The lost art of description

[simont]

I was just walking through a shopping centre, and some random girl walking in the opposite direction handed me a flyer as she passed. I looked at the flyer, but it wasn't entirely obvious what it was advertising. The large print just says ‘TwentyTwo’, and ‘Free admission to any of these events with this flyer’, and ‘join us over the festive season’. After reading the smaller print, which says things like ‘over 18s’ and ‘10pm till 3am’ and describes a dress code, I've concluded that it's a nightclub of some sort, but (a) I'm still none the wiser about what kind of nightclub (what music? what sort of people? is there any particular reason I might want to go to it?), and (b) it seems barking mad that I should have had to read as far as the small print to even get that far!

Now I think about it, this seems symptomatic of a more widespread tendency I've been noticing here and there for a while, which is that people increasingly seem unwilling to spend the effort to tell other people what things are.

Another good case of this: two months ago, somebody sent me a link to some website's terms-and-conditions page with a comment along the lines of ‘Wow, that's the biggest T&C page I've ever seen’ (which it is!). Naturally I was curious to know what website was so important and unusual and difficult that it needed such elaborate terms and conditions; so I followed a link to the front page of the site, and it didn't tell me. It has links on the front page to web forums, user registration, chat, and a FAQ, and it has site news about downtime and server upgrades, but apart from one or two hints that it might do something related to BitTorrent, nowhere is there a clear description of what the site actually is, or why somebody might want to register for an account on it. Even the FAQ is unhelpful on this score, diving straight into tiny little details without any kind of introductory ‘yes, but what is it?’ section at the front.

Computer industry marketing is another area in which this sort of thing is widespread. Occasionally somebody will mention a computer-related term to me which has its own website, and I'll go and read the website and still have just as little idea what the wretched thing is. Increasingly I'm finding Wikipedia fills this niche for me: it told me, for example, what U3 was rather better than www.u3.com did. (Though it doesn't always win on this count: I still haven't got a clear idea of what UML is, because even Wikipedia just seems to define it in terms of other buzzwords. I know it involves diagrams in some way, but I've never quite worked out what you do with the diagrams once you've got them and whether there's anything else to it except diagrams.)

Finally, you also get a lot of this sort of thing in blogs and discussion forums, where people will post a URL without any explanation of what it is or why you might want to visit it. If it's a web forum, one might argue that it only takes a couple of seconds to find out for yourself, but even so, the Usenet effort economy still applies: thirty seconds of one writer's time works out to less overall than two seconds each of twenty readers', and if lots of people post bare URLs then I don't have two seconds to spare for all of them so I'd like some means of deciding which ones are worth looking at in advance. Particularly bad is if the link goes via one of those URL-squashing services which removes any chance of you being able to look at the URL itself in advance and know whether it's a news site or a comedy site or what. Also particularly bad is if the thing being linked to is a ten-minute YouTube (or equivalent) video which you have to watch all the way through before you have any idea whether the person had linked to it because it was bad, or good, or funny, or sad, or just tedious, or what.

I'm not asking for huge elaborate descriptions of things which remove any need for me to go and read the actual thing. I just think that writing, say, ten words or so to give people the first idea of what something is shouldn't be that difficult for anybody, and yet it seems to be taking the first steps toward becoming a lost art.

Comments

[simont]

And I'm afraid you're still not telling me what UML is, only what it's for, which is subtly different. You're keen to tell me what it's intended to make better about my life, but you haven't really described what it is, and how it achieves what it aims to achieve. There can be a world of difference between things which have the same aim: for example, a vacuum cleaner, a carpet shampoo and a mop all share the aim of making floors cleaner, but they are totally different things which go about the job in different ways.

[geekette8.livejournal.com]

Oh, sorry, I thought that "what is it for" was actually what you wanted to know, rather than "what is it".

How about this, then:

It's a modelling language that defines syntaxes for different types of diagrams relating to system design (eg FSMs, message sequence charts, user interactions, object hierarchies) and a framework for fitting them together to provide a coherent (hopefully :-)) system architecture that can (again, hopefully :-)) be understood by techies and non-techies alike.

It has a string of other claims associated with it, including things like self-documenting systems (if you've written the UML model and developed the code from it, there's no need for further documentation) and making development faster and more reliable with less need for skilled programmers (if your system architect has designed the model, she doesn't need to know the intricacies of C or C++ or Java syntax to implement it - just press a button and bing, there it is).

As I tried to imply above, I'm not really sure that it does actually achieve any of these otherwise laudable aims.

[simont]

OK. So, notably:

• the types of diagram and their visual syntaxes and symbol sets actually are pretty much the whole of UML, and there's no textual component that goes with them
• the sole purpose of a UML model is to communicate information about systems' structure between people (i.e. it isn't a "modelling" language in the sense of "simulation", and doesn't give you ways to predict how the system will behave other than thinking very hard about it in the conventional non-UML-based way).

Are those accurate? Because neither one was something I was entirely sure about before this conversation, so I'm learning new facts here which I suspect most UML people would have seen as so basic that they'd have forgotten to tell them to me.

[geekette8.livejournal.com]

First bullet: yes, although you can apply labels to states, transitions, messages etc. But they are attributes of that diagram component rather than being useful in and of themselves.

Second bullet: yes, although there are some tools that can help you iron out some of the issues (like warning you that you've got a use case that isn't covered by any of your state transitions, or a message sequence that can never get triggered).

There is also a "real time extension" for UML that claims to allow you to add clocks and timers and whatnot to your diagrams, and I bet that would also then allow you to simulate stuff happening (again, with the right tools). However, I have never met anybody who had a good word to say about that, other than the people who sell the tools :-)

I suspect some UML proponents would make far greater claims for it than I am making here - my knowledge is based on a years-ago training course which I have used very infrequently since.

[ewx.livejournal.com]

UML is for describing system architecture and behaviour, in a way that allows non-technical people to understand how it all works

eg FSMs, message sequence charts, user interactions, object hierarchies

I'm having a hard time imagining these two things as remotely compatible. (Also the first reminds me of COBOL.)