Claudia Landell, Cadence Design Systems, Inc.
In this article, I describe how one writing group at Cadence Design Systems made simple changes to support a more topic-based approach to documentation—without a topic-based authoring system.
Here at Cadence Design Systems, we listen to our customers through direct contact, periodic customer surveys, and our corporate problem reporting system. Based on customer feedback, our group identified three areas that we wanted to improve.
- We needed a better way to organize our documentation library.In a software release, we have as many as 120 user manuals. They are presented to the user in our Help system as an alphabetical list of titles. As you can imagine, it can be difficult to find an individual book in this list.
- We needed a way to reduce redundancy.We ship two technologies that are very similar. Each has approximately 1500 pages of content, much of which is duplicated in both sets of documents. This kind of redundancy is inefficient and error-prone.
- We needed a way to show or hide the documentation of specific features, based on the products that are present on the users’ system. We couldn’t use conditional text, because it isn’t dynamic. That is, determining what to show or hide had to be done dynamically at the customer site.
All of these problems could be solved with a topic-based system. However, in these hard economic times, we couldn’t go out and buy a new set of document authoring and delivery tools. We had to come up with a solution based on our current set of tools:
- FrameMaker is our authoring tool.
- The Electronic Document Management System (EDMS) renditions our books for HTML and PDF output and stores them in a documentation database.
- Cadence Help, developed in-house, is our online documentation viewer.
The same team that develops Cadence Help also maintains our corporate FrameMaker templates and writes extensions to FrameMaker and EDMS for creating and releasing documentation. Luckily, the Cadence Help development team was willing to work with us to support the features we needed, and Marketing helped us define the framework we would use.
Reorganizing Our Documentation Library
Our releases are made up of a set of technologies. Some technologies appear in all releases; some do not. The list of technologies and the releases in which they are shipped keeps changing. More importantly, the list keeps getting longer as more technologies are developed.
The Cadence Help system was originally designed to display an alphabetical list of all the documents in a release. As you can see in Figure 1, our library list didn’t fit in the Cadence Help window, and users had to scroll through the list to find a specific document.
To better organize the documents, we came up with the concept of a “group.” A group name is specified by the writer at the time the book is first checked into EDMS. It is stored in the HTML document as metadata. Books with the same group name are listed together in the Cadence Help window in alphabetical order under the name.
As you can see in Figure 2, the list of groups is much shorter than the list of documents. Users can more easily find the group they are interested in, then open it to find a specific book.
Also note the Known Problems and Solutions and What’s New groups. These groups gather together all known problems and all new features for all technologies in the release. Figure 3 shows the Known Problems and Solutions group when it is expanded.
Customers had been asking for such a document but producing it as a single, physical document was impractical. Grouping together documents of the same type gives users the access to this information that they were looking for.
Moving from Books to Modules
Solving the problem of the long library list created another. We had made the information one level deeper in the documentation hierarchy.
1. Opening a book to the table of contents
2. Opening the chapter or section of interest
Users had to
1. Open a group
2. Open a book to the table of contents
3. Open the chapter or section of interest
To fix this problem, we came up with the idea of “modules.” A module is more targeted than a conventional user guide or reference manual. Instead of describing every feature of a technology, it might describe one feature or a few related features. However, our EDMS system can’t handle anything smaller than a book. That is, all of our modules must have a table of contents and a title page, so that as far as FrameMaker and EDMS are concerned, they are “books.”
Modules make information more accessible by removing the extra level of hierarchy. With modules, users can
1. Open a group
2. Open the module of interest
In the process of defining modules, we focused on the following content issues:
- Chapters that were overly long
Some of our chapters had more than 100 pages. When it made sense to do so, we split them into smaller chapters and created a module containing those chapters.
- Information that was duplicated in another document or that could be shared with another technology
This information was turned into modules and assigned to all relevant groups.
Of course, not all books needed to be split into modules. Any book that is already self-contained, such as a tutorial, was not touched. We simply assigned those books to the appropriate group or groups and left the content alone.
Using Modules to Reduce Redundancy
We have two technologies that are similar, but have different customer bases. Although much of the information about these products is the same, we didn’t want to burden customers with information that wasn’t relevant to them. This goal caused a significant amount of redundancy across the two document sets.
The problems with this approach are not surprising:
- It doubles the effort to make a simple change—you must make the same change in two places.
- It is easy to forget to make the change in both places—information gets out of sync.
- It doubles the amount of space the documentation takes up on our system as well as the users’ system when both documents are installed.
Figure 4 shows the two original, non-modular documents, the VHDL Simulation User Guide and the Verilog Simulation User Guide. As you can see, the list of chapters is long and nearly identical in both books.
We were able to reduce redundancy by creating modules and assigning them to multiple groups. Figure 5 shows the modules we derived from the Verilog and VHDL User Guides.
The common modules, such as the Introduction to Simulation, appear in both groups. Modules that are unique to a technology, such as Compiling VHDL Source Files andCompiling Verilog Source Files, appear only in the groups to which they apply.
There is only one source file for any module, regardless of the number of groups to which it belongs. This makes the information easier to maintain and reduces the amount of space consumed by the information.
Using Modules to Share Information Among Technologies
We have one underlying technology, the SimVision Analysis Environment, which provides the graphical user interface for our other technologies. Some windows apply to all technologies, while others are specific to a single technology.
We wanted users to see documentation only for the features they are licensed to use. Therefore, rather than create one monolithic document that describes all features, we documented the unique features with the technologies that used them. This practice kept the information with the appropriate technologies but it also caused information to be fractured—there was no single place to find all of the information about SimVision.
For example, the Assertion Browser window is specific to Assertion-Based Verification. In past releases, the window was documented in the book called Assertion Checking in Simulation, shown in Figure 6. The Assertion Browser wasn’t mentioned at all in theSimVision User Guide.
By splitting the documentation into modules, we can display the technology-specific features of SimVision in the Assertion-Based Verification group and also in the SimVision Analysis Environment group, as shown in Figure 7.
Groups have made our information more accessible. Modules have made our information more flexible and reusable. As new technologies are introduced or new methodologies for using them are developed, we can create additional modules and put them into new groups or fit them into the current set of groups, as needed.
We made these changes using our existing set of tools because we felt that an evolutionary approach would work better for us. Had we moved to a topic-based authoring system all at once, we would have had to make sweeping changes across all of the documentation groups in the company. With an evolutionary approach, changes were implemented gradually, and our tools have evolved to satisfy our particular needs. As a result, we have not had to drastically change our internal processes for developing and delivering documentation. As we get feedback from our customers, other groups can consider making similar changes.