Recently I read a review (on Tom Johnson’s excellent blog about technical writing) of a short book called “Modern Technical Writing”, by Andrew Etter. It’s available on Amazon as a download for Kindle for £2.69 / $3.56 (or free if you have Amazon Kindle Unlimited).
Based on Tom’s review I downloaded the book, and I’m glad I did – I thoroughly recommend it. It’s refreshingly short – more of a pamphlet or extended essay than a typical text book, and all the better for that (I read it in full during one 45 minute train journey home from work).
I guess I like the book partly because it says a lot of things about technical writing that I’ve thought for many years, in particular:
- know your audience
- understand the topic
- use simple text markup, not heavyweight WYSIWYG, and don’t bother with complex DITA type projects that will never work either
- put the source in source control (Etter is a fan of Git)
- build static websites
- wikis are rubbish
Now, the first two are, you would think at least, uncontroversial, but I loved Etter’s quick romp through this area, especially his description of technical writers who obsess about the Chicago Manual of Style and so on:
“…their impression of the job was that technical writers interviewed engineers, took copious notes, wrote drafts in Adobe Framemaker, and waited several hours for some arcane process to build these drafts into printable books… None of them seemed to give any thought to their reader’s needs, preferring their own criteria for what constituted a job well done. They used phrases like ‘clear, concise, correct and complete’ and avoided words like ‘searchable’, ‘scannable’, ‘attractive’, and most egregiously, ‘useful’. … they were products of a dysfunctional profession, …judged far too long on meaningless criteria by managers [who] would rather produce minimal value from a lot of work than tremendous value from far less work.”
Ouch. I had flash backs to an unhappy time working for a large company that did everything in Microsoft Word and used technical writers merely to proofread and copy-edit those Word docs (in arbitrary time scales) before they were submitted to “some arcane process” (which took longer than the time allotted to actually write the stuff) that destroyed all the formatting that line managers obsessed about, and then uploaded the content in mangled html form to a website.
I’ve never liked WYSYWIG, hate MS Word with a passion for anything other than writing a letter, and could never see what on earth Framemaker fans were so keen on. Instead, I used LaTeX in the 90s (and into the 00s), and kept the source files (plain text with readable markup) in version control, using whatever version control tools the software engineers around me were using (so initially RCS, then Perforce or Subversion). I was deemed to be a bit odd. I used other things of course when duty called, but my favourite Help Authoring Tool was Help and Manual, partly because it is more lightweight than Flare, and partly because its source is well formed XML that you can edit safely when you need to (and you can play around with the CSS that drives the styles too).
But then I noticed a few years ago something happening in discussions I saw in places like techwr-l. Suddenly everyone was talking about how to get their Framemaker files into Subversion. Then, lots of people were acting all interested in XML and DITA – which is plain text markup. XML is really really bad of course, and not meant for humans, but still.
And now, just as programmers have tended to move from XML to JSON for data purposes, it seems technical writers are coming round to lightweight, readable, simple markup like markdown or reStructuredText. And putting the stuff in Git. Because it’s software, just like the rest of the code, and there’s no excuse to use different tools or re-invent wheels.
I still think there’s scope for some form of markup that’s as easy to work with as markdown, but provides semantic tagging, while still being simple syntactically. But until that comes along, I’m with Etter – my favoured approach for getting stuff done would be markdown or rst, stored in git or svn, and built into a static website using one of the many open source tools that do that. The only problem really is there are so many different tools – Etter’s book gives a quick overview of a few.
So, in short – if you’re a technical writer, it’s well worth reading this book. Even if you don’t agree with all of it, there’s probably food for thought, and you won’t have invested too much time or cash.
Or, wait for me to publish my own personal manifesto for technical writing which I’ve had at the back of my head for a few years now – but I may not get round that that, as I’m too busy playing around with static site generators. And that Etter bloke stole my thunder, anyway.
PS. Tom Johnson’s review (much better than mine, as is his blog) is here:
http://idratherbewriting.com/2016/07/26/modern-technical-writing-review/
Hangingwater's Blog 