Your team (fellow software engineers, and perhaps test engineers) are your audience.
Assuming you are a software engineer (in a large US city on the West Coast, for example)1, and are asked to write a "design doc" for a software module before you implement it, to get approval from your team and present your idea to your team, what would you expect this document to look like? Does anyone have any actual examples of a real or representative design doc you can share?
My preference for a 500~2000 line code module with complicated architecture would be to write a bullet-paper ~2 pages in length, using plain English sentences and descriptions to logically lay out the design, including explanation of threading, mutexes, synchronization, state machine and states, program flow, etc. It would be declarative in nature:
[brief, high-level description goes here, then the program flow and logic, in plain English…]:
Use 2 event loops, each running from the same thread.
- The first loop will process X, Y and Z in a single callback, called at a period of 10ms.
- The 2nd loop will process W and be called at a period of 100ms.
- Note that no mutexes are required to pass values A, B, and C between these two independent event loops because they are using cooperative multi-tasking and running in a single thread…
Event Loop 1:
This loop will consist of a state machine since it needs to operate in an asynchronous manner without blocking. The states are:
- SEND_DATA_REQUEST – send a request over SPI to the GPS module to obtain a packet.
- WAIT_FOR_RESPONSE – delay exactly 100ms from the request, per the datasheet, before attempting to read back the data.
- READ_RESPONSE – read back the data over SPI, so long as it is ready. If we get back code 0x742 it means data is not ready, so return to WAIT_FOR_RESPONSE state with a new delay of 10ms until data is ready.
That’s the kind of style I’m talking about.
This has the advantage of being detailed enough that it avoids a lot of the back-and-forth and re-design that comes during the code review process otherwise, AFTER you’ve written the code and are trying to merge it, if you just got a diagram and brief, high-level description approved and then implemented a module based on that.
However, it has recently received a great deal of criticism for being "too detailed", "too implementation-specific", "too much to read", "not high-level enough to be understood outside the team," and "too much info. for the team members to want to go through it anyway." It has also been called "not a design doc at all."
However, I’ve been doing this pattern for 10 years for personal engineering projects of all sorts (not just software), and have had great personal success with it. So, I’m at a loss for what is "normal" for other people and I’d like to know what others do and are looking for in the industry.
1. I’m only mentioning this since culture and expectations can vary from location to location, even within a given industry