Why technical reviews fail

It’s a common topic, an oft repeated complaint, and one which has already had many many lines of advice written, and countless suggestions offered. So here’s a new slant. The reason most technical reviews fail is because of the writer, not the reviewer. It’s not because the reviewers couldn’t find the time, it’s not because the reviewers didn’t understand the need or reasoning behind the review, it’s not because they didn’t know what to do, and it is most certainly not because they don’t value your contribution to the product and your part in the development process. Because, if any of the above reasons are true, it’s YOUR fault, your responsibility. Katherine Brown covers this area well in her recent …

Continue reading

Write the docs first

I’m currently pondering a proposal, suggesting to our Dev team that we write the user documentation first, and then use that as the basis of what the product should deliver. This wouldn’t work for everyone but given that an XP environment encourages little (well, less) documentation than a more traditional ISO style project, then having a draft of the user documentation would be beneficial in many ways: Early design thoughts are often lost as they are translated into the stories used to develop the functionality. Fleshing these out into more fully formed documentation would better capture that information, and focus it on the user. Earlier consideration of the “what ifs” will likely come of this, pushing thoughts and discussions out …

Continue reading

Technical Writing Evolved

The following is largely focussed on the software industry as that is where my experience lies. I’ve been an on/off member of the TechWR mailing list for many years now. I dip in and out of threads depending on my current work and knowledge levels. The membership of the list is fairly wide-ranging, with people involved in all sorts of technical communication activites across many different industries. This gives any discussions around our profession and interesting slant as, by and large, the constituent parts of what it means to be a technical writer, and the daily activities involved, are somewhat tied to the industry in which they work. My experience is largely in the software world, but many of the …

Continue reading

Skill Set

Without meaning to I seem to have taken some inspiration from this post, whilst I’m not directly offering a counterpoint, it’s worth a read. ~ Every trade or profession has a skill set, a unique set of talents that make one role different from another. For most people in the IT industry we all have some amount of ‘business-led’ skills such as time management, a little project management perhaps, and so on. As a profession, Technical Communications covers a wide range of skills and some people, depending on their role or the company the work for, can end up being a jack of all trades (master of some?). However, there are some skills that are easily identifiable as being part …

Continue reading

Day in, day outI work in the field of Technical Communications (which is full of poppies and grazing sheep… sorry…). Essentially, whilst I am a ‘team lead/manager’, I am mainly a technical author by trade. So what is a technical author? Basically it is someone who writes manuals. But, as with every other job, there is a lot more to it than that. Our job loosely includes information design, graphic design, indexing and editing skills, the ability to write accurate, unambiguous and technically valid information (usually from a description of how something will function rather than from a completed component), the ability to understand our audience, what information they want, how they want it presented, and how we can best …

Continue reading