Freescale Semiconductor Creates Usable Microchip Documentation for a Highly Technical Audience

Creating good, usable technical reference documentation can present real challenges. Writers typically work with source material that is complex, dense, and written from the viewpoint of the developer rather than the user.

At Freescale Semiconductor, Dr. Michael Tsurikov and other members of a Freescale Information Development team turned to The Method^™ by Information Mapping^® to re-write a reference guide for a complex component of Freescales’ microcontrollers.

Using the Method, they were able to re-think the content and structure of this key reference document, streamline their team-writing process, and dramatically improve the guide’s organization and effectiveness for users.

About Freescale Semiconductor
Freescale Semiconductor is a global leader in the production of microchips used in computers, mobile phones, automobiles, and many other products. Fujitsu, Motorola, Siemens and Hewlett-Packard are among its many customers. The chances are excellent that you’ve used at least one Freescale microchip today. Freescale’s products are cutting-edge and diverse, and the documentation accompanying them is often highly technical in nature, intended for use by engineers who incorporate Freescale microchips into their own systems.

Meet Dr. Michael Tsurikov
As an Information Developer with the Microcontroller Solutions Group at Freescale’s headquarters in Austin, TX, Dr. Michael Tsurikov is responsible for creating technical reference documentation for some of the company’s most complex products. Michael’s doctorate is in Aerospace Engineering, and he worked and taught in that field for several years before deciding to change careers. Noting that the code he developed as an aerospace engineer had often contained more written comments than actual code, Michael decided that he’d rather do writing than programming, and he became a member of Freescale’s technical writing staff in 2006.

“The Information Mapping method wasn’t being widely used when I started, but even then people were beginning to talk about it,” he said. “We felt that our documentation wasn’t meeting the needs of our customers. Our team received the training in 2007. Information Mapping instructor Sharon Paradero was outstanding—engaging, persuasive and committed to the Method. I was completely sold on this approach after the first day and a half of the training. It simply makes sense to think in terms of the Information Types and how to organize information.”

Return to Top

A test for the Method: a block guide for the 1²C module
To demonstrate the effectiveness of Information Mapping techniques, Michael’s Information Development team developed a block guide for the I²C module, which is a component embedded within many of Freescale’s microcontrollers. These modules are known as “blocks,” and the block guide is published as a chapter within the reference manual for each microcontroller. Problems common to block guides included poor organization, missing information, and duplicate or unnecessary information. Customers found them hard to navigate and difficult to use.

“We thought that the block guide would be especially challenging because it is a reference document and as such doesn’t contain procedures,” Michael explained. “There are just too many possible applications for us to be able to tell you how to do everything. We were concerned because prior to my team’s work, nobody at Freescale had seen an example of the Information Mapping method applied to pure reference content. But despite the non-procedural nature of the block guide, Sharon Paradero was invaluable in helping us apply the Method successfully.”

“Our source document was disorganized and contained all sorts of information mixed together, but our knowledge of the Information Types proved invaluable and helped us untangle it. And of course, since the Method is also about organizing information, we were able to significantly improve the document’s overall structure.”

Michael went on to say, “Another challenge we faced and solved involved creating a document with multiple authors. The Information Mapping method helped us work as a team. Sharon helped us arrive at common agreement on what the right Information Blocks would be, and then delegate them to members of the team. Melding them was completely seamless. This was very big for us.”

Return to Top

Example
The excerpt below is from the I²C block guide and demonstrates the effective use of Information Mapping concepts within Freescale’s documentation guidelines.

Return to Top

The new I²C block guide: Better organized, more complete, easier to navigate and use
Michael’s team maintains its documents in Adobe FrameMaker and Freescale mandates use of its own editorial and sequencing guidelines, so the finished block guide doesn’t have the same look and feel as “traditional” Information Mapping documents. Nevertheless, it has been an unqualified success.

“We presented our final document to top-level documentation team managers and shortly thereafter to the engineering community. It was very positively received, and has been successfully integrated into our product documentation.” Michael told us. He reported several improvements resulting from application of Information Mapping techniques, including

• better organization, with use of lists, tables, chunking and labeling of information
• removal of duplicate or unnecessary information
• addition of missing information
• clear identification of processes, and
• significantly easier navigation.

“We’ve gotten lots of positive feedback about the I²C block guide. The applications engineers who work with customers to help them use the device tell us that they are very pleased. Customers access this document regularly. It will probably remain in use for as long as Freescale sells devices with I²C’s in them.”

Return to Top

More applications for the Method at Freescale
Michael and other members of the Information Development team are now applying the Method to additional projects, including internal process documentation and training materials.

“We’re really just reaching the point where we can roll it out to truly benefit Freescale. Our department manager has been very eager to deploy the Method. We’re moving towards a single source documentation system using DITA XML and an intelligent content management system, and the Information Mapping method will be invaluable for us.”

As an organization that invests over $1 billion annually on research and development, Freescale is driven by innovation and change. There will be no shortage of new projects and new challenges for Michael and the Information Development team. We look forward to learning about their future successes using Information Mapping techniques.