Building an Electronic Document-Management System at Cadence

Home/Publications/Best Practices Newsletter/2002 – Best Practices Newsletter/Building an Electronic Document-Management System at Cadence

CIDM

February 2002


Building an Electronic Document-Management System at Cadence


CIDMIconNewsletter Amy Witherow, Sr. Technical Publications Director, Cadence Design Systems, Inc.

The problem
In 1998, Cadence began releasing its CAE design software to customers in suites of products targeted specifically to the product areas customers used. These product suites were released more frequently than in earlier release models in which all software was released at the same time as one complete package. The Knowledge Transfer Organization (KTO), which produces nearly all of the information that ships with the product, was faced with an increasing number of documentation releases. Because software products were being mixed and matched to create unique suites, documentation also had to be flexible enough to be mixed and matched. Between 1996 and 1999, the number of releases grew from two a year to an average of forty-five per year. Without knowing the impact, the company had enforced a model in which writers had to find out if their products were shipping in any particular release and what version was required for that release. Then, they had to physically transfer the files for the appropriate release to a server for production, which meant that some files were reused many times for different product suites. Manually tracking the documentation and its relationship to the product suite wasted an incredible amount of writing time when resources remained unchanged.

releases29

At the same time, the number of books produced for releases each year also increased.

books43

In addition, no central repository of information existed for all documentation source files. Writers worked on the source files at their workstations and were responsible for backing up their systems and their source files. So when a writer left the company, it was often quite a task to find the correct version of a document to put into a release. And if the backups failed, it meant recreating whole documents.

Finally, because Cadence is a company built from mergers and acquisitions, each new publications group had its own spin on the process to release documentation to customers. Therefore, the number of processes we used to create documentation increased.

processes44

The vision
In August 1998, the vision of the KTO managers was to build a technical information system in which the customer could

  • receive documentation specific to their implementation, which is installed with the software
  • find up-to-date documentation for products from the Web
  • access documentation easily across all platforms
  • augment the documentation with their own information

This vision required making two major changes:

  • building a document-management system to deliver information to customers that was standardized across publication groups, automated production tasks, let us deliver several types of output to several systems, and let us manage our source files
  • moving to a non-proprietary documentation delivery system that let users view documentation for the products they purchased (not all documentation in a release) and build a list of available documentation on-the-fly

Because the KTO organization at Cadence has the unique advantage of having a development organization within the publications group, we could work on the solutions to our problems and our vision in-house.

We created the new information delivery system first for two reasons. We felt that the architecture of the system would drive other decisions about processes, and we had in-house resources to tackle this project; we didn’t need to create a business plan and ROI models for justifying large purchases of outside tools.

Creating the Information Delivery System

The new information delivery system was to be Web-based, letting users view the product documentation on their Web browser of choice. The documentation was to be installed on the client computer when the product suite was installed from the CD-ROM. Documents would be delivered in HTML and in PDF files suitable for print. The system also included a Java applet to let users choose which document to view.

To support the system, we added metatags to HTML files to allow for the dynamic display of documentation titles by product, document type, or product group. In 2000 alone, we calculated savings of $570,000 by eliminating the manual creation and testing of online menus for each product release. The menus permit users to find relevant documents in the electronic library. By navigating from menus with high-level tasks or menus with product names, users can find documents associated with the subject matter in which they are interested.

We also defined the kinds of processing that would occur on the FrameMaker source files to allow them to be converted to files ready for delivery.

Building the Electronic Document-Management System (EDMS)

While the developers were working on the delivery system, a project team was writing the requirements for the document-management system and evaluating tools. We needed a system that

  • interfaced with FrameMaker on the UNIX platform
  • allowed us to continue authoring in our current environment (FrameMaker on UNIX)
  • provided an easy way for writers to check documents into a source control system and version them
  • automatically created HTML and PDF output files (sometimes in several flavors)
  • let the writers create deliverable “kits,” or installable software packages, for their files that could be used in any release in which the documentation was needed

Delivering documents into releases in a more automated way would save us 10 percent of the writers’ time and the work of about 1.5 project coordinators, for an annualized savings of $1,610,000. Although we did not justify the project using savings we would gain from not losing source files because we didn’t have quantitative figures on what this problem cost, we feel that we have also gained efficiency in this respect.

For documentation source control, we looked at Intra.doc!, Livelink, Domino.doc, and Documentum. We chose Documentum because of its leadership position in the field, its history of supporting UNIX, its ability to handle almost any kind of file imaginable, its ability to break tagged documents automatically into smaller components, and the ability to use its API to create our own tools that interface with the content-management system.

For processing our files from FrameMaker to HTML, we chose Quadralay WebWorks. Although we could have used the internal capabilities of FrameMaker for production, we sought a more automated approach.
WebWorks processes files from the command line, which allowed us to produce deliverables without writer intervention.

Initial implementation
For the initial phase of the project, we wrote detailed specifications of what we wanted to build. We hired a Documentum consultant to guide and train our own engineers on the project and build a system that

  • handled the quantity and types of files we needed to check in
  • kept the source for all KTO documentation in one system, allowing us to find information easily
  • gave the writers a graphical user interface within their FrameMaker authoring tool for all database actions, such as check-in and check-out
  • verified file requirements at check-in and reported errors to writers
  • captured meta information about each document and the related revision of the product
  • captured versions of documents for each revision of the project
  • created output files labeled for either draft or production delivery based on input from the writer
  • let the writers review the HTML files before the files were delivered into a release
  • automatically created output files for several delivery systems
  • created a mapping file that showed what books were associated with each release of the product, allowing configuration management (the group responsible for ensuring that the correct software was packaged in the correct software suite) to put the correct documentation in each release

In designing the new documentation release model, we discovered new input requirements, which were mainly an outgrowth of the way WebWorks converted FrameMaker files into HTML. For example, we found that although you could insert a graphic anchor in FrameMaker and specify that a graphic appear at the bottom or top of a page, you could not do this in HTML because pages cease to exist, and graphics would be inserted where the anchor had been inserted in the FrameMaker document. These requirements were thoroughly investigated, documented, and rolled out to the writers before the new system was in place. The system then checked the input files for requirements and informed the writers when the requirements weren’t met.

We mapped our FrameMaker files to HTML using WebWorks and built filters that both converted the documentation to HTML and added header/footer navigation to each file.

The figure below is a high-level picture of how the EDMS at Cadence works.

BPFebruary0231

Project tasks for developing the system included

  • defining issues and needs
  • investigating tools
  • writing and presenting a project proposal and justification
  • managing a budget
  • negotiating tool and hardware purchases
  • learning new tools
  • writing a technical project plan and passing on tool knowledge
  • hiring and managing consultants
  • installing hardware and tools
  • developing functionality
  • testing functionality and making modifications
  • performing a front-to-back test
  • writing training, support information, and online help for the EDMS
  • training pilot users, getting feedback, making modifications

Because we had thoroughly defined what we needed and had engineers on site who had a long-term relationship with the technical writing organization, we were able to move from project approval and tool purchases to being ready to go live in about eight months. Another critical area for being able to deliver so quickly was an agreed-upon use model for the new system that fit writers’ needs. When we rolled out the system to writers, they embraced it. One writer says “I’m generating HTML and checking in files and am amazed at how easy and robust the EDMS/tarkit system has become! I am having absolutely no problems at all, and it is a real time saver. The HTML and PDF output looks great, and the push-button GUI is fantastic.”

Benefits of using the system include

  • Managed source, with version control, no matter who the author is.No more lost source files.
  • Time savings for managing documents by automatically generating reports, including an automatically updated list of documents, who owns them, what release they are for, and what state they are in.Previously, this information was created by hand and was always out of date. So we save time and get accurate information. Cadence saved more than $10,000 in 2000 by automatically tracking documents through version control. One manager reports “The EDMS system saves me an average of an hour a week on tracking and maintaining information on the books I’m responsible for. But better than that, I know the information I’m getting from the system is up-to-date. And I can ensure closure on the handoff for books I’ve given to another group.”
  • An automatic way to inform configuration management of what document kits need to ship with what version of the product.The EDMS automates the delivery of self-extracting executables (UNIX tar files or PC ZIP files) for each release stream, elminating the need for writers to physically transfer files for releases. The savings for this task was nearly $150,000 in 2000.
  • Reduction in the number of processes used to create documentation, as shown in the last figure on page 10.
  • The ability to support continual development of and for the WebWorks filters.Writers can use different versions of the filters based on their needs, depending on whether they need the latest version of the filter and if they are early enough in the release cycle to accept changes in their HTML files. The ability to support several versions of the filter at one time would have been impossible without EDMS.
  • The ability to map documents to a changing set of product, group, and family categories and ensure that one document uses a constant set throughout the life cycle of that document.We can continue to process updated documents for old releases and use new product names and groupings for new products. This ability also would have been impossible before implementing EDMS.
  • The ability to link the data in EDMS with other tools that display data over the Web.

Responding to current and future needs
Cadence is beginning to use the Web to enhance our product delivery process. Although the first step is being able to generate and update licenses for customers, the future site will manage customer views of information so that it is specific to them. All of the attributes we have in our EDMS system will support the model for delivering information on the Web. We are positioned to help Cadence give customers information about products they have purchased. And with Documentum’s market acceptance, the new Internet tools Cadence is choosing work with our database.

The research and development groups within Cadence are beginning to use (or reuse) code for multiple products. This means sharing information among products. The authoring community is beginning to generate requirements for writing information once and using it in multiple deliverables. We have the in-house expertise to implement enhancements to the system to support single sourcing so that authors can create and manage shared content.

In conclusion, EDMS has allowed KTO to standardize and streamline the process for producing documentation, saving us time and money. At the same time, the system is flexible enough to be developed for future needs. CIDMIconNewsletter

About the Author

 BPFebruary0227