Strategies for writing software design documents

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.

posted over 5 years ago

CC BY-SA 3.0

manduca‭

5 reputation 0 1 1 0

This answer provides a lot of good information. I want to augment it, not compete with it.

Over time, many organizations develop templates for various documents (design, functional spec, test plan, etc). Often they're derived from IEEE standards -- usually, in my experience, they're simplified from IEEE standards, which seem to be designed for large systems. It sounds like you don't have any institutional knowledge to draw on, but if you do have peers, it's worth asking to see some of theirs just for calibration within your own company.

The purposes of a software design document are to:

• explain what you're going to do (or did, if you're back-filling), and

• demonstrate that it is a complete solution to the problem you're trying to solve.

To do the latter, you need to actually state what the problem is that you're trying to solve. You might think it's obvious and will be obvious to your peers, but I have seen more than a few design reviews stall right there, when people in the room have different views of the requirements and overall goals.

Once you've stated the problem, you can cast the rest of the discussion in terms of addressing that problem -- we're using this architecture to meet our goals of extensibility, we're making this compromise because of this performance goal, we anticipate redoing this part next year when the new version of a key library is released so we're keeping it isolated in our system, and so on.

My usual outline for software design documents goes like this:

• Problem statement and key requirements: not the fine-grained, detailed requirements list that (if it exists) should be in a separate document owned by product management, but the key points from that list that affect how you design the software. Aim for a few paragraphs, not pages and pages. Don't just cut/paste them from somewhere; restate your understanding of them, because your understanding informs the design (so if it's wrong, better to catch it now).

• Functional specification, if not covered in a separate functional specification. This is where you describe externally-visible impacts -- user interface (and/or API), new configuration settings you're adding, performance contracts, etc. If your system is large or complicated, please do this separately and first to avoid rework later when somebody comes back and says "no, I need it to do this instead" or "that user interface is inconsistent with this other part of our system and you need to fix it" or "we already have too many configuration settings; are these ones necessary?".

  If you have a separate functional spec, I find it's useful to include a brief summary in the form of an example. People might need to refer to it when reading the design.

• The actual design specification: what are you creating, what are you changing, and why? What problems do you need to address (e.g. we need to address this technical debt before we can add this new thing), and what issues might your design introduce (e.g. this design places a higher load on the server; we think it's ok but we might need to do X to mitigate it). What risks does it introduce? The design should be detailed enough that somebody reviewing it could spot architectural or similar problems before you spend time implementing, but not so detailed that you have to write and comment all your code first before you can distill out a design spec.

• Testing strategy: how will you validate the work? Do you just need to run the regression suite because you're not making external changes, or will you create new functional tests, or what? This isn't a test plan, but thinking early about how you'll demonstrate that your eventual implementation is sound can help identify problems early.

posted over 5 years ago

CC BY-SA 4.0

Monica Cellio‭ staff

2514 reputation 51 268 361 110