Tag: QA

bookmark_borderWhy technical reviews fail

Posted on

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 article, noting that:

reviews can often go awry for a number of reasons at a number of points in the overall process:

  • Poor communication
  • Lack of preparation
  • Lack of management support
  • Unclear expectations and objectives for the review
  • Insufficient time planned for the review
  • Lack of follow-up
  • Wrong people involved, or right people involved at the wrong time

Katherine goes on to offer solutions to all of these issues, but I have a different slant, namely:

  • Poor communication – if, as a technical author, you cannot communicate there are bigger problems than the technical review!
  • Lack of preparation – you are asking reviewers to give up their time, even if it is agreed many will consider this an ‘extra’ piece of work. Not preparing for this is likely to come across as both unprofessional and arrogant. If you don’t seem to care about the review, why should they?
  • Lack of management support – yes, we do need to fight a little harder to get support for our work from management. No, it isn’t the way it should be. As professionals we need to learn to promote ourselves and, by our actions, gain the support we need.
  • Unclear expectations and objectives for the review – as I’ve said, many people treat reviews as an interruption, so it’s up to you to make the objectives and requirements clear. What should they be looking for? What should they report back, and how? If they have a general query how do they present it during the review?
  • Insufficient time planned for the review – as a project manager once said to me, there is no such thing as “not enough time” just something called bad planning. Yes you may need to fight to get allocated time (and you should, ad-hoc reviews are never as productive as well organised and scheduled sessions) but it is an important part of the technical publications process, so fight your corner hard.
  • Lack of follow-up – It’s not hard to send a short email, summarising the main review comments or outcomes, to those that were involved. This is something I am terrible at but I know, when I’ve received similar communications, how well they work and how good they make me feel.
  • Wrong people involved, or right people involved at the wrong time – “The more eyes the better” doesn’t always hold true. You need to figure out the best people, and make sure they are reviewing the content at the correct time, enlisting the help of your friendly project manager if required.

This may seem harsh but, and this is something I’m guilty of myself, there can be a tendency to wrongly apportion blame, to presume that the technical reviews are failing because no-one else is interested, or presuming that the work you do doesn’t need a review anyway (and you hate to bother those busy developers, right?).

We are responsible for our work, we are responsible for the information we produce and as the technical review is part of that production process (it is NOT a QA check!) then, if it is failing… well, I’m sorry, but it’s your fault.

bookmark_borderWrite the docs first

Posted on

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:

  1. 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.
  2. Earlier consideration of the “what ifs” will likely come of this, pushing thoughts and discussions out into areas that the documentation needs to cover but which might not be considered as they might not be part of the software.
  3. Focussing on the final product, rather than just the next piece of functionality, should make the big picture easier to see, allowing the developers to better understand WHY they are working on a particular piece of functionality.
  4. Testing/QA can use the documentation to validate the software that is being produced. If it doesn’t match the documentation, it’s wrong.
  5. Anyone coming late to the team can get up to speed much quicker.

I’m still thinking this through, and by pushing on with the documentation, sometimes even striding ahead of development, the technical author can help with the finer details of the implementation, running through some of the scenarios (or edge cases, or “unhappy path trails” depending on your lexicon) before they have been approached by development, blazing a trail for them to follow. After all, we spend a lot of our time considering things the readers of our documentation are likely to ask, if the answers need to come through the software then what better way to develop the solution?

All of this would, of course, be in close consultation with the development team but I think it might be an interesting experiment to try.

Anyone got any thoughts? Pros? Cons??

Update: I posted about this on the TechWR mailing list, and Andrew Warren pointed me at his previous response on this topic. Interesting.

bookmark_borderTechnical Writing Evolved

Posted on

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 other list members have wholly hardware-based experience, yet others work in highly regulated environments, and some flit from contract to contract, job to job.

A while ago a discussion about how our profession was changing kicked off and the range of responses was fascinating. This wasn’t a surprise of course, the list is full of passionate and intelligent people, but did have the effect of causing me to sit back and reflect a little more on what I do for a living and how, ultimately, it’s a fairly unique profession.

The discussion centred, mainly, around how the emphasis for a lot of technical writing jobs is swaying more and more towards a more integrated approach to the role and how it fits within a team than the historical basis of being heavily centred on writing. The presumption (largely being pushed by those of us in the software environments) is that the skillset a Technical Writer brings to a team extends beyond “just writing the docs”. As a customer advocate, we can (and should) influence UI design and the functionality of the product, and increasingly we are involved in the early design discussions, get hold of early builds and so on. To a small degree, today’s Technical Writer whilst retaining the core function of writing documentation, also dabbles in UI design, functional analysis, sanity testing software (note: this is not QA by any means!) and may even contribute to the software itself.

Some say that this detracts from the role for which we were hired. I disagree.

The role of product documentation is hugely important to any company and its creation will always be the core function of a technical writer. However, as companies push to reduce timescales and costs, whilst ask that productivity is increased, the idea of a closely-knit team with a shared vision becomes all the more necessary. Integrating a Technical Writer into that kind of environment means that speciality becomes less of an issue, and everyone starts doing a little bit of everything else. This extends beyond the Technical Writer, obviously, but uniquely we span the divide between technology and user (application and customer) and so can start to play a larger part in the development of the applications themselves, and also lessen the impact on our own area of expertise.

As I stated in that discussion:

I’ve always presumed that the role of technical writing isn’t really about ‘writing’ all that much (these days) and is why I’ve pushed to change job and team titles away from “writing” or “publications” to “communications”. It’s a small thing, but I think it breaks the “document monkeys” label a lot of people still have in their heads.

What this can mean is that a Technical Writer needs to have a sufficient knowledge to be able to intelligently converse with the application developers, and a good understanding of the business and user requirements that are currently being worked on. Acting as a “user proxy” in early design meetings has the double bonus of improving the application being developed (as most developers have a tendency to think in terms of functionality, rather than task) and hopefully easing the burden on the documentation as the general usability should be improved.

A bold statement perhaps, but ultimately the long-term aim is to have a better grounding in the usage of the application for which you are writing documentation. Understanding the why, and the who, as well as the how, is not a new thing of course, but contributing to the team in a “non-document” way is the real benefit.

A lot of companies still view product documentation, and the technical writers who produce it, as necessary evils to be tolerated and humoured. Most technical writers are able to constructively challenge and change that perception and I’m certainly not suggesting that anything I’ve suggested is the only way to do things. But I do believe that, in software documentation, there is a growing call for more technically technical writers, as opposed to technical writing writers. Becoming the accepted user-advocate in your development team is one path to achieving this, and I firmly believe that it will enhance both your own career and the perception of our profession.

Additional links: TechWR Mailing List.

bookmark_borderSkill Set

Posted on

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 of our core job and apply to most, if not all, technical writing positions, for example:

  • Writing
  • Editing
  • Indexing

After that we can look to other areas in which some technical writers dabble, either because of company need or personal curiosity, such as:

  • Graphic design
  • QA/Testing
  • Coding
  • Usability
  • Information Architecture

All of these skills are professions in their own right, and whilst I would never suggest that a technical writer could replace like for like, we do tend to inherit a few additional skills as we bumble along. The specifics and amount vary from person to person, situation to situation, and whilst that means that no two jobs are the same it does present a small quandary.

How do we come up with a generic job description for our profession?

Even if I was to limit the scope of that question to my own personal experience, having worked in 5 different software companies with each having a slightly different view of what my role should be (and with each role being developed in a different way once I had joined the company), it’s still hard to get a single, generic, job description.

This all sparks another question, why do we need a generic job description for our profession?

Well put it this way. A software developer will have a set of skills, but I’d warrant that their list of core skills far outweights the list of their secondary skills. There is an understanding that a software developer will know certain things, and that list is far longer than that of a technical writer yet we have the potential to bring so much more than ‘just writing’ to a company.

To help publicise our capabilities, and the benefits of having a dedicated technical writing team within your company, a generic job description is an ideal starting point to make sure the hiring managers of the world know what we CAN do, if given half a chance.

I know that a generic job description will never match any one role, but I imagine it like a pie chart, with each slice (skill) growing or shrinking to meet the job specification. But before we can bake that pie we need a full list of ingredients.

So, what have I missed? What other roles and skills do you bring with you to a company? Let us build our generic technical writer, we can call her Tina… (or maybe not)

Posted on

Day in, day out
I 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 tailor our output to their needs. We need to be technically competent to the same level as our users, need to be able to talk to developers, consultants, SMEs, product managers, technical support and testing/QA staff. We need to be able to take information from a variety of information sources and levels and distill it into one consistent, readable, usable document (or two). Ohh and we have to deal with translation issues, print shop demands and are typically asked for input to sales and marketing documents, corporate intranet and websites etc etc.

Most technical authors tend to favour one area of work to another, my personal preference is in the early planning and design phases, and I don’t enjoy the writing phase. Other authors prefer the writing phase but may be less technically minded than others who, in turn, prefer the interaction and collation of information and the filtering and learning process that must be passed through. We are a strange bunch, by all accounts, akin (possibly) to the goalkeeper of a football (soccer) team. Our mistakes are obvious, our part of the product typically goes untested, and frequently is only validated internally rather than externally by the people the document is aimed at…

Hmmmm, this wasn’t supposed to turn into an essay.

As I said, I prefer the information design stage of a project and have been delightedly working my way through this list for a while now, picking up books when I can. I spotted a link to it on another site yesterday which reminded me that I’ve not bought a work related book for an age. The reading list takes the view that information design (experience design) is not a sole art, but knowledge can be gathered from a wide variety of sources and used across all the mediums covered.

Experience Design Reading “The following books cover many disciplines, from Interaction and Visual Design to Filmmaking to Architecture, but all relate loosely to the various processes, ideologies, visions and practicalities of Experience Design.”