Follow+Star Public Account, don’t miss out on wonderful content
Author | strongerHuang
WeChat Official Account | strongerHuang
Writing documentation is “difficult” for embedded engineers, especially when a project has dozens of documents to write.
So, when you develop embedded projects, do you write documentation? How many documents do you usually write? What types of documents?
Do embedded projects really need documentation?
Some companies do an embedded project without a single document, relying entirely on verbal communication. In contrast, some companies have hundreds of documents for an embedded project.
I have worked on projects with zero documentation and also on projects with fifty or sixty documents (of course, not all were written by me, I only wrote a few).
You will find that whether or not to write documentation for embedded projects is related to the company’s nature, management, project size, etc.
Generally speaking, small companies lack personnel and have poor management, so they do not value documentation. In contrast, large companies have strict standards regardless of project size, and they will not miss any necessary documents, even if the content is minimal.
What documents are needed for embedded projects?
Strictly speaking, an embedded project without documentation is not a good project.
Why do I say this? I believe many readers have taken over “bad projects”, like the one I shared a few days ago titled “What are the drawbacks of having too many global variables in a microcontroller project?“. In fact, many bad projects have part of the reason due to lack of documentation.
So, from the developer’s perspective, have you considered what necessary documents there are? Here are some to share.
1. Requirements Document
The requirements document is crucial; all subsequent research and development work is based on the requirements. It details the functional requirements, performance requirements, interface requirements, etc., of the embedded system. It also helps ensure that the development team maintains a consistent understanding of the project and serves as the basis for subsequent design and development work.
The requirements document aims to determine the specific goals, functional requirements, and performance indicators of the project. It analyzes the complexity and feasibility of the project and ensures that the selected microcontroller and various components can meet the requirements.
If the company has many staff and subdivided work, there should be multiple requirements documents.
2. Design Document
The design document includes structural design documents, hardware design documents, software design documents, etc.
The structural design document contains content such as structural dimensions, size, appearance, etc.; the hardware design document describes the hardware architecture, circuit board design, component selection, etc., of the embedded system; the software design document involves software architecture, module division, interface definition, etc.
These documents help team members understand the overall structure of the system and the functions of each part.
3. Development Document
This development document, also known as implementation documentation, should be the most written by developers, mainly detailing and recording the specific implementation process of the embedded system, including source code, header files, library files, etc.
These documents are crucial for subsequent code maintenance and upgrades, and they also facilitate code sharing and collaboration among team members.
You will find that sometimes there are situations where software and hardware blame each other.
4. Testing Document
The testing document includes the testing plan, test cases, testing reports, etc.
It describes the process, results, and problem analysis of the tests in detail, helping to ensure the quality and stability of the embedded system.
You can refer to my previous sharing titled “How to write test cases in embedded development?“
5. Maintenance Document
In our software and hardware development process, as well as subsequent updates, there are different versions. The maintenance document mainly records the maintenance process of the embedded system, common problems, and solutions, helping to ensure the long-term stable operation of the system and troubleshooting.
6. Other Documents
The above are some necessary documents that are commonly written in embedded projects. In larger companies, there might be other documents, such as summary documents, deployment documents, user manuals, etc.
Summary
The above is just a “big framework”; how to implement it specifically is related to company management, projects, and various factors, but one principle is to clearly describe the main content of the documentation.
Writing documentation may be something engineers dislike, but from the long-term perspective of the project, or from the perspective of long-term career development, writing documentation is still very necessary.
