Wiki lacks?

Quote:

The only example of a wiki that worked is Wikipedia, and that’s not really a wiki in the true sense, because it is heavily edited by such a small number of people.

That’s Russell Keith-Magee, speaking on a podcast (so I may not have quoted him exactly). He was talking particularly in the context of software documentation, but I think, on consideration, that he’s right.

Don’t get me wrong, I love wikis, use them quite a bit, and shook Ward Cunningham‘s hand very enthusiastically when I met him a few years ago. But on the other hand, if one has been spoiled by the quality of documentation in projects such as Django, it makes one’s heart sink when exploring a new piece of software to discover that the documentation is ‘only a wiki’.

Wikis are great for their free-form, collaborative nature – remember, they came into existence long before Google docs and SubEthaEdit – but they also suffer from a few key problems:

  • They can make you feel as if you’ve done something about documentation, so you don’t do the real work. “The crowd will fix it later”.
  • The fact that you don’t need to think about the structure early on means they often need to be reorganised – making it hard for others to find things even if they’ve visited before, and harder to link to things reliably.
  • It’s notoriously difficult to move content from a wiki into anything else, including another wiki package.
  • It can be hard, with a software package, to know to which version the documentation applies.
  • As with mind-maps, the free-form nature closely represents the mental model of the author. It’s good for personal notes and reference (Voodoopad is lovely, for example), but the difference between structured documentation and a wiki is the difference between a talk/lecture and a rambling conversation. The letter may be more fun, but does it achieve as much in the same amount of time?

None of this means, of course, that you can’t write good documentation with a wiki. It’s just very rarely done, and when it is done, it probably takes a lot of effort. Wikis are the whiteboard doodle, the back-of-the-envelope scribble: they can be useful within a small internal group of collaborators, but they’re not the thing you want to present to the world.

Actually, I think one of the best ways of doing documentation was the approach adopted by the PHP developers many, many years ago – you write proper docs but allow comments at the bottom of each page. Here’s an example. They did this long before the concept of comments-at-the-bottom-of-the-page was well established.

What do you think?

Morning, Constable

It was a moist early morning… but the light felt almost like a Constable painting.

20130825-07525011

Tilly enjoyed it, and showed some reluctance to get into the hay wain and head home…

A Good Name

I like this one – somehow I feel there ought to be an interesting story behind this street in Orwell…

Hurdleditch Road

Quentin’s Law of Photography

The second-best camera is the one you have with you.
The best is the one you have in your hand.

A taste of their own medicine…

This was a lovely story, featured on the BBC this morning. A Russian man, before signing a contract with his bank, altered the small print, signed it, and sent it back to them. They signed it, not noticing that they were then obliged to provide interest-free loans, no management charges, and would pay a substantial penalty if they wished to get out of the contract…

Fabulous idea.

I’ve done nothing as cunning as that, but often when I call some institution and get an automated voice saying “This call may be recorded…”, I say “Thank you!”, and click the record button…

That’ll show ’em.

High upreared and abutting fronts

Materials Science, Cambridge

The new Materials Science and Metallurgy building, Cambridge.

Sarah & Hubertus

About three weeks ago, my very good friends Sarah and Hubertus got married in Queens’ College here in Cambridge. They were good enough, and foolhardy enough, to ask me to take the photos.

2013_07_21-14_46_36

It was a wonderful occasion – great people, lovely weather, delicious food, and a really excellent ceilidh band in the evening.

2013_07_21-16_44_39-Edit

Being ‘the photographer’ was a great learning experience for me, and gave me a huge respect for the professionals who do this on a regular basis.

In particular, at this (otherwise wonderful) venue, every single room had challenges from a lighting point of view. One was very dark, one had a low white ceiling, and one was lined with glass-fronted bookcases, which made it a real challenge to position the flashguns! But things mostly worked out in the end.

2013_07_21-16_08_24

Even the outdoor shots had to be carefully managed so people weren’t squinting into the bright sunshine, and despite visiting beforehand and working out where the sun would be at about the time the ceremony was finished, I didn’t quite get it right. The bride and groom may hope for glorious sunshine on their wedding day, but, trust me, the photographer doesn’t!

Still, everyone was very tolerant of the inexpert photographer, and, above all, we all came away with happy memories of a very cheery occasion.

2013_07_21-20_53_53

More photos from the wedding can be found here.

Understanding your DSLR

I always enjoy Jeff Cable’s photography tutorials. Here’s a good talk to recommend if you know somebody who has just got a DSLR, or is wondering about getting one. What kind of things can you do with it, and what do you need to know about it, if you’re used to a fully-automatic point-and-shoot?

Remember that these days you may need to click the ‘YouTube’ logo and watch it there if you want to do so in full-screen mode.

When is a photocopy not a photocopy?

One of the challenges, when storing or transmitting the image of a scanned multi-page document, is that it takes an awful lot of space. Unless, of course, you compress the data. But how should you do this?

The kind of lossy compression used by the JPEG and MPEG standards is great for photos and movie frames, but not much good for text – it makes the edges blurry. And the hard-edged, often lossless, compression used by things like PNG and GIF is great for text but will do nasty things to any embedded photos or background textures. So how do you handle, say, a typical magazine page, with crisp text, embedded photos, graduated background colours?

In the late 90s, my friend Yann LeCun and others created the DjVu format, which cunningly works out how to split a document up and compress each bit using the most appropriate system, then reassemble them for viewing later. It was particularly good for things like digitising historical manuscripts – it would separate the script from the parchment, deal with them separately and still produce a realistic-looking copy afterwards, but take a fraction of the amount of data that most other schemes would have used; especially important in those pre-broadband days. The same concepts are now in the JBIG2 standard, which is included in PDF and embedded in many devices, including Xerox copiers.

Another way to save space and time is that, once you’ve separated the text and other symbols from the background, it’s fairly easy to see if any symbols are re-used. So you don’t have to store the image of every ‘e’ in the document – you can store a representative sample of each size, font etc and simply insert an appropriate one wherever it is used in the original. All very cunning.

Assuming you get it right.

But this story on the BBC describes how some Xerox photocopiers may not have been getting it right, occasionally substituting incorrect digits in their copies. This can be something of a problem if you are, say, an accountant, or an architect. It’s not clear from this article whether this has ever caused anybody serious problems yet, or just been noticed in the lab, but you can imagine the potential lawsuits…

It’s a potential danger of any technology that reassembles a perfect-looking output, when in fact some data may have been lost since the input. You could save a lot of mobile-phone bandwidth if you noticed that someone had just used the same word that they used a few minutes ago, for example…

Xerox fought hard to preserve their trademark by not allowing it to become a generic verb meaning ‘to photocopy’. But I guess they’d like it less if it came to mean something else.

“Ah, hello, is that my tax accountant? I was wondering if you could…. ahem… Xerox this year’s figures for me?…”

Thanks to Mike Flynn for the link.

Circles of logic

I cycle past this sign regularly:

I think this indicates that all of Cambridge is now part of the Cavendish Lab. I know they’ve been expanding a lot recently, but I didn’t realise they’d got that far.

On the other hand, I may be confused. It’s difficult to keep a clear head when you’re cycling backwards like that.

© Copyright Quentin Stafford-Fraser