Archive of Writing posts


The single customer view

I just found this sitting in my drafts folder. The company name has changed (we are now Kana Software) but the premise is the same. Interestingly, the parallels between our thoughts on customer service and the thoughts in tech comms of better integration within a support system (providing information as part of call deflection) are striking. I’m going to try and pull these together in a future post.

I was asked to write an article for Credit Control Journal on behalf of the company I work for, and for the sake of historical archiving (and so I know I have it somewhere), here is that article.

On pedantry

I start this blog post with an admission and an apology.

Admission: I am a manager, I don’t spend a lot (any) of my time writing technical content these days.

Apology: One of my weakest areas is in the intricacies and ‘correctness’ of grammar. *

That said, there is one thing that continues to frustrate me about the technical communications profession, the constant ‘deep dive’ into every single aspect of one sentence, one clause. Dear grammar pedants, please stop!

Don’t get me wrong, I know that good written information is a keystone of our profession and I’m all for discussions to make sure things are being approached correctly and debated thoroughly, where appropriate.

Please note the last two words of the last sentence, “where appropriate”.

Maybe it’s just me, but as each of us write for a specific audience, likely to a specific style guide, such discussions become academic almost from the get go. What really irks is when discussions on other aspects of our profession are diverted towards this area. For example, “Content Strategy is important! … Yes, but ultimately the paragraph that someone reads once they have found it needs to be written in the active voice and never ever punctuate that bulleted list with commas… ”

And so on.

I’ve seen it so many times I’ve started using it as a guide. When any online discussion that isn’t explicitly about grammar and punctuation, whether forum or mailing list, reaches the point that someone reaches for the grammar gun, I stop reading, I disengage.

A few years ago, when the UA conference reached Edinburgh in 2008, one of the sessions was by Professor Geoffrey K. Pullum, a noted linguist. It was the closing session and I approached it with some dread, a presentation on language would surely be all about the use of transitive verbs and the perils of infinitives which are split. How wrong I was, leaving the room at the end with a simple, repeated message.

Write as you speak. Write as if you were explaining something to someone sitting next to you, put aside the rules of grammar if needs be!

I blame my current stance, my dislike of long academic discussions on someone who, I’m sure, has initiated and partaken of many such discussions himself.

Forgive me if I’ve offend anyone, I’m not saying that correct grammar is a bad thing, far from it, I just think that in the current day and age we, as a profession, need to raise our view and focus on bigger things. The language will take care of itself, one way or another, let it go!

We should be looking to influence, to sell, to push ourselves to the forefront of our companies as the experts we are in that valuable (and its stock continues to rise) commodity, information.


* Yes, there are deliberate mistakes in this post. Feel free to point them out in the comments.

The Presumption of Common Sense

If there is one phrase which should set off alarms in the mind of a technical writer it’s when a developer says “Ohhh but they wouldn’t use it like that…”.

Because, as I’m sure you all know, they will.

I am currently working with a few people to try and pull together a solid set of product usage recommendations. We provide an SDK and a feature rich application built using our own technology, and that application is extended and configured for specific uses. There are plenty of hook points in there and, for the most part, usage follows accepted patterns. However there is always the time when a certain component is bent and twisted and used in a way we hadn’t expected and it’s these instances that we are trying to understand and capture.

We get a view of them by exploring edge cases when testing, but it occurred to me that there is still one thing that can catch us out. Our old nemesis, ‘presumption’ (which is usually coupled with it’s friend ‘common sense’).

So now I’m on red alert for any statements which are based on presumption. Sometimes they are right, but it’s the times when they are wrong that we need to explore them, capture them and help our customers by giving them some frame of acceptable usage. It’s not an exact science, but even just pausing to have those short conversations seems to be helping.

I is a Editor

(note to self: stop with the jokey bad grammar, peoples might think you cant be writing good)

I’ll say this quietly because I’m a little apprehensive but, for the next few months, it looks like we will have extra resource in our team. Basically we are ahead of the curve when it comes to recruiting so, until the rest of the R&D team catches up, we are one technical writer up!

Which means that we are taking the opportunity to both get ahead with some things, and catch up on others, and one of the things we’ve never tried here is to have a formal editoral review of the content. Peer review is one thing and whilst the technical content we produce is excellent, the differing writing styles and approaches each writer has does show through.

I’ll be the first to admit that I’m not all that bothered by this, simple business reasoning dictated that we concentrate on improving the accuracy and timeliness of the documentation and so, now we have done that, we can turn our attentions to other areas including findability and clarity.

The latter finds me taking on the role of Editor (I want to write Editor-in-chief just to conjure up images of a smoke filled newspaper office in the 50s), casting an eye over all of the content we produce and using our lightweight Writing Style Guide to prod and cajole the content towards something that, without being too restrictive, has a level of consistency for the reader.

As we haven’t had anyone performing that role before, it’s taking a bit of adjustment and the jokes about the “red pen” are already flying. Thankfully I work with smart people and it’s not taken long to see the results come to fruition.

What we need to figure out is how we change this model in the future so that we can all consistently edit each other’s work, lest I become a bottleneck in this process.

What do you write?

I’m currently pushing a business case to allow me to hire a new member for our team. The premise is that, particularly with our product set, there will always be areas of technical content that need writing but that with an additional member we can start to create other forms of content.

Which begs the question, what other forms of content can we create?

One thing I would like to get my team more involved with, both to give them a wider view of the product and to help the rest of the R&D team better understand why we build what we build, is in the creation of our Business Requirement Documents (BRDs). These documents drive the product features, setting out the requirements for the new features that we want to add for the next release cycle.

Early on in my career I remember reading (somewhere) that the technical writing team are user adovocates and that we are “the interface to the interface”. With that in mind, we need to understand both why a feature is in the product and how we expect it to be used (or at the very least, how we would like people to use it). By getting involved earlier in the product lifecycle, helping to understand and articulate the business requirements at the start of a release, we can be better placed to act in the best interests of the customer.

Being part of the team that collates and creates the BRDs will place us bang in the middle at the start of a stream of work and, by nature, we are also there at the very end, checking our documentation as the final stages of the release tweak and refine the functionality. My hope is that this end to end view of the product will help both the technical writers, and the development teams in which they are embedded.

Are you involved with early development documentation? If so I’d love to hear your thoughts on this.

How much does “good” cost?

Recently, Ben Minson stated that “Good Enough” Really Isn’t. It’s an interesting post, and I wanted to expand on the comment I left on his blog.

Ben suggests that:

If I find myself thinking “It’s good enough” on a regular basis, I—and my users—am probably not getting all that’s possible out of my work

Before I go any further, perhaps we need to clarify what “good enough” means?

My fear is that many people take “good enough” to mean, “yeah, I’m done with that and it’ll have to be good enough”. If that is the case then yes, you are selling your users, and yourself, short. However there is a perfectly valid scenario around which the phrase “good enough” could, and should, be used.

There is a classic business situation that drives the use of the phrase, it is one with which we are all familiar and which will never ever change, and that is the age old issue of high quality deliverables versus cost of delivery. It is sometimes stated in terms of Return On Investment but the bottom line is that, at a certain point, regardless of your deliverable, there comes a point where the amount you are spending on something has reached the maximum value you can expect to gain.

Finding the balance of that will, without doubt, mean that you disappoint some users. The Pareto principle is typically offered as a rule of thumb at this point (wrongly as it happens) with the presumption that “good enough” means meeting the needs of 80% of your audience, knowing that 20% will not be as well served. The reality probably that 20% of your documentation will be used but that’s for another blog post.

Ultimately whilst we would all love to provide better information, both in quantity and quality, projects have deadlines, budgets have limits and it is there we find the true definition of “good enough”. It’s up to us, as professionals, to make the most of these situations so that when we say something is “good enough”, we mean exactly that.

Elements of Style

To my American colleagues, who recently celebrated the 50th anniversary of their much used Strunk & White style guide, may I gently prod you in the direction of this article by Geoffrey Pullum of the Language Log.

I’ve seen Professor Pullum speak, hilariously, about english grammar and whilst I’m certain that he could find many issues with the content I publish here, I’m certain he would never be nasty or vindictive in his comments. However, in this post, in which he responds to some of the people who have commented about his article, he proves that he has the wit and style to handle such things. Both are well worth a read, even if you don’t agree with his point of view.