Newsletter

Issue 52, 20 October 2001

ISSN 1442-8652

Editor: Jean Hollis Weber
jean@jeanweber.com
http://www.jeanweber.com

In this issue...

An example of an editorial overview
Editing procedures and instructions (again)
Revision tracking in FrameMaker
Book review: Website Indexing
Revising websites to be more usable and accessible
Tools: BCL Computers' PDF to HTML publishing tool and others
Books available from Jean Hollis Weber
    Taming Microsoft Word
    Editing Online Help
    Electronic Editing
Subscription information

---

An example of an editorial overview

Some years ago I was asked to review a manuscript on writing and managing technical documentation, which had been submitted to an Australian publisher. I approached this task by firstly identifying the major problem areas, much as I do when brought into a company to structurally edit material written by non- professional writers.

Here is a slightly revised version of my report to the publisher. (Had I been writing this review for the author, I would have phrased some of my comments more diplomatically.) I don't know who wrote the draft, nor whether it ever got rewritten and published.

In a different situation (if I had been asked to edit the manuscript), I would have used this report as the starting point for determining how much work would be involved, how much time it would take for me to do the work, and how much the editing would cost.

Major problems identified in manuscript (not intended to be an exhaustive list)

1. Appalling punctuation and misuse of words; needs a good copy-editor.
    
2. The chapter on Computer Disk Files, which is devoted entirely to IBM-compatible computers, is totally out of place in a book of this sort. This information could be put into an Appendix if considered vital. Alternatively, a more general chapter on change control of computer disk files could be valuable.
    
3. The Bibliography has numerous problems. It contains many papers that I would not consider very authoritative (including one I co-authored). At least two authors' names (mine and Brockmann's) were misspelled. Several important works have been omitted.
    
4. The Useful Contacts list is incomplete and misleading.
    
5. The discussion of style guides and the sample style guide are inadequate.
    
6. The use of examples and humor is very uneven and frequently not where I think they would be most valuable. For example, on page xx three examples of "style" are given, but they seem quite irrelevant to technical material. A more valuable example would be the same topic written for three different audiences.
    
7. The author has attempted to address the issue of gender- inclusive language by using "he" and "she" in alternating chapters. This is not a good solution, because it draws even more attention to the issue; good writing should not interfere with reading. It is easy to rewrite the material to use non-intrusive gender-inclusive language; to not do so suggests to the discerning reader that the author is either lazy, incapable or doesn't care about the readers' sensibilities.
    
8. Writing quality is not assured by following procedures as described in this manuscript. These procedures may be necessary for a quality assurance program, but they are far from sufficient. The book does not address most of the writing issues that contribute to quality (or when it does, it covers them superficially or inappropriately). It may be outside the scope of a book of this sort to attempt to cover writing quality issues in detail, but if so, the claims made in the preface and other places in the book should be modified.
    
9. The index is appalling. It appears to have been computer-generated and not edited.

Back to top

---

Editing procedures and instructions (again)

In Issue 12, 17 June 1999, I discussed editing procedures and instructions. A recent discussion on the HATT (Help Authoring Tools and Techniques) list started with someone questioning whether a statement like "This is the end of the procedure" was necessary or appropriate. I contributed this comment.

I can think of at least one situation where explicitly stating "This is the end of the procedure" (or some other wording) may be appropriate: in a company's policies and procedures manual. These documents cover mainly workflow procedures, a slightly different beast from the typical "how-to-use-this-dialog-box" type of software procedure. In fact, many workflow procedures involve no computer use, or a mixture of computer use and other work.

Workflow procedures often have these characteristics:

• More than one person is involved, so the procedure must clearly indicate who does which steps. Often a "playscript" type of presentation is used, rather than a simple sequence of numbered steps.
   
• A procedure may have one or more prerequisite procedures (things that must be done before anyone starts this procedure), or it may be a prerequisite to one or more other procedures.
   
• A procedure may be self-contained, or it may be a subset of another, longer or more complex procedure.
   
• Individual workers may typically have copies of only those procedures they do, rather than a copy of the entire manual. They may print pages off the company intranet, or read them online, or be given a ring-binder containing the relevant pages.

Given those characteristics, a workflow procedure may have this general outline:

    Name of procedure (and possibly an identification number)
    List of personnel (job titles) involved
    Prerequisites
    Steps in the procedure (and who does them)
    A clear indication of the end of the procedure
    What happens next (if anything)

This outline sounds very formal, and it is. I certainly wouldn't use it in a software user guide (or in Help for a software product), but I would use it in workflow procedures - which are often provided in an online-help format as well as other formats.

A less formal variation, as described in my earlier article, is more generally applicable. The writer definitely needs to make clear to the reader at what point the procedure is complete, but that can be indicated in many different ways. As an editor, you need to question procedures that don't give start and end cues.

Back to top

---

Revision tracking in FrameMaker

Back in issue 13, 24 June 1999, I described some possible ways to track changes in Adobe FrameMaker, since that product does not have a built-in change-tracking feature like Microsoft Word's.

Now Integrated Technologies has produced a plug-in for FrameMaker that tracks changes. According to their website (http://www.intech.com/providers/adobe.htm), this plugin "allows users to easily monitor, accept or reject revisions within Adobe FrameMaker 6.0 documents. (Editor's note: June 2003 site not found.)

"Changes to text and graphics are monitored on Master, Reference and Body Pages and may be accepted / rejected individually or globally within these pages. Revisions are clearly identifiable by style and color. These tracking styles and colors may be modified to match individual preferences. With this tool, users are able to more effectively manage the editing process.

"Track Changes is available on the Windows platform."

Keith Soltys has reviewed this plug-in and says he cannot recommend it. You can read Keith's review here: http://www.soltys.ca/techcomm/software_reviews/ Track_Changes_plugin.htm

Back to top

---

Book review: Website Indexing

by Glenda Browne and Jonathan Jermey, Adelaide: Auslib Press, 2001, ISBN 1875145486, 103 pages.

This book has joined a short list of recent publications that have greatly influenced my work. I've known for over a year that I needed to change the retrieval aids I provide for my websites, but I had not been sure how to improve them. This book has not only shown me what to do, it's got me started understanding how to do it. I recommend it highly.

A full review and ordering information are here: http://www.jeanweber.com/books/webindex.htm

(The other book that's had a major impact on my thinking is Steve Krug's Don't Make Me Think, mentioned here: http://www.jeanweber.com/news/tenews43.htm#usebk)

Back to top

---

Revising websites to be more usable and accessible

It's been too long since I published a newsletter. I've been caught up in revisions to this and other websites I manage, not that you're likely to notice more than a few cosmetic differences for awhile. Most of the changes are in the code: I've been getting rid of the tables I originally used for layout and replacing them with CSS (cascading style sheet) positioning. I'm also now using CSS to replace old code for heading colors and other layout features. These changes not only bring the code into compliance with newer standards, but - a time-saving practical reason - they make the sites much easier to maintain and to update if a newer "look and feel" is later required.

As part of this exercise, I've been learning more about how to use DreamWeaver to automate changes using templates. And last but not least, I'm slowly improving the indexing. All of these changes are part of my learning about website design for usability and accessibility, influenced by the two books mentioned above: Website Indexing and Don't Make Me Think.

Reworking my own sites and helping others to design their own sites, I have learned a lot about the problems people can get into when they use a tool for design but don't have enough background knowledge, or don't do enough testing, to identify any resulting problems. I'll be writing up a lot of this material over the next few months, because I think it's important for editors to understand the issues and get involved in looking at more than just the content of a web page - whether their managers or clients think they should be involved or not!

Back to top

---

Tools: BCL Computers' PDF to HTML publishing tool and others

(Editor's note: The information below about Magellan and other products was taken from a 2001 website. The product has grown since then. Current information can be found at this address: http://www.bcltechnologies.com/document/products/magellan/magellan.htm.)

"Magellan(r) converts PDF files into HTML4 for online browsing. Magellan uses unique process that preserves original document layout - complete with graphics, lines, hyperlinks and bookmarks - and transforms it into a useable and searchable document for the web."

I'm sceptical about the resulting document (will it be better than what you get when converting from Word, for example?), but I haven't had a chance to test the tool or the results. I'd be very interesting in hearing from anyone who has done so.

The company also sells Easy PDF, which they describe as "an easy-to-use PDF creation tool, created specifically for those of you who need to produce PDF documents without the hassle of learning complex options."

Again, I'm sceptical. I haven't tried Easy PDF, so I don't know how good a job it does, so I'd like to hear from people who have tried it. Many people have found that other non- Adobe PDF-creation tools work fine for simpler documents but not so well on long, complex technical documents. That's okay: many people don't need to convert more than resumes or short, text-only reports.

Lastly, BCL Computers provide goBCL, a free online conversion service, to convert documents into PDF and HTML. I couldn't get through to the website to check on details, but you might like to try them out. http://www.gobcl.com/

Back to top

---

Books available from Jean Hollis Weber

Taming Microsoft Word

116 pages
ISBN 0 9578419 2 2
Published February 2001

A quick reference for writers, editors, and others who need to use some of Word's more advanced features. This book is an expanded and updated version of Chapters 3 and 4 in my first book, Electronic Editing. Taming Microsoft Word is quick to read, yet packed with essential information.

A full contents list and information on downloading the PDF file and paying for it are available here: http://www.jeanweber.com/books/tameword.htm

Back to top

Editing Online Help

155 pages
ISBN 0 9578419 0 6
Published October 2000

For students, writers, and editors who are developing online help for computer software, and for their managers and clients.

Supplements tool-specific instruction by presenting the basics of help content development, regardless of the operating system running the application, the type of help being produced, or the tools used to produce it.

More information here: http://www.jeanweber.com/books/olhbk.htm

Back to top

Electronic Editing

248 pages
ISBN 0 646 38037 0
Published October 1999

A quick start guide for editing students, experienced editors making the switch from paper to online, and anyone who needs to write or edit electronically.

More information here: http://www.jeanweber.com/books/e-edit.htm

Back to top

---

© Copyright 2001, Jean Hollis Weber. All rights reserved.

You may forward this newsletter (in whole or in part) to friends and colleagues, as long as you retain this copyright and subscription information, and do not charge any fee.

Subscription information

This newsletter is no longer being published.

Privacy statement

I do not sell, rent, or give my mailing list to anyone.

---