
Ask HN: How do I learn to write good software specifications? - ciaoben
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?
======
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.

------
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.

------
machtesh
The best guide in my opinion:
[https://www.joelonsoftware.com/2000/10/02/painless-
functiona...](https://www.joelonsoftware.com/2000/10/02/painless-functional-
specifications-part-1-why-bother/)

