torus6.gif (1371 bytes)


cctext.gif (2384 bytes)

Services Tips Theory WebPoems Workshops Books Articles Lisa Jonathan


Restructuring Legacy Documents for Multiple Re-Use
  Internet Prose 101

Writing for Webzines

Testing to Revise

Restructuring Legacy Documents for Multiple Re-Use

Writing Effective Procedures

Adopting an Object Orientation to Improve Documentation

Designing Online Help

So You Wannabe a Technical Writer?


We’ve entered the age of information recycling, but many of us have inherited whole libraries of legacy documents that are so poorly chunked and so incoherently written that we cannot easily move them into an online environment such as a Web site or CD-ROM, and we even blush to reprint on paper.

In this intensive two-day workshop, you will learn how to adopt an object-oriented approach to editing current documentation to make it more effective. You will see how to rethink the purpose of each sentence, paragraph, and section, in conceptual overviews, procedures, language reference, process descriptions, and tables of contents, to prepare for extensive re-use in a variety of genres, formats, and media. Done badly, the transformation of legacy materials ends in customer rebellion. Done well, it improves the quality, efficiency, and impact of your documentation.

Working with hands-on exercises, discussion, and extensive readings, you will learn to reorganize, revise, and, if necessary, completely rewrite legacy materials, revising them for object-oriented disassembly and multiple re-use, modularizing them for random access, and developing guidelines for consistency across the line.

This workshop does not promote or teach any particular tool, programming language, or corporation; the focus is on writing and editing skills you can apply in any situation. You will also find that because of this consistent, object-oriented approach to structure, you can convert the resulting documents into XML or SGML more easily than you could have transformed the tangled originals, but this workshop does not explore any specific markup syntax or tools.


What we cover

Adopting an object-oriented approach. Moving from the document model to the world of objects. Spotting a rhetorical object. Putting rhetorical objects into packages you can easily retrieve, reuse, and give users access to. Dovetailing your anatomy of information with the emerging enterprise-wide data model for consistency, efficiency, and better user access.

Opening Up Access: Using an object orientation to cope with the multiplication of levels and topics you are being asked to organize on a CD-ROM or Web site, creating more meaningful and efficient menu systems, headings that help users decide among hits in a search, and index entries that add value to the references. What writers can do to improve a user’s success in searching a gigantic pile of information.

Enabling Decisions. How to open up the decision-making process by offering decision diagrams, and process flows that open up to lead users through choices, while offering supporting files, email contact, and access to archives of email exchanges.

Procedures as Packages: Stripping down your existing procedures, to make sure they are functioning efficiently; reassembling them in discrete chunks, for faster use, and easier re-use.

Command and Language Reference: Exploding those dense paragraphs, to separate out each functional object, allowing customers to identify the objects they want displayed, while reducing others to icons.

Conceptual Overviews: Disassembling these often-garbled chapters, deciding what to move elsewhere, picking a structure for the remaining materials.

Special Considerations for Web Delivery: Defining categories of information, to simplify menu systems. Creating clear paths through the material. Picking a structural model that matches your purpose.

Facilitating Virtual Conversations: Discovering ways to increase your ongoing electronic discussions with users, customers, developers, and other groups within your company, using the new objects you have at hand.

Revising style. When material must appear on the screen, as the primary delivery mechanism. Copyediting changes; edits for cohesion and consistency; edits for tone. Stripping text to the bone, for online delivery; using conditional text for the extra passages you need for some paper versions. Considering special editorial changes for Web delivery.

A Look Ahead: Anticipating a move to the Standard General Markup Language (SGML), or its subset, XML. How all these revisions prepare your documents for that conversion. Why restructuring alone can give you 80% of the benefits, during the first few years.


Author of How to Write a Computer Manual and The Trail Guide to America Online, co-author with Henry Korman of How to Communicate Technical Information, Dr. Jonathan Price has coached documentation teams in his object-oriented approach to creating hardcopy and electronic information systems for major computer manufacturers in the U.S. and Japan. For a high-level view of his approach to restructuring, see his articles on Structuring Complex Interactive Documents and Complexity Theory as a Way of Understanding our Role in the World Wide Web.

Recent clients for this workshop: Adobe, Informix, UCSC. We are always glad to customize a workshop for a particular group or setting.  Please call Jonathan at 505 898-4912 to get more details.


Copyright 1998 Jonathan and Lisa Price, The Communication Circle
Return to our site at
Email us at