原创 Agile-friendly documentation for embedded design

In this time of increased cost-cutting and bean-counting, documentation is usually the last thing that companies think about, despite the fact that is a critical element in any complex software or hardware design.

The pervasive nature of embedded systems designs in our lives means much greater attention must be paid to rigorous and—at least short-term—expensive methodologies such as Agile systems development, which very much depend on an Agile-friendly documentation development process.

In a recent article, James Grenning, one of the founding members of the Agile Alliance, pointed out that while in agile development working software is a more meaningful gauge of software development progress, that does not mean that there is no need for documentation. "Documents are often invaluable," he writes. "Those that are, must be produced. However, documentation is expensive to create and maintain so it is important to create only those documents you truly need."

During the development process documentation provides individual engineers a reminder of what's been done and what is left to be accomplished. For a design team it provides a global view of the state of the system at any particular time and allows each member to see the place their particular piece plays within the whole of the design. At the later stages during testing, it provides the means to compare the operation of the completed system to the original design goals. For the end users, it is a guide to operating the system correctly and most efficiently.

But despite the need for documentation in any development process focused on high quality and reliability, there are serious issues facing embedded developers as noted in several recent columns, including: "Incorrect documentation or none at all?" by Bill Schweber, and "Embedded design getting dumbed down," by Jack Gannsle.

In an article, "DITA and the death of technical documentation as we know it," Andrew J. Thomas suggests that the shift to a new documentation paradigm developed by IBM—called the Darwin Information Typing Architecture (DITA)—may resolve many of the problems faced by embedded developers.

Because of the importance of documentation in almost any hardware or software design, I would like to hear from you about the techniques and tools you have developed to assure complete and accurate documentation at all stages of development.What do you think about such things as DITA, as a solution to the problem? What alternatives are you considering?