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.

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.

As I normally do, I reviewed the list of actions I jotted down before I left and looked over some of the last bits of work I completed, just to make sure I had been focussing on work and not been too distracted in the run up to the holiday.

One thing that leapt out at me was how I still, all these years later, struggle with consistency. It isn’t something that comes naturally to me and, truth be told, I’ve still to find a working system that helps.

It’s all well and good relying on Style Guides and whatnot but until I can make myself write consistently it’s always going to be something I need to consider. It’s not a huge problem, I am talking about a very fine level of detail here, but it does irk.

Aside from that, the usual hurtle towards the finishing line is well under way and by the end of the month we will see where things stand and what things we need to tackle next. All part and parcel of software development and, even though it’s a high stress time, I did kinda miss the buzz whilst I was away.

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.

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.