|
Tech Focus: Documenting your embedded system design
HIGHLIGHTS
DITA and the death of technical documentation as we know it
The documentation challenge
What's worse: incorrect documentation, or none?
Editor's Note
In these days of aggressive cost-cutting and bean-counting, documentation is often the last thing that companies think about, despite the fact that is a critical element in any complex software or hardware design. During the development process it 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.
The serious documentation issues facing embedded developers are noted in several recent columns on Embedded.com, including: “What's worse: incorrect documentation or none?” by Bill Schweber, and “The dumbing down of embedded design , ” by Jack Gannsle. Recent articles on the role of documentation in embedded hardware and software development include:
The documentation challenge
Making hardware specifications “firmware friendly”
Software development – a lot more than coding
Dissecting the requirements document
In my Editor's Top Pick , “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.
Design How-Tos
DITA and the death of technical documentation as we know it
Faced with growing complexity of hardware and software designs and the demand for lower cost delivery of the final product with as high a reliability as is possible, companies need to consider structure content based documentation strategies using the Darwin Information Typing Architecture (DITA)
Using requirements planning in embedded systems design: Part 1 – Dissecting the requirements document
In this six part tutorial, Keith Curtis takes you step by step through development of an embedded systems design requirements document for a seven digit electronic alarm clock. Part 1: Dissecting the requirements document.
PRODUCT HOW-TO: Software development – a lot more than coding
Here's how integrating graphical UML editors such as Atollic TrueSTUDIO into the C/C++ environment can provide developers better possibilities for requirements capture, and to model the static structure as well as dynamic behavior of the application.
Use XML to build ASIC or SoC design specifications
Here's a step-by-step guide to building an ASIC/SoC hardware specification using the Web's Extensible Markup Language (XML).
Introduction to XML for engineering applications
Mathsoft CTO Allen Razdow provides a quick overview of the eXtensible Markup Language (XML), and shows how its ability to manage calculations can benefit engineering teams.
XML: Pros and Cons
XML's biggest advantage is that it provides developers with a tool that concisely and unambiguously defines the format of data records.
Agile embedded software development
Developers flee engineering for marketing and management. Why? Big processes are not delivering, and neither is coding chaos. This author says Agile helps address the problems of late projects, high defect levels, and stressed teams.
Making hardware specifications 'firmware friendly'
Firmware engineers and systems board designers face huge learning curves as they design and control systems that are increasingly complex, requiring dependence of some form of documentation methodology to carefully assess design options.
The documentation challenge
This article will cover the importance of good product documentation, what some of the hurdles are in creating it, and provide a few suggestions for producing quality documentation.
Tips on building & debugging embedded designs: Part 1
In a two part series, Jack Ganssle, editor of “Embedded Systems: World Class Designs,” passes on some tips about embedded systems design gained from his experiences as both a designer and a manager of hardware and software projects.
Embedded Systems Bookshelf
Excerpts
Embedded Books Reading Room
Bernard Cole's favorite links to book excerpts.
Reviews
Engineer's Bookshelf
Airport fiction blows. A look at books other engineers are reading and why you should read them, too. Recommend and write a review yourself. E-mail Brian Fuller.
Jack Ganssle's Bookshelf
A list of book reviews by Jack Ganssle, contributing technical editor of Embedded Systems Design and Embedded.com.
Max's Cool Beans
Clive “Max” Maxfield, the editor on Programmable Logic DesignLine, often writes about interesting books.
|
