Post History

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

[This answer](https://writing.stackexchange.com/a/42565/1993) 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?".

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

Original score: 5