In general, software developers don’t like generating documentation. This dislike was codified in the Agile Manifesto which prefers “Working software over comprehensive documentation”. Outside of regulated industries, the trend in the embedded software space seems to be that documentation is a waste of time. While I agree that excessive documentation is not a net positive for a project, the other extreme, where “source code is the documentation,” is a net negative. Documentation should be viewed as a tool; it is more than just a record of what was designed and implemented. Documentation adds values by

• Providing a canonical reference.
• Providing a higher level of abstraction for identifying, analyzing, and specifying solutions.
• Providing a concrete medium for reviews.
• Being easier and faster to rework than source code.
• Bridging the gap between individuals and disciplines.
• Providing training and onboarding materials.
• Providing the basis for end user and support documentation.

So what is the Goldilocks amount of documentation for an embedded project? It depends. Asking the question differently, then, what should be documented? Here is my recommended minimum list of items that should be documented for project.

• Software development plan (SDP). A software development plan captures the details of the development process that the software team will follow. For example, it specifies what SCM and bug tracking systems will be used, the SCM branching conventions, how code reviews will be handled, and so on. By definition, the SDP should be one of the first documents created. Said another way, the SDP documents the explicit decisions that have been made about how the software will be developed before you start the development.
• Software architecture (SA). What is software architecture? To quote Ralph Johnson: “Architecture is about the important stuff. Whatever that is.”  It consists of the important design decisions that shape the system.  And yes, software architecture is different/separate from detailed design. By definition, the software architecture must be completed before the design and implementation begin.
• Software detailed design (SDD). The SDD is the “how” and bridges the gaps between software requirements and software architecture and the source code. Assuming the software architecture has been defined, the detailed design can be done just-in-time or on an agile story basis.
• Best practices. If your organization has its own best practices with respect to software development, these practices need to be articulated and documented for the software team. Undocumented best practices are at best company culture and at worst individual preference.
• Source code. Everyone will agree that the source code needs to be documented. My best practice for this is to fully document all public interfaces (e.g., the semantics, thread safety requirements, example usage, etc.). In other words, the documentation for public interfaces should read like hardware data sheets for an integrated circuit or a man page in Linux or Unix. The reason is because with a highly decoupled design and implementation, the consumer of an interface does not necessarily know where to find the source files (i.e., the .c or .cpp files) that implement the interface in order to see the missing details.

Depending on the organization or industry you are in, documentation templates, formats, and document control processes can be largely dictated to the software team. If the software team has latitude in defining its documentation process, my recommendation is to focus on content over formatting. Trying to put together a formal Word document with a title page, executive summary, table of contents, headers, footers, references, glossary, actual content, change log, appendices, and so on can be exhausting. An alternative is to create a Wiki (or similar tool) page entry that just contains the actual content. You can then tag the entry or create links to it, so the entry can be found. An example of this is the top/start_here.html page in the PIM GitHub repository. The start_here.html file is a TiddlyWiki file, which is essentially a self-contained Wiki-Server-with-content in a single HTML file.

Document First, Then Implement

As a rule, software developers are documentation averse. Perhaps it’s just human nature. But this tendency often leads to the anti-best practice of generating documentation after the coding has been completed. This anti-best practice is widespread across the entire development process from architecture and design to comments in the source code. While this approach may satisfy a project’s deliverables and bring your work in line with a formal development process, it takes longer than if the documentation was done before the implementation. In fact, it negates much of the value add of creating documentation. Generating documentation is a tool for problem solving—that is, it is a tool for figuring “stuff” out before writing code. This applies to formal architecture and design documents as well as comments in the source code.