HN Explorer

Ask HN: How do I learn to write good software specifications?

7 points by ciaoben ↗ HN
I want to be able to hire freelancers and to give them documents that make our communication effortless and clear. Make them jobs as developers easier, any advice or good resource to suggest?

6 comments

[ 3.1 ms ] story [ 20.4 ms ] thread
AnimalMuppet
First, you should have had to implement a number of specifications yourself, so that you have experience about what kinds of things are unclear.

Second, you should have someone else read the specs you produce, to help find the places where what you wrote was clear to you, but not clear to someone who didn't already know what you meant.

And third, you need to make it very clear: If you don't understand, ask. Email me. Better yet, call me.

itamarst
Behavior-driven development (BDD) tools are designed to help with this use case: sitting down and defining the high-level criteria for functionality.
fiftyacorn
Whats your experience in practice of BDD? It sets out requirements in a way a developer simply churns out code, but I can see a lot of business analysts I've worked with struggling to implement at this level. Use case and Jira's are about as low as they want to go
itamarst
No personal experience, but met some people at last year's PyCon who were very happy with results of using it.

Also my understanding is that it's not about churning out requirements, it's about having a conversation and everyone agreeing to a concrete, shared set of requirements.

brudgers
Hiring good contractors is always going to get you farther than good specifications. A good contractor will fill in the gaps in the spec and make something better. On the other hand, even the best spec won't preclude a contractor from delivering a package that meets the spec without meeting your needs.

Specs are only as good as the shared sense of mission between the spec author and implementor. The specification for C specifies that certain behaviors are undefined. A compiler writer is free to reformat the user's hard disk when an undefined behavior is found in the source code. That's the compiler writer you don't want to hire because restoring the disk from backup will be a change order.

Good luck.