cat slave diary

Looking for inspiration

Written by

Andrew van der Stock

in

Like many technical writers, I am constantly looking for ways to improve my writing skills. I don’t think there will ever be a time when I think “Okay, that’s good enough” and stop criticizing my own work.

I am constantly in awe of other authors, particularly those that have published great works. I seek out author interviews on scholarly websites, and places like Galley Cat, in an effort to glean small insights into the life of an author.

I started out by reading author interviews for any morsels on how they organized their day and their writing space. This accelerated once I started working from home. This is a futile project – each author, if they mention it at all, has a completely different day structure and writing space than the author before. Some write early in the morning (impractical for me), some write late in the night (I’d love to, but I have a 2.5 year old who says “close eyes” and means it); some write in glorious writing palaces redolent in over stuffed furniture and old books others write in long hand at the local coffee shop or library. No two are the same. Sigh.

The one common theme is that they write every day. Iain Banks, one of my favorite authors, writes for only part of the year and takes the rest off, but still manages a punishing schedule and daily word count to pump out beautiful works of art.

Another common theme is supportive family and friends. I can attest to that – my cats led a lonely life whilst I was tapping away at the OWASP Guide 2.0 for several months. I don’t think I could ever do that again – not least for family reasons.

Technical writing for web application security is far different from any form of fiction. It’s different from most non-fiction – and it’s dramatically different from sports writing. We’re expected to dumb down (“communicate”) with our peers in a way that nearly no other technical field would allow. In my field, respect is paid to those who can communicate highly technical, very advanced concepts in a way that could be understood if they were on the back of a “Fantale” wrapper.

I am not disparaging my field, for I love it, but I do object that our terms of art – our short hand – is so easily sacrificed. I need to learn how to write dumber, become one with my inner dumb writer, and make sense even when it makes no sense to write for the average tabloid reader. I think we underestimate our reader’s intelligence and insult them terribly every time we pump out a report in basic English (that is – using only the 500 most common words).

Viva la revolucione! Whoops, that wasn’t basic English. My bad. As for more author interviews – it’s like reading a good autobiography – hard to put down. I think I will continue to seek out author interviews, even though I think they will in the end not shape my writing style nor my work space to any great degree.

Comments

One response to “Looking for inspiration”

  1. Big Red Avatar
    Big Red

    There are so many aspects of this entry I disagree with, it may be faster to articulate the areas of concurrence! I am not saying you are wrong — merely a divergence of view.

    Let me examine your “Fantale wrapper” paragraph. It strikes me that you are possibly writing one document for two audiences: already a bad idea, and a document doomed for failure.

    A trick/tip which has served me well in my report writing over the years has been establishing at the outset:

    1. What am I trying to say with this document?
    2. What is the intended audience for this document?

    I have found, invariably, that once I start to write a document which targets more than one group, I am better off splitting the document into two. Yes, it means a lot of duplicated copy. However, this is a small price to pay to ensure that you have an appropriately targeted document.

    If I wrote a Fantale piece for the consumption of my ITSM colleagues, I would be (constructively) crucified for it, and rightly so.

    I am on my last day of an 8 week engagement today, and I have written a report of observations, findings, the work I have done, and recommendations. It comes in at 60 pages, and it is to do with the coaching and improvement of a team of highly skilled Major Incident Managers.

    I have determined who the report is for (line executives at this client), and what I am trying to say (here’s what you’ve got for your money (and, implicitly, invite me back 🙂 ))

    I asked two of my younger colleagues to review it, neither of them with any significant ITSM experience (admittedly, neither with executive experience either!) Both of them thoroughly enjoyed reading it (“surprisingly good reading” said one), said that it clearly stated the problem space, the approach taken, the work done, and quantifiable improvements.

    I also asked one of my more experienced colleagues to review it, but neglected to tell him the intended audience. It came back with annotations galore — useful if it were to be a paper at itSMF later this year, but not if I am aiming it at a different audience.

    I also have to write up a report for my colleagues. The intent here is that when any of us return from an engagement, we write it up as a formal presentation, and give a lunch time presentation about what we’ve learned. (Done well, this is surprisingly effective: I’ll be able to distill 90% of 8 weeks’ worth of learning into an hour. I’ve sat through three of these given by colleagues already, and could well have been involved in the engagements, so useful were they.) Now for this document, I *will* take on board my more senior colleague’s recommendations. Different audience, different purpose.

    Some further gratuitous good writing advice:

    1. Use short sentences
    2. Use numbered lists
    3. One idea per paragraph
    4. Ensure that you can answer the two questions outlined above.

    If you want any more, bribe me with a bottle of red 🙂

Leave a Reply

Your email address will not be published. Required fields are marked *

More posts