A software specification answers the what, why, and how. Here are 7 proven tips to create better specs and wireframes before moving to implementation.

Rapid product development has been key to my current and former startups:

The software spec is a crucial deliverable in the product development process, and the tips in this article will help you deliver a high-quality spec in a timely fashion.

1. State the problem in the introduction

Start your spec by clearly explaining the problem you are solving.

You should be able to describe what you are trying to achieve, and why, within a few sentences at most. This is also a good place to add a link to the Balsamiq project that contains the wireframes used in the spec, so that you know where to go to edit your wireframes.

If you find it difficult to properly summarize your problem, this indicates that you may need to revisit the concept.

2. Find the right terminology

If your spec includes some novel concepts, carefully consider your terminology. It may seem like an academic point, but continuously refining and simplifying your terminology will vastly improve the readability of your document. The best term is one that is so intuitive it hardly needs to be explained.

For complex specs, I often provide a dedicated "Terminology" section after the introduction. This helps maintain consistency as your document evolves through a sequence of feedback rounds.

3. Show, don't tell

It's better to use annotated wireframes instead of a paragraph of text. Your readers will thank you.

"Office Editor" annotated wireframe - how to place a seat

1. Select the ‘Seat’ tool
2. As you move the mouse across the canvas, you can see a gray, transparent seat next to your cursor.
3. As you move your mouse near a table, the transparent gray seat will become a solid and ‘snap’ to the table at an appropriate location. This seat will always snap to the edge of the table (a seat is always adjacent to a table). Further, it will snap to reasonable locations along the edge of the table (in a ~1m x 1m table, it would snap at the midpoint of the edge).

I typically use annotated wireframes in one of 2 ways:

1. To demonstrate how to accomplish a task, by showing a sequence of events
2. To describe the UI elements in a wireframe.

I recommend that you use the "Callout" widget to annotate your wireframes in Balsamiq.

4. Learn how to quickly export wireframes to your spec

Balsamiq Wireframes provides some nice shortcuts that let you quickly export wireframes to a spec document:

1. Download your wireframe as a PNG image from Balsamiq Cloud: CMD/CTRL-E,
2. Drag & drop the downloaded PNG into your document.

You'll probably be doing this a lot, so it pays to have an efficient workflow. 😉

5. Use a web-based document editor

Share your specs with a tool that allows for easy feedback, tracked edits, and commenting, such as Google Docs.

Google Docs tip #1: whoever creates a comment thread is responsible for resolving it

1. Bob adds a comment "Can you create a foobar with this?"
2. Jane answers "Yes, I've added a paragraph to clarify this."
3. Bob resolves the comment since he's satisfied with the response.

This ensures that all concerns are systematically addressed, instead of "falling through the cracks".

If Jane had resolved the comment thread after responding in (2), then there is the risk that Bob might not have been happy with the response, but would not inform Jane since the comment is no longer in the document.

Google Docs tip #2: only the spec owner can edit the document

A single person should be responsible for the content of a spec. Others should limit their feedback to comments and suggested edits.

If more than a single person changes the spec, then it will be difficult to maintain coherence and consistency in a complex document.

6. If discussions are strained, move quickly to a call

I think we've all been there: debating an idea in a comment / email thread, with rapid and sometimes heated discussions about "who's right". STOP!

If your back-and-forth in a comment thread doesn't rapidly converge on consensus, mark the comment thread as "To be discussed on a call" and have a video chat with your stakeholder. Disagreements and confusion often evaporate a call, since parties tend to empathize more readily when they can see each other's face.

7. Enforce a tight review process

I generally try to enforce a max of 3 business days per review round, shorter if possible. Longer review rounds will result in people losing context, meaning lower-quality feedback from your stakeholders.

When emailing your stakeholders, make your expectations very clear, and send reminders if you think they will help ensure timely feedback.

Again, it's important to emphasize that the main benefit of a tight review process is that it promotes higher-quality feedback from your stakeholders. We're not trying to speed things up just for the sake of it, rapid feedback rounds will directly improve the quality of your spec.

In conclusion

It's challenging to create a B2B software spec: multiple stakeholders, "users" aren't "buyers", and the requirements are complex.

The goal of a spec'ing process is to try to answer questions about functionality / requirements before entering the prototyping / implementation phase of the project.

By following the above tips to ensure a rapid spec review process, your project should be on the right track for success.