I'm a hardcore tech writer. I don't use RoboHelp or whatever else "authoring tool" bastard consultants try to foist on unsuspecting vendors. I use Word, and I use Paintbrush.
So the other day I come up to a developer and ask him to explain a complicated thing that I am supposed to document. He opens his copy of OpenOffice and starts using the 'Draw' component to make circles, squares, cylinders and arrows. All the while I'm sitting there thinking how much prettier - and easier - Visio is.
Eventually he's done, and I ask him to email me the drawing so I can redo it in Visio and put it in the doc. I come back to my desk, find the email and open the attachment.
A copy of OpenOffice 2.0 that I'd forgot I had boots up. Damn, I hoped Pbrush would catch this one.
Guess what? OO 2.0 can't handle .odg files properly. The diagram is as mangled as any Word doc that some zealot from the development wing saved in OpenOffice and emailed back to me. I hate it when that happens.
This time around I got the guy to email me JPEGs. But this is a symptom of a great problem for open source.
Recently I've helped set up a wiki. After trying out several different ones, with varying degrees of discomfort, the powers-that-be settled on a specific one. My job was to document it - because the creators never bothered to, and the point of a wiki as opposed to an FTP server to dump all the Word files on, or better yet, as opposed to bothering a live human being until they go and get what you need, is to make it easy for people to use the damn thing. This above all else means that you remove as many reasonable barriers as you can. (Technical writers really do rule the world, in our own unassuming way.)
So I wrote a quick guide on how to make a new wiki page and how to use the built-in editor. Then I tried to put it under the FAQ section.
Then I asked the person in charge of the wiki how to do it.
Then I asked the programmer in charge of the technical side how to do it.
It appears that the way you add pages to the navigation area in this particular wiki is, you find a very specific document type, open it in the built-in editor, then play around with links to internal page numbers on a hierarchical tree until you end up with something approximating that which you intended to do. Very simple.
The problem with open source, in particular the enthusiast-driven minor projects done by one, or maybe three, developers in their spare time is - it doesn't conform to the user model.
Enthusiast-driven development is great for some things. One example I can think of would be some sort of highly specialized programming tool. Another would be a game. In both cases, the authors and the audience are the same; the user model can be disregarded, because things will simply fall into place. But when the open source ideology is applied to something of potential commercial value, or even something that regular people will want to use, you get a communication breakdown: the author doesn't understand what the user is trying to do, and the user doesn't understand how the author expects them to do it.
This is why Firefox is ultimately irrelevant and why the absolute majority of people who own a computer still struggle with Windows Media Player and codec packs, instead of downloading VLC which plays absolutely everything out of the box. In VLC, when you want to play a movie, you have the option of 'Quick Open File', 'Open File', 'Open Disc', 'Open Network Stream', 'Open Capture Device' or 'Wizard'. Seriously. What the fuck.
There is a saying: A camel is a horse designed by committee. I heard it first as applied to software development, and haven't stopped marveling at how appropriate it is.
The vast intelligence of Mary Ann Evans
3 months ago