Tag: ISO

What do you write?

Most of my experience is based around software documentation. Whilst there are several levels to this, from task oriented User Guides through to highly technical API/SDK documentation, they tend to follow similar patterns making it easy for me to take my experience and apply it to new challenges.

I’ve also been involved in writing up procedures and guidelines as part of an ISO quality system, a little whitepaper style writing, and even the odd product brochure. All of which require a slightly different approach but the same grounding in the basics of understanding the audience.

However I’m aware that there are many other forms of technical writing, and I’m curious to find out what everyone else does? Do you write documentation for hardware products? Do you write proposals? Procedures?

Ultimately I’m starting to look at other areas of our profession to see if there are any good things that I can re-use where I am. If you have a moment, I’d love to hear what your main writing focus is, let me know in the comments.

Trickle and Blink

“There is no such thing as too much information”

We’ve all heard this statement at one time or another, and in the internet age it’s accepted as a statement of truth. Which is shame as it’s completely wrong. Turns out, that you only need enough information, not all of it.

A while ago I wrote up some thoughts on how to integrate an authoring team into an Extreme Programming (Agile) development group. The post Trickle vs Traditional outlined a basic way of building up the required content throughout the various stages of an XP release and, to save you re-reading that post, let me grab the crux of what I was saying:

The trickle method relies on the ability of the technical author to retain a “big picture” view whilst working on multiple chunks of information at any one time. The information will not come in a set order, nor from a definitive source, instead it will trickle in from various parts of the development team, testing, and so on. Your job is to monitor the flows of information, position yourself within a stream (or two) and divert the information you need into the documentation.

In reality this means that you need to develop a good technique for filtering information, knowing when and what to leave out of the documentation and relying on your knowledge of the product to help you make decisions and make them quickly.

Quite simply, to remain agile in such a system you need to be able to make decisions. A decision can be wrong, as long as you make the decision to fix it as soon as possible.

In a way, you start to write by instinct, trusting that you properly understand all the myriad of factors that influence what information you are creating and letting your talents as a technical writer take over. As Malcolm Gladwell, who wrote an entire book about this type of decision making, suggests:

We live in a society dedicated to the idea that we’re always better off gathering as much information and spending as much time as possible in deliberation. As children, this lesson is drummed into us again and again: haste makes waste, look before you leap, stop and think. But I don’t think this is true. There are lots of situations–particularly at times of high pressure and stress–when haste does not make waste, when our snap judgments and first impressions offer a much better means of making sense of the world. [source]

All of that sounds slightly scary if you are currently working in a process-heavy environment, with requirements and specification documents been seen as a way to provide all the information everyone needs, and which are typically a rather slow cumbersome way of handling information.

Anyone who has written such a document knows how hard they are to do as you can’t know everything at the start of a project and over time things change. Having previously worked in ISO regulated companies, where the audit history of a document was almost more important than the information in the document itself, I know how onerous, time-consuming and false those systems can end up being. Many is the time when everyone in a discussion knows what is going on but you still have to write it up, review and approve it, before it can be officially logged in a system that is rarely referenced.

Monitoring the flow of information, trickling it into your documentation as and when needed, making quick decisions and trusting your instincts certainly feels like a more natural way to work. It does mean that there is no such thing as a final document and there is a chance you will publish something that is wrong; yet it is the very possibility of that happening which keeps itself in check. Allowing people to make their own decisions instills a higher level of professionalism and lowers the number of errors.

It’s not suitable for everyone and some industries wouldn’t enter it but it’s an interesting way to work. Limiting the amount of information you have available, and making decisions based on those seems wrong but it does work. You just need to be brave.

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:

  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.