So you need a software specification

I don't remember if I have written about this already, but if so, let's say this this a recap and introduction to my next post. While I talk of software specification here, the term used might as well be requirement specification or somesuch; in this case they could be used interchangeably.

Software specification is often overlooked as something trivial which can be handed to be written by some random trainee. In my experience this is completely and absolutely wrong way. While anyone theoretically can write a software specification, such specification rarely is worth the paper it's printed on (doubly so if it's never actually printed). Writing a good specification however is extremely difficult and should never ever allowed to be written by anyone who isn't both excellent software designer and at least proficient (tech) writer. And of course motivated to get it right, but first part there pretty strongly implies this already.

If you are dealing with internal projects you can most likely get away with a relatively poor specification. "Internal" here means "within the same small group I'm working in." If your company's work culture is good, group members communicate freely and easily and can always work around shortcomings and mistakes in the original specification, as long as issues are relatively small. (I'm completely ignoring the scheduling and budgeting here although they naturally are related topics, this is all about the specification quality).

Years ago I was given something that could be called a project plan. It described a software that needed to be written in very general terms, in just a few pages. I was sufficiently familiar with system this was to work with that I could tell them that yeah, I could do this in just a few weeks (so really nothing too major). I was told that no, they wanted to outsource this and I had to write the specification for it, primarily as an experiment on how outsourcing would work in this company's case. So I shrugged and got on it.
I found out that it took me about the same time to write the very detailed specification (covering every single detail I could think of) as if we had done the entire project internally. And then it took remote group even more time to write the actual code. The end result wasn't really bad, of which I blame my pretty good specification, but it still took quite a long time.
I don't really know if this company learned anything of this, but I certainly did.

The further away you get from your own group, the more detailed the spec must be be. Reason is both cultural and communicative; it's far more difficult and slower to ask for clarification for some part when you are not familiar with person who wrote the spec, even if person works just for different part of same company - and this gets worse the further away person writing the spec and code get.

Having direct line of communication helps - if you can communicate with your counterpart at the other side of the world, even with email, things are easier. If however communication must go through few layers of middle management at both ends it's pretty much automatically game over. More communication layers means that much of the message gets lost in translation (both literally and figuratively.)  In such case any shortcomings in initial specification means that the results will be pure rubbish. If resulting code/software can be reviewed often enough it may save something (specification can be improved and made more detailed where it is found lacking), but if you only get to see the end result - forget all hope. It most likely will be useless.

Of course in some cases a good developer may read between lines and implement details implied in specification, but you may never, ever rely on this - good developers aren't that abundant, especially on that level. Very likely the person writing the code has no idea on background and related environment where this software should work so he has no way of figuring out issues you might consider self evident.

So, whenever you find that a software specification (or requirement specification) needs to be written, always make sure that it is written by most experienced software developer you can find, and absolutely no detail (no matter how trivial or self-evident it seems) is left out. Those will come back to bite you in the end.

Yes, it will take a long time and cost a lot up front. But this is the part you absolutely do not want to skimp on, as those relatively minor savings will come back to bite you in end.