Blog post
It probably happened while you were foraging the expanses of the Internet and you came across something like this:
You’ve read it, thought deeply about it, and finally decided that it was one of the most profound things ever written by a human being and that you want in on that sweet, sweet requirements writing action right away.
Well, good for you. But we do need to figure out a few things first.
“Can you write?”
You might think that it’s a stupid question to begin with, since you can obviously read and you needed to type something into that search box to even get here. You might also be inclined to point out that besides just being stupid, the question is, at the same time, a superficial one, since the ability to write is something that would obviously be required for a job where you need to document the requirements in some kind of written form.
And you’d be right on both accounts if what I was referring to was the basic ability to record your internal monologue in the form of a string of words on a piece of permanent storage. However, I’m not.
What I’m talking about here is the level of writing ability where you do just what I described a sentence before, but in a way that is also concise, well structured, grammatically sound, and to top it all off — in a form that is both as easy to read as possible and unambiguous enough to be readily “attachable” to a legally binding document.
That is actually not at all easy to do, and I’ll be blunt here — the majority of people I’ve met in my career couldn’t really write their way out of a wet paper bag if their life depended on it. And I’m talking about really smart and otherwise competent people here.
By extension and liberal use of statistics, that more likely than not includes you as well.
You might argue something along the lines of “but I write on a daily basis — emails and such — and no one seems to be complaining about my writing, you arrogant piece of filth”. I applaud your eloquence, but at the same time, I want to state that your argument is invalid because we’re talking about quite different formats (although you’ve nailed that “arrogant filth” thing right on the head there).
The thing is that what most people, at least in my experience, tend to write on a daily basis is mostly short and even very short-form pieces, and those allow for really terrible form, while still being technically readable, simply because your reader’s brain will fill the content holes similar to how it does when you rd smthng wrttn lke ths.
The requirements are, however, almost always in medium to long-form and what works for your typical email, simply doesn’t work anymore in that context.
Additionally, few mails are ever going to (voluntarily) become an annex to a legal document, and they don’t need to pack nearly as much precise information as a requirement document does. Furthermore, they are usually not a single source of truth for some topic, but rather a part of a conversation — i.e. one of many.
My proposition here is that, to write medium to long-form content and still make it digestible to an average reader, you need to write well, not just be able to write. The fact that you can do something relatively effortlessly (write), doesn’t automatically mean that you can do it well.
For example, I can swim. I can swim in a sense that if I fall into the water by accident — I won’t drown, and I can and will swim around purely for the purpose of fun. I don’t find swimming that hard.
However, when I do jump in, my form closely resembles that of a plucked chicken, and my overall technique is best described as “generally lacking”.
In short, my swimming ability is good enough for keeping me alive in the water and even for purposes of pure leisure, but it would be totally inadequate for any advanced task, such as swimming long distances or achieving any kind of speed, etc. If I decided to engage in any of those activities, I’d need to improve my swimming skills considerably.
So, you really need to be able to write well. If you can’t, then the first thing you need to do is to learn how to do it. Try with a few single page essays on any topic you’re familiar with, have someone critical (and literate) read it and give you an honest feedback and then go from there.
Also, I recommend that you read a good book on the subject — such as, for example, “On writing well” (I haven’t read it myself because I’m such a good writer that If I were merely 37 years younger, I’d certainly be considered a child prodigy, but it is truly an excellent book, and you should read it).
After you’ve read a book on writing (or even if you haven’t) — just write. There is no other way to get better at it — think of that swimming example — you can read all the books on swimming (and there are many) and watch all the instructional videos on swimming on YouTube, but you
will not learn how to actually do it until you get in the water and swim.
So, once you’ve learned to write well, we can then move to the next point.
“Do you like to write?”
This is another big one. One that is quite crucial, since, as a requirements writer/architect, you’d be doing a lot of (sic) writing, so you better like it or you’ll hate your job and burn out eventually.
This also seems quite obvious, but it goes beyond simply liking the process of expressing yourself through writing. You need to enjoy (or at least not be annoyed by it) the very act of writing, since requirements writing usually requires a lot of rewrites.
There is one caveat there, however, and it happened to me as well — liking to write and being able to write well at the same time often also include liking what you have written. This is understandable and almost unavoidable, but unfortunately — in the requirements writing situation, it’s also something you do eventually need to break out of.
However well written your requirements are, they are primarily a technical, utilitarian document that should get changed in any of its parts the moment you acquire some new knowledge about the project itself or the context in which it will exist, once it’s built.
You are not writing a next great <insert your country name here in adjective form> novel. You are not an artist, but a craftsman first and the writing in the context of requirements documentation is not an art form, but rather a fine craft. If you are really good at it — you can sneak a bit of an art in there and kind of blur the line between the two (think “Tex: the program” by Donald Knuth) but that’s not really the requirement or even a part of the job.
However, the pure act of writing is, and since you’ll be doing it a lot, you better enjoy it.
If you don’t like to write, you’re out of luck, requirements engineering is not for you and if you still decide to go into it for some reason, you won’t be very good at it and you’ll hate it at the same time(1).
If you do like to write, however, then we’re cooking and it’s time to tackle our next topic.
“Do you know the proper technique?”
Finally, we got ourselves an easy one. If you got through the first two, you’re golden.
The technique is not that difficult to learn, and there are excellent learning materials available such as “Writing effective use cases” by Alistair Cockburn and “Specification by example” by Gojko Adzic, just to name a few brilliant ones. But there are many more, including a series of blog posts on the topic of writing software requirements specifications, written by the guy who, if he was 37 years younger, would be considered a child prodigy.
However, you do need to know and understand the technique well and not just get quickly acquainted with it and then start breaking the form immediately.
Don’t think that just because you can write well and like to write, you can neglect the craft and just “wing it”(2).
Always keep in mind that (according to Audemars Piguet — a person whose qualifications include being the master craftsman of the ridiculously precise fine mechanics and most likely being much smarter than me) — ‘To break the rules, you must first master them’.
The technique, however, really boils down to understanding and using some standardized forms of writing and structuring the content. Its main benefit is twofold:
- it provides you with the framework which, if used correctly, will force you to ask yourself and other people questions you might have otherwise overlooked, and
- it assures that the end product would be readable by people other than you — as long as the content you put in is written well and the content itself is of good enough quality to start with.
So the technique is comparatively easy (if you can write well) and there are good learning resources available. So if you don’t know it yet — just learn it and we can then move on to the next topic.
“Do you like to learn new stuff (and can you do it quickly)?”
You can’t really write requirements for something you’re ignorant about. Even more so, you cannot really remain ignorant about something you’ve written requirements for.
As a consequence, writing requirements for something invariably involves learning the essentials of that something — being, at the same time, fully aware that your knowledge is very spotty, and being able to easily identify knowledge gaps.
This fact is even more pronounced if you work for a software development agency, in which case you will often encounter clients from very different domains, and you’ll have to learn the ropes of all those domains quickly, if you want to have any chance of capturing their requirements with any quality — and especially when the client is unable to formulate it’s wishes or ideas well or has a very narrow vision of “what he/she wants”.
Let me be clear here, your goal is not to master each and every domain you write requirements for. You will never ever have nearly enough time for that. What you need to be able to do is to quickly identify important bits, figure them out as quickly as possible, and then get to the point where you understand just enough of that domain that the requirements you’re eliciting and wiring down make both business and functional sense to you at every point of their writing. Also, this will allow you to ask precise, exploratory questions in order to identify edge cases and functional gaps — and that is a crucial skill to have as a requirement architect.
Remember that you should never, ever produce a set of requirements that doesn’t make functional sense to you. You don’t need to completely understand the business model though, but it also shouldn’t be a complete mystery to you.
So, if you don’t like learning new stuff often through the means of, for example, reading non-fiction, engaging in various hobbies, and pursuing knowledge in general, just for the pure joy of learning something new — you probably won’t like this job (and you’re missing out on a bunch of amazing, unbelievable things that happened, will happen or are actually happening around you right now).
If that’s the case — you can still make a decent requirement architect, but I’d strongly advise against doing so in an agency setting — but rather in a single industry scenario where you need to learn the basics only once and then update them once in a while.
Conclusion
If the answer to all those questions above is either a sound “yes” (with one or two “not at the moment, but I can and want to learn”) — you’ll be ok. The technique itself is not that hard to learn, and if you do like writing and learning new stuff, then it’s just a matter of learning the techniques and additional polishing of your writing skills.
I’ll give you an example of how I feel about this job — it might help you, or it might not, but I’ll tell you anyway, since I like to write.
I am, first and foremost, a developer and an application architect, but discovering and documenting requirements is something that I found out I enjoy quite a bit and something that I tend to do more and more as the years go by.
It contains a lot of stuff that I like, such as (technical) writing, learning new stuff, discovering edge cases by prying the important information from often uncooperative/confused people, and the end result is fleshing out something that, until that moment, existed only in the minds of those uncooperative/confused people, within their management presentation slides or in someone’s digital equivalent of scrapbook notes.
I don’t consider it a fundamentally creative process per se, as I’m not really creating the product for the client or inventing anything at all, but for me, it comes rather close to it.
In my eyes, what I do is create and introduce to the world the first material embodiment of that future product/project idea, and, at least to me, that’s pretty cool as well.
I liken my role as a requirements architect to that of a good music producer in a recording session, and I think that analogy does hold true. It’s an essential role without which the chain of events, leading from the conception of a product idea and ending in its release into the world, is irrevocably broken and the success is left to chance more than anything else.
So the conclusion I’m trying to get across here boils down mainly to these points:
- Requirements architects are an elusive breed of awesome superhumans
- They play a fundamental and irreplaceable role within the software production process
- I quite like being one
- You might enjoy it too.
Addendum
Since it takes all sorts, if that particular combination of doing something while sucking at it and hating it at the same time is exactly what gets you off — then kudos to you (and condolences to the people who’ll be working with you).
You actually can do just that, as I’ve done that for at least the first couple of requirements I’ve written professionally — since at that time I had no idea that any techniques existed — but take my advice and don’t do it, it’s an approach that doesn’t scale at all.
