What not to do

Working in a team that isn’t heavily invested in documenting requirements and specifications (we usually have a starting set of such things but these soon fall out of step as development evolves) makes it a challenge to know both what is being added to the product and whether it needs to be documented. The development teams recently adopted JIRA and whilst the additional information helps I fear it may give us a bigger problem. As we will (should?) finally have a clear picture of everything being added to the product, will it be too much for us to handle? At present the Publications team have two very large products, with a complex API and code base which is all evolving …

Continue reading

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 …

Continue reading

Planning your deliverables

I don’t like making presumptions, something that I learned early on in my technical writing career, but I am going to presume that anyone who reads this knows that they should be planning what content they produce before they start writing. You do, right? A basic information plan will include knowledge about the audience, the main areas of the information that need to be covered for the project/release, as well as outlining the purpose of the documentation and any media and design considerations. Finally you’ll most likely provide a definitive list of deliverables, be they printed documents, PDFs or online help. It’s this last area that I’m currently working on. Our product has undergone some exciting changes, and the previous …

Continue reading

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 …

Continue reading