There’s a famous saying “If I had more time, I would have written a shorter letter”. I find it relevant to my work as a Product Manager at Dynamic Yield. A big chunk of my day to day work is spent in writing texts to people who don’t consider reading these texts as their #1 priority. This is true for emails, micro-copy, documentation, and also for my Jira tickets (also known as Product Specs).
Recent years have taught me the importance of concise specs. I remember slow development cycles or developer mistakes that are direct results of wordy specs, and efficient development that is a result of concise specs.
What is “Concise” Anyway?
Let’s start with what it’s not. It is not “Short”. “Short” is a term that might (positively) refer to the agile methodology of breaking big features to smaller pieces, or (negatively) to incomplete information. That’s not it. My definition is:
All relevant information exists, and you cannot remove a word. Meaning, the content is not the king. The reader is.
Why Is Writing Concise Important?
There are 4 main reasons. Let’s list them now and elaborate later:
- No one will really read a long spec.
- Those who do, will not understand it.
- It is very time consuming to understand long spec.
- It is very time consuming to maintain long specs.
Ready? Let’s drill down (or dive in).
1. No One Will Really Read a Long Spec
This might sound depressing, but it’s true. Chances people will read your spec will significantly drop if you don’t use concise writing. Developers like writing code, not reading product specs. And people don’t tend to do things they don’t like doing. So what happens when developers don’t read specs? That’s right: they make mistakes.
Notice, sometimes they will tell you “Oh, right, I forgot that”. But that’s usually because they never really read it — only looked at the mockup, listened to you explain, or maybe just “scanned” your text. In rare cases, they did read it but…
2. Those Who Read, Will Not Understand It
Let’s be honest. Even in school, when you had a short learning material, you could read it once and still ace it. However, if it was long, you probably forgot pieces of the beginning before you even reached the middle. This is exactly the same. Longer texts require multiple readings in order to fully comprehend the content, and as we established in the previous point — no one really wants to read your beautiful literature piece. And that’s leading us to point #3:
3. It Is Very Time Consuming to Understand Long Spec
You hit the jackpot — the relevant people (developers, QA engineer, technical writer, your peers) are actually reading your spec. They are even taking the time to read it more than once. Best-case scenario, everyone took the time to read your specs and they fully understand it. Great, right?
Not really. Because you just “wasted” the company’s precious time; That’s time that people are reading unnecessarily long texts — instead of doing their job. By spending more time in editing down your writing, you actually save multiple “times” to your peers. Thus, saving money for your company.
But if this is not enough, think about yourself…
4. It Is Very Time Consuming to maintain Long Specs
We’ve all been there. You talk to customers, Customer Success, Support, R&D. You had it all figured out. And then you realized a small detail needs to change. It can be a terminology you use, or a change in architecture that has implications on the functionality. Now you need to edit your spec. To do so, you need to spend time reading the entire “novel” just to find all the relevant places that need to be changed. Not only you — your developers need to follow up on every change and read the context in which it was made, and same goes for your QA engineer. More time wasted — to everyone’s involved, including you.
Summary
It is so important to write concise specs. Specs that have all the relevant information, with the reader in mind and not the content. This will save you from developers’ unnecessary mistakes, and will keep everyone involved more efficient.
