Ask HN: Best practices for writing a design document?
I'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?
1 comment
[ 4.7 ms ] story [ 9.0 ms ] thread1. "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!