Follow+Star Public Account Number, don’t miss the wonderful content
WeChat Public Account | strongerHuang
Recently, I saw a discussion in a group chat regarding the topic: Do embedded developers really need to write documentation?
To discuss this topic in depth, we may need to consider various situations such as company size, project difficulty, management systems…
Before sharing the main content, I’d like to recommend some embedded-related job positions:
As the saying goes, an engineer who cannot write documentation is not a good engineer!
If you can only write code and never write documentation, you might only be suitable for coding during lunch, because sooner or later, there will be “trouble”..
What are the consequences of not writing documentation?
If documentation is not written, similar situations may arise during the development process.
Leadership:This feature is not good, add another feature, remove this feature, etc.
Software:This feature cannot be implemented, the code can only be refactored, one bug leads to N bugs, etc.
Hardware:Adding features requires redesigning the board, failing to consider communication interface reservations, etc.
Usually, not writing design documents is quite common in small companies, but it poses significant risks.Repeatedly adding and removing features, adjusting plans require a lot of time and effort.
Just a few minor changes are manageable, but if there are multiple, major changes, it can lead to blame-shifting and discord among colleagues.
Don’t ask why; those who have experienced it understand
What design documents are needed for embedded projects?
In the projects I previously participated in, from requirements, design, implementation, testing, to summary, there could be over a hundred design documents.
Of course, this includes various documents segmented by different roles (software, hardware, mechanical, testing, etc.) and different modules.
For different projects, the types and quantities of design documents may vary. For instance, a simple electronic watch may only require a requirements document and a design document.
In fact, the more complex the project, the more design documents are needed. For example, can you imagine how many design documents are needed for JD’s warehousing and logistics system? Just the documents during the requirements phase would definitely exceed a hundred: requirements, evaluations, reviews, and various documents.
Of course, for our regular projects, the required design documents might range from a few to a dozen.
For example: requirements document, evaluation document, overall scheme document, module scheme document, communication protocol document, test case document, etc.
Each type of document does not have a fixed format; it just needs to clearly describe the key points based on your actual project, guiding developers and facilitating development and design.
Example: Power Management Plan for XXX Project
Below is a simple design document example.
Like the cover of a book, it lists the main information. For example:
Project Name, Document Version, Date, Author, Confidentiality Level, etc.
As a technical developer, if you don’t even know how to generate a table of contents in Word, you should reflect on yourself.
The directory is very simple, for example:
I want to mention that the directory should be auto-generated, not manually edited.
I’ve seen people whose directories are actually manually edited; I wonder if everyone is this “lazy”?
The introduction can also be an “overview”, describing the main content of the entire plan, such as listing a few key points:
The framework should allow someone to understand at first glance what the project entails.
For example, system framework, software, hardware framework, etc. Here, some design framework tools are needed, such as Visio.
List hardware-related design information, such as power supply, status, etc.
When it comes to software, one essential point in the plan is the software process.
If you are unclear about the software process, during development, you will definitely modify the code repeatedly, even modifying dozens of versions that are unusable.
There are many examples of software processes available online, such as key detection processes:
For example, voltage and current detection processes:
Every system generally consists of multiple states (or modes), such as operational state, idle state, fault state, etc.
You need to list all the possible states that the system may encounter and describe them clearly. For example:
8. Communication Protocol, Interface Design, and Others
For example, if your project involves communication, you need to organize the communication protocols.
Or simply describe communication-related content, such as hardware using UART, CAN, and communication protocols using CANopen, Modbus, etc. Specific protocol instructions can be documented separately (see: protocol document).
Finally, the above content is for reference only; different projects have different situations. Organize the important information that needs to be considered in the design according to the project situation, and make it easy to understand.
———— END ————
● Column “Embedded Tools”
● Column “Embedded Development”
● Column “Keil Tutorial”
● Selected Tutorials in Embedded Columns
Follow the public account Reply “Add Group” to join the technical group according to the rules, reply “1024” to see more content.
Click “Read Original” for more shares.
