If you’re like most technical content developers, you’ve been told more than once to produce a user-facing document with only a specification to guide you. Or maybe you’ve been asked to actually write a specification yourself. What?! What does a specification really mean for technical communicators? Isn’t this an engineer thing?
It might be prudent to start by stating the obvious: that specifications are different from user manuals. But specifications help make the procedures in manuals easier to verify, and help them be more consistent. When it comes to internal processes and procedures, they help us be consistent, and also make it easier for us to do single sourcing when we have some way to specify what goes into a doc.
If you’re a beginning to mid-level technical communicator or other content developer who is suddenly confronted with specifications as source material, or needs to write specifications for products or internal processes…. you might be asking yourself, “why do I need this document, anyway?”
Specifications have their distinct place in our digital communication pallet, and it’s useful to take a look at where they fit.
What is a content specification? And why are specifications important?
In the field of technical communications, we talk a lot about procedures. We often use recipes to illustrate our examples or make analogies because, well, they’re pretty everyday procedures that we know how to follow. But a specification is not the same thing – it’s not a procedure.
Let’s take the case of spaghetti and meatballs as an example here to illustrate the difference.
In a specification, we need to start by talking about how the spaghetti pasta is to be produced, and what the raw materials are. We talk about dimensions and how the raw materials should be fabricated.
We define a serving, and we define how the pasta is to be cooked, possibly including some options that may be available. Continuing on, we do the same thing with the meatballs (that’s a separate chapter).
The question for success is: could we actually cook a plate of spaghetti and meatballs from this? And would the construction made by any given “cuisine engineer” taste and look exactly the same, based on the specification?
Such a specification, correctly done, can enable a technical communicator to perform their specific magic of explaining the “how” instead of the “what”.
So, what exactly goes into a specification?
That depends on what kind of a specification it is. For example, a functional specification contains a description of functional characteristics of whatever it is that we’re specifying – i.e. what it does. A requirements spec provides a set of criteria that the product has to satisfy. This can be provided by a buyer to its supplier, or by product managers to the design team, and marketing departments quite regularly provide requirements that help product managers design upcoming releases.
What about our own documents – can we specify those?
We can, and we do. Some of the things that might go into creating such a spec are:
- The scope of the document – its purpose
- The product and release it applies to
- The sources, whether they be written or human
- Some sort of structure
- Table of contents
If you’re specifying an update to an existing document, you also need:
- What do we take out?
- What do we add?
- What do we change?
- Change history
- Terminology
Specifications exist in a fluid world
This may seem paradoxical, since we think of specifications as “freezing” the product. But things happen during development, and products evolve and change because customer needs change even during the development process. So specifications can also be a kind of documentation – they document what was actually built, as well as providing requirements for what needs to be built.
If you work in an agile environment, you might think that specifications are superfluous and not applicable to your processes – but you produce specifications in every daily standup meeting, whether you consider them as such or not. And every iteration creates a new set of specs that you need to apply to the next iteration. You probably don’t call them specs, but that’s what they are.
So how do I hone my skills with specifications?
The most common need for technical content developers in this area is to know how to create specs for internal processes and procedures. These are there to aid your team maintain consistent style, and if it’s your case, develop reuse policies for single sourcing.
If you’re a lone tech author out in the woods and you find yourself with product documents to write for users with no guidelines, you can develop your own specifications before you start.
The skills for this are not far from the ones you already have as a digital communicator. We offer a short course in specifications in the Firehead Training Centre.
Download our guide to specifications
Content expert Ray Gallon has written this checklist to help digital communicators like you, make the most of specifications and help integrate yourself into the product team.
