Technical Writing at SolidWorks is a Collaborative Effort

Collaboration is a key element of the documentation process at SolidWorks Corporation, and it contributes significantly to the high quality of the technical documents. "We couldn't produce the volume of documents that we do in the time that we have without working closely together," says Georgia, manager of the Technical Publications department.

Five technical writers and eight translators collaborate with each other, with developers and testers, with a translation house, and with a print house. Together they produce a user's guide, a tutorial, multiple online help systems, and numerous smaller documents with each release of the software. Releases occur about twice a year. Because each release includes major new functionality, the documentation schedule is very tight. "Taking into account that we have to wait for the engineers to complete their changes, and that we have to freeze the English version in time for the translators to translate before the release," says Georgia, "the schedule is even tighter than it appears at first."

Some of the techniques that make this situation workable are an integrated hardware and software system, careful distribution of responsibilities, explicit procedures and style guides, and file maintenance.

Hardware and software tools

The SolidWorks software is a 3D Computer Aided Design (CAD) product for mechanical engineers working in solid modeling. Engineers see the complete model on the screen and use the many features to quickly design parts and assemblies, check attributes, explode assemblies, and derive drawings automatically.

The SolidWorks software was developed on, and for, PC platforms with Microsoft^®Windows^™. The rise of the PC, with its ever-increasing speed and capacity and decreasing cost, has made the wide distribution of SolidWorks software and its documentation easy. Documents are also handled on the company's PC network, which combined with various software packages and tools, supports the collaborative environment, resulting in a smoothly integrated system.

The writers use FrameMaker^™ RoboHelp^™ and Adobe^® Acrobat^™ for their documents. They use Fullshot, Collage, PaintShop Pro, and Microsoft Paint for screen capturing and enhancing. The translators use Trados Workbench software to speed up the translation process.

Distribution of responsibilities

This process starts with the documentation plan and determines how new material is incorporated into existing documentation and how the writers collaborate with the translators. The document cycle begins with a formal review. The documentation plan starts with the assignments from the previous release and realigns them to take into account new employees, new chapters, and new documents. The planning process is led by Georgia, as department manager, but it is also collaborative. The writers meet and discuss who is best suited to handle a new chapter, how responsibilities for documents and chapters could be reapportioned to evenly distribute the work load, and what is appropriate for a new employee to undertake.

Marilyn, one of the writers, recently joined the company as the developers were adding an AutoCAD emulation package to the software. "I had some experience with AutoCAD at my previous job," says Marilyn, "so documenting this package was a good fit." Because everyone else in the department was busy finalizing other documents to send to the printers, they were pleased at the arrangement. Judy, another writer, who has overall responsibility for the user's guide, also enlisted Marilyn to reorganize an appendix on options. "This appendix is complicated," says Judy, "and with new options being added and deleted in recent development, the documentation became disorganized. Options enhance and control many features of the product, so it seemed like a good opportunity for Marilyn to learn about the product in a manageable assignment."

Each writer has responsibility for one or more major documents, from gathering the information to preparing the document for printing. Each writer has responsibility for several subject areas for all documents. Table 1 shows the current document and subject assignments. Although the names of the subject areas may mean little to you, the table gives you an idea of the process.

Table 1: Writing Assignments for SolidWorks 99

Writer	Documents	Subject Areas
Georgia	SolidWorks Online Help	Sketching, Reference Geometry
Judy	User's Guide	Piping, Parts, Assembly, Drawing, Detailing, Configuration
Cheryle	Tutorial, Release Notes, Animator Online Help	Fundamentals, Sheet Metal, Animator
Joe	What's New, FeatureWorks & SLDDFX Online Help	Import/Export, Features
Marilyn	2D Emulator Online Help	2D Emulator, Options

Being responsible for a documentincludes formatting, generating the table of contents, index, and front matter, generating print and proof files, and overseeing and coordinating proofing with the translators and the print house.

Being responsible for a subject includes writing on the subject for all the documents, updating the material at each release, and proofing the chapters for all the documents. Writers become "experts" in their areas of responsibility, explaining them for the user's guide and online help and developing examples for the tutorial. Thus every writer does not have to be an expert on every subject.

Georgia sends the documentation plan to the managers of Research and Development, Quality Assurance, Sales, and Marketing for their input and sign-off. "If they see any red flags, they have the opportunity of voicing their concerns before we get too far in the process," says Georgia, "but they seldom object to our plans."

Writing new material

Writing new material is a process of discovery. After a new release has shipped, the development team produces a project list of product definition specifications (with project numbers assigned) of new functionality that is planned for the next release. However, this list is only a working document, and development often diverges from it. For example, some items on the list are not included in the next release, while other items that are not on the list can be added late in the process.

The writers are expected to try the new features themselves and write from their experience. "We watch the daily development summary reports for implementation of the project list," explains Judy, who developed a spreadsheet document to keep track of the changes. Cheryle continues, "We install new builds on our own machines and try out the new functionality to see how it works. We act like the customers. Sometimes we can suggest changes or demonstrate problems that the development team hadn't considered. We provide input on the user interface, which improves overall usability." Joe, who came to documentation by way of technical support, adds, "My technical support background helps me understand the customer and write for the customer."

Translation

The translators have many responsibilities, such as localizing the user interface dialog boxes, splash screens, and informational and error messages in the software. They translate the online help systems, training manuals, and other corporate documents. They also test layouts for the Quality Assurance department and collaborate with proofreaders who are CAD-literate and native to the country of the language. A translation house develops a glossary from the translated user interface and translates the major documents. Then the translators format, index, and otherwise prepare these translated documents for printing.

We try to take advantage of translation software," says Alex, the Russian translator. "The translation house provides us with a translation memory that we can access with Trados Workbench software, which we use to help us translate online help files. Trados Workbench compares a specified sentence or phrase with its memory and suggests a match. This process speeds up our translation tasks immeasurably." The software also uses fuzzy logic to find possible matches where exact matches do not exist. Alex adds, "We're looking at QA Help for comparing the English versus the localized online help files at the next release and insuring accuracy between the two."

The writers help the translators with practical details such as inserting graphics, generating cross-references, and so on. This support is particularly important the first time through the process. Lin, who recently produced the first translation into simplified Chinese, appreciates the help that she has received from the writers. "There were many terms to define," she says. "Even with my engineering background, some of the specialized terminology needed explanation. And Judy spent much time helping me with the graphics files, tables, and documentation procedures."

Judy says that the writers in turn learn from working with the translators. "We learn to appreciate the difficulties in translating technical terms, and to avoid vague language," she says. "We think much more in terms of how clear, concise, and unambiguous we can make our writing." Lin adds that sometimes the translators find the messages in the resource files (the text for menus, dialog boxes, and error messages) to be cryptic. "The writers have already investigated the resource files for writing the online help," she says, "so they can explain the meanings to us exactly. That is very helpful."

"One of the keys to the success of the translations," notes Georgia, "is that each translator is a native speaker of the language. However, the writers can do much in their writing to make translation easier." Some of the techniques the writers use to help the translators include following a detailed style guide — to keep formatting and terminology consistent — and avoiding potential pitfalls such as acronyms, contractions, long sentences, and humor. They use more commas, articles, and the word "that" than is necessary for English speakers in order to provide clues for the translators. They use words, examples, and graphics that are culture-neutral and gender-neutral, and the models in the examples are items that are recognizable anywhere in the world. In general, they write straightforward English; in addition to making translation easier, the English itself is clearer.

Explicit procedures and guidelines

Written procedures and style guides streamline the writing process. As a new employee, Marilyn had the benefit of these documents. "The style guides and template files helped quick-start my contributions," she says. "I was able to choose paragraph tags, for example, that had already been defined in a template. And the written procedures meant that I didn't have to bother the other writers at every step." Georgia, who as manager has overseen the development of these aids, appreciates the lightening of the management load that results. "I have writing and administrative work of my own to do," she says, "so time saved in instructing new employees is beneficial all around."

The department also has a mentoring system to help new writers. Cheryle was Marilyn's mentor. "Cheryle helped orient me to a wide variety of tasks and resources," says Marilyn, "from introducing me to other employees and installing software on the computer, to getting started using the product and finding the files and written documents to support writing new material. It was a very friendly way to start a new position."

File maintenance

Most files are maintained on a server that is accessible to all the writers. Even when files are maintained locally (as online help systems often are), they are accessible from the network. As assignments shift, writers can access the files they need without effort. Chapters in one document are easily copied to another and then edited as appropriate.

The writers update existing material and write new chapters as functionality changes. At regular department meetings, the writers discuss what new subjects require separate chapters and which can be added to existing chapters.

The writers maintain directories of graphics, usually screen shots that are also used by the other writers and by the translators. There are two types of graphics: (1) those with no language or with call-outs that are separate from the graphic image, and (2) screen shots with words that have to be translated and re-shot for the localized documents. The number of graphics that require translation is kept to the absolute minimum to make the translation process easier.

The writers may ask any of the other writers to proof their work as they generate new material. They usually proof from printouts, but also sometimes generate Portable Document Format (PDF) files, which are read online, usually from the server, in Adobe Acrobat Reader, a convenient, time-and-paper-saving procedure.

The editing and proofing process is more formal as documents approach printing. The writer in charge of a particular document has a proofing check list with items for front matter, table of contents, index, and various aspects of each chapter, with a separate check list for English and each of the eight other languages. Each writer is responsible for proofing several chapters in all languages, not for wording, of course, except in English, but for formatting, widows and orphans, correct graphics, and so on.

The main documents are printed on high-resolution printers at a print house for the languages (English and several of the foreign languages) that need a large number of copies. The writers and translators generate PostScript print files with the appropriate printer driver and send a laser printout with the file. The print house notes any discrepancies for the writers to resolve. Because the writers have already reviewed and proofed the documents extensively, very few discrepancies appear in the final print phase.

Other documents are delivered in electronic form. For example, release notes are included with the software in Rich Text Format (RTF) files. Online help systems are integrated into the application. The writers provide help (HLP) and table of contents (CNT) files from RoboHELP projects to the developers, who build them into the SolidWorks software.

Conclusion

Collaboration benefits everyone in the Technical Publications department. As all writers know, it is difficult to see errors in one's own work. It is even more difficult to see problems with logic and flow. Peer review is an important way to test and evaluate material before it is published. Peer reviewing contributes to keeping the documents consistent in both substance and form.

Becoming experts in certain areas benefits the department, too. Each writer can focus on certain subjects, so the writing is more efficient. Each writer takes responsibility for certain support expertise as well, to provide assistance to the other writers and the translators in a particular software or procedure, for example. Judy learned about and wrote a procedure for generating PDF files from a FrameMaker book, Cheryle documented the procedure for updating release notes, Alex helps the other translators with Trados software, and Joe is the resource for questions about submitting files to SolidWorks builds.

That the writers proof documents in a foreign language may seem puzzling at first; however, it is actually quite useful. "Being an expert in a particular subject," says Joe, "I am familiar with the graphics used in the documents. When I look at a document in Japanese, for example, I focus on how the graphics fit with the instructions, so I can spot when a graphic is out of place." Because the writers are not checking the words, they can concentrate on other aspects such as widows and orphans, number of steps, and so on.

"We're proud of the documents that we produce here at SolidWorks," concludes Georgia. "They are accurate, readable, and attractive." Recent accolades from customers confirm this assessment.

Marilyn B. Kloss is a technical writer at SolidWorks Corporation in Concord, MA. She can be reached at mkloss@solidworks.com

Report any problems with the Broadside online to abruce@tibco.com
January 8, 2001

Inside . . .

Technical Writing at SolidWorks Corporation Is a Collaborative Effort

by Marilyn B. Kloss