Embedded.com Tech Focus Newsletter (11-28-11): Documenting your embedded system design - Embedded.com

Embedded.com Tech Focus Newsletter (11-28-11): Documenting your embedded system design


Embedded Newsletter for 11-28-2011

» Click here to view online I » Forward to a friend I » Sign up for an EE Times Newsletter

Share this Newsletter:

facebook linkedin twitter digg

November 28, 2011

Tech Focus: Documenting your embedded system design


DITA and the death of technical documentation as we know it

The documentation challenge

What's worse: incorrect documentation, or none?

Editor's Note

Bernard Cole Bernard Cole
Site Editor

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


Embedded Books Reading Room
Bernard Cole's favorite links to book excerpts.


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.


What's worse: incorrect documentation, or none?

Good documentation is key to successful troubleshooting, but what about when it's not there?

The dumbing down of embedded design

If you believe the pundits, prepare to stuff Android into your next electronic toothbrush, but… .

Writing in software development

It's time we recognize that software development is mostly about writing, not coding.

An interview with James Grenning, Part 2

Is test driven development viable for embedded systems? It may be part of the answer. Ganssle continues to grill James Grenning on TDD.

XML – the embedded industry's not so secret weapon?

Because XML is at the heart of what is being called the 'embedded cloud,” and is in wide use in embedded development as a powerful data representation framework, there needs to be as much discussion of its strengths and weaknesses and how to deal with them as is now devoted to C or C++.

Sponsored White Papers

XML Basics

ASIC Documentation—Controlling Device Costs

Design Documentation with HDL Designer

Improve Project Success with Better Information

Agile Embedded Software Development

Requirements engineering for systems and software product lines

Courses and Webinars

Maximize Engineering Value by Automating PCB Documentation with BluePrint-PCB(R)

ESC SV-405- Agile Embedded Software Development

Manage and Track Requirements in Your FPGA/ASIC Design Flow

The Payoff of Driving Requirements Management Across Product Development


Around the Network Events

ESC Silicon Valley 2011: THE

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.