The common cliché is that software engineers are not very good at communication, and by extension don’t write good specifications. In my experience, I have found that failure to create good technical specifications is caused by one of two reasons – engineers are not aware or cannot use effectively the basic tools for writing specifications, and second engineers may not have the right motivation at the time they attempt to write one.
This blog is about how to write readable specifications – the 6 tools I consider most essential for making written communication easily readable and reviewable:
- List of open issues
Throughout this blog I used other simple but essential tools – see if you can spot them (answers at the bottom).
As a disclaimer, I use MS Word for the examples here because that’s the tool I am most familiar with. However, any non-trivial word editing application will have rich support for these tools.
Bulleted lists and numbered lists are perhaps the simplest tool in the trade for writing readable content. Paragraphs of text with items separated by a comma or semicolon can work well when giving illustrative examples, but are hard to read if the user has to parse out the exact items listed there. Bulleted or number lists are a great alternative, as they separate visually each individual .
Compare the readability of this requirement expressed as a paragraph and as a list:
Feature Jiggamathinger must work and must be supported on Windows Vista RTM, Windows Vista Service Pack 1, Windows Vista Service Pack 2, Windows 7 Service Pack 1, and Windows 8 RTM.
Feature Jiggamathinger must work and must be supported on:
- Windows Vista RTM
- Windows Vista Service Pack 1
- Windows Vista Service Pack 2
- Windows 7 Service Pack 1
- Windows 8 RTM
Which version would you say is more readable? And which version do you think would lead the reader (and yes, the writer of the spec) to question if an OS version was perhaps missed? For an answer, see the bottom of this blog.
In addition to being more readable than the paragraph equivalent, bulleted lists and numbered lists are very easy to create. Just type the star key (* – SHIFT+8 on QWERTY keyboards) followed by a space, and MS Word will start the bulleted list for you. Type 1 followed by space, and MS Word will start a numbered list for you.
Alternatively, click the bullets icon:
Numbered lists are fine too, however consider using them only if there’s rationale for ordering them exactly as they are listed. Once you introduce the numbers, you may be tempted to refer to them which is good, but it will take a bit more work – you will need to reference individual items by inserting a cross-reference to the number, otherwise “hard-coding” the list number may get easily out of sync if you add or remove an entry prior to this item.
Tables are another simple yet impactful tool available to focus the attention of the writer and to make it more readable. By defining a rigid structure (the table cells in which information needs to go), tables state very explicit (and hence make reviewable) what type of information is being collected, what information has been collected so far, and what information is still needed.
In their simplest form, tables can be used as lists on steroids when the list needs to incorporate several attributes consistently.
Compare the readability of this updated requirement:
Feature Jiggamathinger must work and must be supported on the following platforms:
- Windows Vista RTM (Priority 2) – lower priority than SP1 and SP2 because most consumer and enterprise deployments will have updated their Vista deployments to SP2 by the time the product ships
- Windows Vista Service Pack 1 (Priority 1) – some people/enterprises may be slow to deploy SP2
- Windows Vista Service Pack 2 (Priority 0) – most Vista deployments will be SP2 by the time we ship
- Windows 7 RTM (Priority 0) – most non-Vista deployments will be W7 by the time we ship
- Windows 7 Service Pack 1 (Priority TBD) – not sure about this – is it higher or lower priority than W7 RTM?
- Windows 8 RTM (Priority 1) – W8 will be a growing platform, more important that Vista RTM, but not as important as Vista SP2 or W7 for now
Feature Jiggamathinger must work and must be supported on the following platforms:
|Windows Vista RTM||2||Lower priority than SP1 and SP2 because most consumer and enterprise deployments will have updated their Vista deployments to SP2 by the time the product ships|
|Windows Vista Service Pack 1||1||Some people/enterprises may be slow to deploy SP2|
|Windows Vista Service Pack 2||0||Most Vista deployments will be SP2 by the time we ship|
|Windows 7 RTM||0||Most non-Vista deployments will be W7 by the time we ship|
|Windows 7 Service Pack 1||TBD||TBD: Not sure about this – is it higher or lower priority than W7 RTM?|
|Windows 8 RTM||1||W8 will be a growing platform, more important that Vista RTM, but not as important as Vista SP2 or W7 for now|
Using this table improves readability in several ways, by allowing the writer and the reader to:
- Focus on one aspect at a time – the reader can focus first on the list of OS-s, and only if she agrees with the list, focus next on the priorities and the justifications. The writer can similarly focus on one thing at a time – such as identifying all potentially relevant releases, and only then deciding what priorities they need to have and why.
- Skip unwanted information – if the reader doesn’t care about the justification, the visual layout allows her to easily avoid looking at the justification section – which in most similar cases would contain more text than the rest of the fields.
- Easily identify the considered attributes – in this case Supported OS-s, Priority, and Justification – and determine if other attributes may need to be considered for this requirement. Since the attributes are clearly spelled out, it becomes easy to see that another attribute is potentially relevant – Bitness (x86 or amd64).
- Use table-specific capabilities – for example, the user could invoke the Sort functionality for that table to sort the requirements by Priority or by Year of Release (if that attribute was used) to see the requirements from another angle.
Another simple and yet powerful usage of a table is to specify relationships across two sets of attributes, for example supported features across operating systems:
|OS 1||OS2||…||OS M|
In this mode, each cell communicates clearly whether, the feature is supported, is not supported, or the decision is not made yet.
Adding tables is trivial too – for a basic table, click the Tables icon and with the mouse click to indicate how many rows and columns you need, and the table will be added:
Making tables more fancy or using various styles is easy too – simply use some of the other options:
A picture is worth a thousand words, and diagrams are the pictures of software specifications. No design specification would be complete without at least a few diagrams – one diagram describing at a high level the architecture , and any number of additional diagrams describing various specifics – such as interactions among various components, class diagrams, state machines and transitions, and much more.
Since diagrams are a huge subject, I will leave them for a separate blog. If you’ve never used diagrams before, here is a good overview of UML diagrams. A number of tools can help you create great diagrams. I typically use MS PowerPoint and Visio. This blog talks about some other good tools.
Markers are little chunks of text that have special meaning that you can leave in the document to be able to find easily in the future, such as:
- TBD – short for To Be Decided – by far the most common marker I’ve seen across specifications, used to indicate a detail for which a decision has not been made yet, but which may be too trivial to include in the Open Issues section
- CUT – a portion of the spec which has been considered at some point, but was cut from the final version of the spec
- ACTION – typically followed by a name – indicates that someone other than the spec owner has taken an action item to complete the specified research
Since even the simplest text editing tools support searching up/down, next/previous, case sensitive/insensitive, using markers is a very efficient way to annotate your specs.
The marker TBD in particular can be very helpful in preventing you from getting distracted on minor details. Simply keep working on the big problem and leave TBD-s notes on anything aspect that will need addressing at some point but it not essential to the solution of the problem.
You started the work on the spec, you captured the background of the problem and some important requirements, and are now working on the design.
Time to organize your thoughts into sections so you can continue to focus on individual problems one at a time. Simply type the name of the section, click “Heading 1”, and voila, you have a new section with all “normal” text underneath turning into text inside that section.
Sections enable you to take advantage of other powerful features of MS Word – such as creating navigable cross references to the section (e.g. “This is explained in more details in section “Detailed Design”), viewing the document in Outline mode in which you can collapse or expand sections and subsections, creating a Table of Contents, and more.
My favorite usage of the sections is for navigating the document – simply enable the Navigation Pane, and then click on a section name in that pane to set the cursor at the start of that section:
A word of caution – while sections can be emulated easily by changing the formatting of the section title to a bigger font with different color, that won’t make the text a “Section title”. As a result, it won’t be added to the list of sections, will not be available to accessibility tools such as screen readers, and will not allow you to create references to it – therefore you should avoid creating “sections” in that manner if the editor you use allows you to create “real” sections.
List of open issues
While a list of open issues is just another section in the document, it is so infrequently used, and yet so impactful, that I believe it deserves to be in the top 5 tools. And that’s before even talking about diagrams, which themselves deserve a full blog just as an introduction.
The list of open issues is a separate section which lists questions that needs to be investigated further and which could have a non-trivial impact on the product, the name of the person who will figure out the details, and an ETA for resolving the issue, such as this simple table:
|John||Final spec approval||Should we support IPv6 or just IPv4?|
In most practical cases, since the owner for resolving the issue would be the owner of the spec, and the “Resolve by” would need to be before the spec is approved, this table could be changed to a simple bullet point list.
Having a Open Issues list has the following benefits:
- Calls out areas that need attention – reviewers can look at this section to get a sense of what the status of the spec is, regardless of what any “status” field of the spec may report.
- Proactively answers or delays questions – by explicitly calling out the areas that need more work
- Helps the writer manage the open issues – by providing one place where all the issues are tracked (minor TBD items throughout the spec could be covered by one item in the Open Issue list, such as “Resolve all TBD-s”).
- Helps the writer by setting the right expectations – without a section on Open Issues, the spec writer would be implicitly pressured to produce a perfect and complete specification for each review, something that he or she may not be able to accomplish at that time, and that may cause the writer to delay reviewing critical aspects earlier until non-essential aspects are “buttoned up”
If you are not accustomed to these tools – which may be the case if you’ve read this far – challenge yourself to use them next time you need to write a spec, or even just a short email. You will be pleasantly surprised at how much more effective your written communication will become.
- From the introduction: some of the other critical common tools for writing not specifically called out above are formatting (such as bold, underline, or color), images, and hyperlinks.
- From section Lists: if Windows 7 Service Pack 1 needs to be supported, most likely Windows 7 RTM needs at least to be considered.