How to Write Embedded System Design Documentation?

Follow+Star public number, don’t miss wonderful content

Author | strongerHuang

WeChat Official Account | Embedded Column

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, sooner or later something will go wrong.This is not alarmism; there are many real-life examples.

1 What are the consequences of not writing documentation?

If you don’t write documentation, similar situations will arise during the development process.

Leader: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 causes N bugs, etc.

Hardware:Adding features can only be done by redrawing the board, did not consider leaving communication interfaces, etc.

Usually, it is normal not to write design documentation in small companies, but the hidden dangers are great.Repeatedly adding and deleting features, adjusting plans all require a lot of time and effort.

Just one or two small changes are fine, but if there are multiple, large changes, there will be consequences of blaming each other and colleagues not getting along.

Don’t ask why; those who have experienced it understand.

2 What design documents are needed for embedded projects?

In the projects I participated in before, from requirements, design, implementation, testing, to summary, there were more than 100 design documents at times.

Of course, this includes various documents that are subdivided by different positions (software, hardware, mechanical, testing, etc.) and different modules.

For different projects, the types and quantities of design documents may vary. For example, for a simple electronic watch, only a requirements document and a design document may be needed.

In fact, the more complex the project, the more design documents there are. For example, for JD’s warehousing and logistics system, can you imagine how many design documents there are? Just the documents in the requirements phase must be over a hundred: requirements, evaluations, reviews, etc.

Of course, for our ordinary projects, the required design documents may be a few to a dozen.

For example: requirements document, evaluation document, overall plan document, module plan document, communication protocol document, test case document, etc.

Each type of document does not have a fixed format; you just need to combine it with your actual project, clearly describe the key points, and guide developers to facilitate development and design.

3 Example: xxx Project Power Management Plan

Below is a simple design document.

1. Cover Overall

Like the cover of a book, listing the main information. For example:

Project name, document version, date, author, confidentiality level, etc.

For example:

2. Document Directory

As a technical developer, if you don’t even know how to generate a Word directory, you should reflect on yourself.

The directory is very simple, for example:

I want to say that the directory is automatically generated, not manually edited.

I found someone’s directory is actually manually edited; I don’t know if everyone is also so “shallow”?

3. Introduction

This introduction can also be “Overview”, describing the main content of the entire plan. For example, here are a few points:

4. Framework

The framework is to first give people an understanding of what your project has at first glance.

For example, system framework, software, hardware framework, etc. Here, some design framework tools are needed, such as: Visio.

For example:

5. Hardware Design

List the hardware-related design information, such as hardware power supply, status, etc.

6. Software Process

Involving software, a point that is indispensable in the plan is the software process.

If you don’t even understand the software process, during development, you will definitely modify the code repeatedly, even modifying dozens of versions that cannot be used.

There are many examples of software processes online that can be referenced, such as button detection process:

For example, voltage and current detection process:

7. System Status

Each system is basically made up of multiple states (or modes), such as working state, idle state, fault state, etc.

You need to list all the 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 protocol.

Or simply describe the communication-related content, such as hardware using UART, CAN, communication protocols using CANopen, Modbus, etc. Then specific protocol instructions in a separate document (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 ————

Reply in the background with『Embedded Software Design and Development』 to read more related articles.

Welcome to follow my public account, reply “Join Group” to join the technical exchange group according to the rules, reply “1024” to see more content.

Welcome to follow my video account:

Click “Read the original” to see more shares, and welcome to share, collect, like, and view.