Improving systems documentation using an online copy editor

ABSTRACT

For the last three years I have been using Writers Workbench, a UNIX text-editing tool, to edit computer documentation. In this article I outline my experiences using the system, noting both the advantages to explore and pitfalls to avoid in using this tool. Writers Workbench is especially useful for improving a writer's basic skills—punctuation, spelling, and grammar. When used effectively, Writers Workbench can cut down on wordiness and improve the consistency of a manual. It can help in the creation of a table of contents, index, glossary, and bibliography and in checking readability. Furthermore, by creating user-defined dictionaries, authors or editors can customize the tool to fit their purposes and styles. However, Writers Workbench is not good at catching problems relating to organization, focus, and clarity.

REFERENCES

• 1: Bell Laboratories, UNIX Programmer's Manual, Seventh Edition, January, 1979.
• 2: Bell Laboratories, UNIX Writers Workbench Software User's Manual, 1982.
• 3: Christine Browning, Guide to effective software technical writing, Prentice-Hall, Inc., Upper Saddle River, NJ, 1984
• 4: Susan J. Grimm, How to Write Computer Manuals for Users, John Wiley & Sons, Inc., New York, NY, 1982
• 5: Brown, E., Word Processing '85, P.C. World, January, 1985.
• 6: Horn, W.D., Computer-Assisted Writing instruction at Clarkson University, IEEE Transactions-on Professional Communication, December, 1984.

INDEX TERMS

Classification:
  D. Software
  D.2 SOFTWARE ENGINEERING
      D.2.7 Distribution, Maintenance, and Enhancement
          Subjects: Documentation
  D.4 OPERATING SYSTEMS
      D.4.0 General

          Nouns: UNIX

  I. Computing Methodologies
  I.7 DOCUMENT AND TEXT PROCESSING

General Terms:
Documentation, Languages