
Ask HN: Best practices for writing a design document? - hood_syntax
I&#x27;m in the brainstorming phase for a personal project that I will likely open source at some point. I want to write a document to capture the guiding philosophy and high level design behind it. Any recommendations for resources that could help me do it right from the beginning?
======
itamarst
Let me tell you all the things I haven't written down yet, and really really
should some time. Maybe I'll turn this into a blog post if anyone cares:

1\. "Design document" is ambiguous: some people use that to mean the
specification, i.e. design as a noun. I tend to want to use the document to
think through issues, so design as a verb. Just so you know my starting point.

2\. You want to write down goals. And non-goals. Non-goals are just as
important, if not more so.

3\. You want to write down who the actors are and what their use case is. "As
a monkey I want to use this app to acquire delicious delicious bananas." Give
each use case a name, e.g. MONKEY-BANANA.

4\. You want to write down all your other requirements that aren't use cases.
Give them names too, like ETHICAL-BANANA-ACQUISITION or whatever.

5\. Make a list of possible solutions. Write all the solutions down. The good
ones and the bad ones, don't think about it just write write write write. Then
add some more (what if you didn't write any code? What if you had to ship in
48 hours? what if you had 2 billion dollars to throw at the problem). Your
goal is to maximize the solution space you're covering so you don't get stuck
at a local maxima. You want global maxima.

6\. For each solution, write down how it does on use cases, requirements,
goals.

7\. Go back and see if you can throw out any of your goal, use cases,
requirements. Maybe a non-goal actually is a goal?

8\. Do step 6 again.

9\. Choose the best solution, document why you chose it.

Now all you have to do is implement the solution. Easy peasy!

