Post History

Source: https://writers.stackexchange.com/a/42565
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

I personally like design documents that are short and fat-free.

- What are you trying to accomplish?
- What is your main idea and why?
- Main decisions
- Main challenges you encountered
- What will I - as newcomer to your project - find surprising?
- What are the 3 classes I should look at first?

To get into the mood:

- Imagine we are sitting and having a beer. You are telling me about your project. 
- Imagine you are giving a one-hour presentation about your project. What would you tell?
- Imagine I just downloaded your stuff off github. What do I absolutely have to know before I start looking at the code?

Keep it short and remember to update it once things change. Do NOT write a 100 page design doc. Nobody will read it and it will always be out of sync with the code. Do concisely comment every class and function and write your code in a self-evident manner (short functions with clear names, clear names for variables, etc.). Your design documents should be 3-page affairs. Major components can have their own design documents.

Original score: 5