Writing about new product features can be hard work, much like digging the garden to prepare for planting vegetables in Spring.
Often technical writers are called in at the last minute to write about a feature that has taken months of development effort and has a specification document running to 100 pages or more. And the release is going out tomorrow!
I first heard about the gardening analogy to writing from Diana Gabaldon, author of the award-winning Outlander novels, and generous supporter and mentor of writers all over the world.
Diana’s advice to writers is to dig where the dirt is loosest. In fiction writing, that means finding a scene or image that you can see clearly, and starting your writing there. But you can apply this same advice to writing technical documents. Find the easiest section to write and start there.
For example, I work for a company that develops an enterprise software application, and so I’m often called on to document new features based on a specification document (Spec). Specs are written so that the developers know what the new feature is supposed to do and how it should be implemented, so they can be extremely technical and difficult to understand. I’m lucky that my manager understands the importance of good Specs. Every year or so, she gives us the opportunity to re-exam the Spec to make sure it provides us with the information we need.
In my case, the Specs follow a template with the following headings:
- Enhancement Objective
- Requirements
- Functional Solution
- Administration/Setup
- Detailed Design
My enhancement document also uses a template, but since my document is for our customers, the information I need to provide is similar but in a different order – an order that will make sense to the customer.
The template I use for the enhancement document has the following headings:
- Purpose
- What is contained in this enhancement
- Administration
- New behavior
- End user instructions
As you can see, these sections don’t exactly match the sections in the Spec. And this is NOT the order I use for writing about the feature. Instead, I dig where the dirt is loosest.
1. Purpose
I like to start with a sentence or two, taken from the Objective statement in the Spec. By writing this first, I now understand what the new feature is supposed to do.
2. Administration
Usually the Spec clearly states what administration and setup the user needs to do before they can use the feature. This is also an easy place to start digging, I mean writing. By the time I’ve finished this section I understand a little more about the new feature, I know if there are any new screens or dialog boxes, and I know enough to write the next section.
3. New behavior
In this section, I write about existing features that have changed to support the new feature. This information is included in the Functional Solution of the Spec. I copy the relevant sections from the Spec, rewrite it to use the present tense and active voice, and include screenshots from our test environment.
4. End user instructions
By now I’m much more familiar with the new feature and I can easily write about the new screens and how a user would use them. I include specific tasks and screenshots with examples.
5. What is contained in the enhancement
Having written all the other sections of the enhancement document, I can quickly write a bulleted list to summarize the changes and new features included in the enhancement.
6. Final review
Once I’ve completed the enhancement document, I read through the Requirements section of the Spec to double-check that the new feature does meet the requirements, and that I have documented the new feature and setup correctly. If the Spec is well-written, I shouldn’t need to review this section, but it’s always helpful to the team for one more person to double-check that we are delivering a feature that meets the requirements.
Obviously this approach won’t work in every situation. If the product you’re documenting is not an enterprise application, a new feature might not require any administration or setup before it can be used. Or if you’re working in an Agile development environment, you might not be using Specs at all. But the main idea is to look at the information you have, and start with the easiest section. As you work through, from easy to more difficult, you accumulate knowledge about the feature and build on what you know, so that you’re better prepared when you get to the difficult sections.
This works for me, but perhaps you have a different approach? Do you have a more efficient way of documenting a new feature? Leave a comment, so we can all learn from your experience!
If you liked this post, consider subscribing to my RSS feed. Or have posts delivered via email. Thanks for visiting!
Photo via Flickr user thegardenbuzz