How the multi-billion-dollar Intel FPGA company excelled after switching from traditional desktop publishing tools to DITA

From Framemaker® to DITA: How Altera Found Its
Documentation Solution in DITA XML and the MadCap Software's DITA CCMS solution.

Altera® Corporation is a $2B¹ a year semiconductor firm best known for their programmable logic devices that enable customers to create flexible computing solutions tailored to their needs. Established in 1983, Altera is based in Silicon Valley, California and employs more than 3,000 people in over 20 countries. Its customers include firms in the telecom, networking, medical device, broadcast, military, and automotive sectors². These companies use field-programmable gate arrays (FPGAs) built by Altera in the construction of their own products.

Altera and Intel® announced in June of 2015 that they had entered into an agreement where Intel would acquire Altera for $16.7B. The acquisition deal is likely to close before the end of the first quarter of 2016.

Altera Addresses Its Documentation Challenges

Altera heavily relies upon documentation to help sell its devices. It is critical then that their documentation is accurate, easily discoverable, and contains all up-to-date data in order for customers to know what to buy and how to properly integrate Altera components into their own products. The majority of people downloading documentation from the Altera website are design engineers who need to know the capabilities of an FPGA to determine whether or not it will work in the product they are creating.

The core 28-person Altera documentation team is global in scope with the majority of its technical writers based in San Jose, California. There are also seven translators who localize selected content into Japanese and Simplified Chinese, extending the reach of Altera into global markets.

Before moving to DITA, the documentation team at Altera was using traditional desktop publishing tools Adobe® FrameMaker® and RoboHelp®, to create HTML and PDF-based documentation for online delivery. The documentation itself was well written and accurate, but several user experience issues were causing concern. Customers expressed frustration when searching for information in their online documentation. Altera noted that part of the problem with PDF-based documentation was that the search engine truncated the text of the PDF during indexing, so users were not searching the full text of each document when looking for answers. A search query for a particular engineering or product term on the Altera website resulted in a return of dozens of files with no additional hints as to which one was correct.

The Altera team also realized that they were spending too much time formatting content, including, but not limited to, content within tables. This is a common issue within semiconductor firms, as many documents contain extensive table-based content detailing items such as the specific electrical, thermal or signal values for their components.

In addition to formatting tables, writers would also spend time adjusting the details of page breaks, text indentation, the space above and below text blocks, and straggling list items. While attention to formatting detail can enhance the appearance of a document, Altera believes that some of the time spent formatting would be better spent writing additional content.

An internal analysis of the documentation requirements at Altera revealed four major challenges necessary to address in order to better meet the needs of their customers:

• Search: improve search capabilities
• Scalability: document an increasing set of products with no expected increase in writer headcount
• Custom Documentation: meet increasing demands for more concise, specialized documentation—stemming from highly configurable product sets
• Publication Cycle: manage shorter time to market for documentation, and be nimbler when correcting or updating existing documentation

DITA XML As Part of the Solution

In search of possible solutions, Sergio Brizuela, Technical Communications Manager at Altera, attended the Intelligent Content Conference (ICC) in 2011. It was there that he discovered many other firms were also facing the same issues and were successfully tackling them by using DITA XML. It became clear that DITA could address many of his team’s documentation issues.

The DITA-related presentations at ICC convinced Sergio that DITA could help with the following:

• Improve user experience with enhanced search by delivering more HTML content with better metadata
• Achieve efficiencies through content reuse, enabling each writer to produce more
• Create more concise documentation better tailored to customer needs with DITA Topics
• Shorten publication cycles by using DITA combined with a component content management system (CCMS)

Sergio was under no illusions that moving his documentation team to DITA would involve some significant expenses and change management. But after crunching the numbers, his business plan clearly showed the savings they could expect at Altera by implementing DITA XML along with a CCMS to support it. Sergio hired Information Architect Severin Foreman to help guide the DITA implementation, and selected Comtech Services to do training workshops on minimalist writing techniques for his documentation team.

Choosing MadCap Software's DITA CCMS solution After switching to the DITA standard, Altera knew it needed to work with a CCMS to further optimize its documentation process. They went through a rigorous, yearlong process to decide which DITA CCMS would best fit their needs. Altera formally reviewed all of the DITA-capable solutions on the market and actively demoed a shortlist of preferred vendors, which included IXIASOFT. Altera chose MadCap Software's DITA CCMS solution based on the following deciding factors:

• Best-of-breed approach
• DITA authoring within an integrated system
• Robust search capabilities and workflow

The Benefits of the Best-of-Breed Approach

The MadCap Software's DITA CCMS solution offers a complete CCMS with a best-of-breed approach to complement its solution. As such, customers are free to choose the ancillary tools that work best for them instead of being forced to use a single suite-based solution whose components may not be the best the industry has to offer. To complement their DITA CMS, Altera chose industry-leading XML editor, oXygen XML (SyncRO Soft) for authoring, DITAweb (Mekon) for dynamic delivery, and Adobe® CQ as their website management solution.

Single, Unified DITA Interface

Another key feature of MadCap Software's DITA CCMS solution for Altera’s content creators was the single user interface it provides for all DITA interactions. DITA CMS provides a fully integrated system for working on all DITA-related items—from authoring and searching for content, to managing workflow and producing output.

Many other CMSes provide a fractured user experience for writers with plug-ins working in separate, stand-alone programs. This makes it challenging for users to keep an eye on where DITA topics are in the workflow—a less-than-ideal working environment. For Sergio, the integrated DITA CMS interface “was one of the key deciding factors that tilted us in favor of IXIA CCMS over other solutions.”

Robust Search and Workflow

The robust search and workflow features built within MadCap Software's DITA CCMS solution was yet another critical aspect for Altera. The instantaneous and extensive search capabilities of the system means that content creators can find what they are looking for quickly and easily. Using DITA CMS, content creators can track who had previously worked with a file, see in which documents a topic is already used, and know whether or not a subject matter expert (SME) has approved a topic for release.

How DITA CMS Has Improved Things At Altera

While Altera is still in the early days of their DITA-based documentation implementation, they are already beginning to meet their goals, including:

• Improved user experience with enhanced online search capabilities thanks to delivering more content as HTML with descriptive metadata
• Increased number of publications attributed to effective content reuse
• Concentrated efforts on creating new content and documentation that is more customer-focused
• Nimbler and more reliable documentation processes, as content creators can quickly respond to feedback and optimized workflow ensures content is validated before its release

Proven Content Reuse

One of the reasons for the switch at Altera to structured, DITA-based documentation was to improve writer efficiency and produce more concise, consistent documentation for their users. Thanks to its modular nature, it is easy to measure DITA topic content production and content reuse. Tracking content reuse is straightforward with MadCap Software's DITA CCMS solution, which comes with powerful, built-in query tools. Query results can be exported and analyzed using a spreadsheet program, such as Microsoft® Excel, or analyzed more in-depth by using the open-source Business Intelligence Reporting Tool (BIRT).

Based on a content reuse formula³ devised by Dr. Bill Hackos, Co-Founder and Vice President of Comtech Services, Altera determined that they are getting roughly 130% content reuse for the content in their device handbooks⁴, with slightly lower reuse percentages on their other technical content.

These results at Altera show that a significant portion of content is being reused effectively, resulting in more reliable documentation for their users. Content reuse also reduces the workload for content creators, who no longer have to re-write the same content, and can concentrate on producing more focused content for users. Altera is clearly on the right track for an effective and efficient DITA CMS deployment. Other benefits beginning to appear with DITA CMS include:

• Decreased support burden for Altera field engineers as a result of better documentation
• Improved consistency on account of more content reuse (errors only need to be fixed once)
• Increased efficiency thanks to the possibility of future integration with other systems

While MadCap Software's DITA CCMS solution was clearly the right choice for Altera from a technical standpoint, there was more to it than that.

¹ Altera, “Altera Corporation 2014 Annual Report (Form 10-K)”, Altera, Annual Reports, 18th November 2015, <investor.altera.com>.

² Altera, “Who are Altera’s customers?”, Altera, Frequent Questions, #4, 18th November 2015, <investor.altera.com>.

³ Dr. Bill Hackos, ‘What is the Best Metric to Measure the Success of Your Reuse of DITA Topics?‘, CIDM Information Management News, Volume 8, Issue 6 (June 2008). Available from www.infomanagementcenter.com.

⁴ Severin Foreman, and Sergio Brizuela, ‘How DITA Transformed Content Delivery at Altera: One Company’s Journey’, slide 17 (presentation, DITA North America, Chicago, IL, April 20-22, 2015).