Documentation is important. It allows developers and others to communicate with each other on a project. It aids in anything from onboarding new team members to work that may occur long after the initial project, communicating across time. Yes, it takes time and effort. That’s part of real engineering. It’s an investment that yields many valuable returns.
Diagrams Communicate System Architecture Quickly
Here’s an example of a typical IoT (Internet of Things) system architecture. This is a context diagram that conveys a variety of high-level architectural details. From here, you can dive into various parts of the system in more detail.
As the adage says, a picture is worth a thousand words. Diagrams provide a high level of information abstraction.
This picture avoids having to write and maintain lots of text description. It can benefit from some explanatory text, but the diagram does the heavy lifting of informing the reader.
One of the tenets of D5’s Modern Embedded development approach is Emergent, Intentional Architecture:
Architecture matching the inherent problem to be solved, evolved and documented as the project evolves.
The documented part can be challenging for a number of reasons:
- The system changes.
- Documentation is time-consuming.
- Effective documentation tools are expensive or difficult to use.
- Documents are stored separately from code, so people lose track of them.
This often results in documentation becoming stale or abandoned, or being avoided altogether.
Documentation is important. It allows developers and others to communicate with each other on a project. It aids in onboarding new team members. It aids work that may occur long after the initial project, communicating across time.
Yes, it takes time and effort. That’s part of real engineering. It’s an investment that yields many valuable returns.
While it’s often a dreaded practice, documentation can take the time to digest some information about your system from days or weeks down to just a few days or even hours! Complex systems take time to assimilate and digest. Forearming people with knowledge is a super power which will help to speed up that process.
What are the costs of poor or missing documentation? What are the effects on the project schedule? What are the consequences to the company and the world at large of errors and omissions due to poor understanding? For embedded systems that control physical systems, they can be far more severe than just a product that doesn’t work well. They can ruin people’s lives.
Well how much documentation should I produce? If I spend too much time working on it, there’s no time left to get implementation work done! Well, somewhere between zero and too much is the sweet spot for the right amount of documentation for a system. It’s important to balance the needs of development, quality, cost, and effort.
An Effective Documentation Tool
There are a number of tools available. Each has its pros and cons. One that is very effective is AsciiDoctor combined with VS Code via the AsciiDoc extension.
What makes this effective?
- It’s a lightweight toolset, freely available.
- It combines diagrams and textual information in a structured form.
- It provides a variety of standardized diagrams along with custom diagrams.
- It’s easy and fast to use, with live previewing similar to a WYSIWYG editor and diagramming tool.
- The input format is text files similar to Markdown, so raw documentation can be stored in-repo right with the code.
- The output format is an HTML file, so documentation can be published for easy browsing or exporting as PDF.
- While the default configuration depends on remote servers to generate diagrams, local server instances can be used, removing that dependency.
The main con is that it requires document generation to be performed in VS Code.
Text And Diagrams
AsciiDoctor allows you to create documentation with a mix of text and diagrams. It provides document structure for organization.
This allows you to create an architecture documentation package that provides a guided tour of the system, relying primarily on diagrams supplemented by text.
Start with the high-level diagrams like the context diagram above, and provide progressively more detailed diagrams of different types that show static and dynamic attributes of the system, digging into the details.
Eventually, the source code is the full elaboration of all the details. But the documentation provides a guide through it, a map of that complexity at various zoom levels. That allows readers to pick which areas to focus on, while still having some concept of what the other areas do.
Informed readers are able to work with the code more effectively. This saves time that would otherwise be spent puzzling through the code to figure it out. Time that would be filled with all kinds of risks for confusion, misinterpretation, and mistakes.
Diagram Types
AsciiDoctor supports two general types of diagrams that are useful for documenting system architecture:
- – DITAA (DIagrams Through Ascii Art) is a text format that allows the creation of free-form custom diagrams.
- – PlantUML is a UML (Unified Modeling Language) diagram generator. It uses a simple text format that allows the creation of a number of standard UML diagrams.
DITAA diagrams are more literal in that the text lays out the diagram elements exactly; the diagram is a direct graphic rendering of the text. PlantUML is more symbolic, using a simple language that specifies the diagram elements; these are translated to graphic elements that are laid out and rendered automatically.
This means that PlantUML is easier to use for generating standardized diagrams, while DITAA offers more flexibility to create non-standard diagrams. They provide a powerful combination for conveying system information.
DITAA Diagrams
DITAA allows creation of simple custom diagrams. The context diagram above is an example. It’s deliberately overly colorful to illustrate the range of colors that DITAA provides.
For details on using colors in DITAA diagrams, see DITAA Color Codes For Diagrams.
System layer diagrams are another common type of diagram. Here’s an example of a typical system with 3 types of layers indicated by color codes:
- Gold: application layers. This contains the application-specific code and various supporting modules.
- Green: abstraction layers. The OSAL (Operating System Abstraction Layer) and HAL (Hardware Abstraction Layer) provide generic drivers and API’s that abstract the services of the specific RTOS and vendor libraries, isolating the application layers from them.
- Blue: platform-specific layers. These are the specific RTOS and vendor software for the platform, which could be swapped out for different ones for a different platform (along with different abstraction layers that abstracted their services for use by the application layers).
Here’s the DITAA text for the diagrams, showing the literal layout of the diagram elements:
PlantUML Diagrams
PlantUML supports these standard UML diagrams:
- Class diagram
- Object diagram
- Component diagram
- Deployment diagram
- Activity diagram
- Sequence diagram
- State diagram
- Timing diagram
Like DITAA, PlantUML diagrams can use colors. There are several ways to specify them. For the different methods, including a chart of named colors, see PlantUML Colors.
Here are two sequence diagrams that extend the example above, showing the user turning on the device’s motor via remote app and getting the resulting speed.
The first shows the overall sequence of events:
The second shows the detailed sequence within the device, including lifelines to denote participant activation:
Readers can glean a lot of information from these, then discuss the design intelligently, perhaps proposing changes. Here’s the PlantUML text for them, showing the symbolic specification of the diagram elements:
You can create a variety of diagrams at whatever level of detail you feel is appropriate. These can cover things like data structures and their relationships, code activity, thread activity, and signal timing.
You might want to go deep on some things and stay high level on others. Remember that the goal is effective communication.
You can segment and break up diagrams to manage their complexity. That might guide you in structuring the code. If the diagram looks out of control, what does that say about the code?
The tools make it simple to create well-defined diagrams that are relatively easy to maintain. You can concentrate on the system technical details without having to worry about the picture details.
Summary
Use diagrams to communicate system architecture effectively. AsciiDoctor with the VS Code AsciiDoc is an effective, lightweight tool for creating documentation with diagrams.
Next Steps
Dojo Five can help you with architecture documentation. We bring modern tools, techniques, best practices, and leading-edge innovations in firmware to our customers-helping them build successful products and successful clients.
