Newsletter

Newsletter Issue 44, 7 January 2001

ISSN 1442-8652

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

In this issue...

Numbering pages, figures, tables continuously or by chapter
Website design: accessibility considerations
Two views of the value added by technical editors
Australian government guidelines for electronic documents
Question time: Current issues in electronic editing
A plug for Woody's Office Watch
Now available: Editing Online Help by Jean Hollis Weber
Still available: Electronic Editing by Jean Hollis Weber
Subscription information

---

Numbering pages, figures, tables continuously or by chapter

In commercial publishing, pages in books are almost always numbered continuously: if Chapter 1 ends on page 17, Chapter 2 starts on page 18 (or perhaps page 19, if the style is to start each chapter on a right-hand, odd-numbered, page).

Many technical documents, however, restart numbering at 1 in each chapter, and preface the page number with a chapter number, so Chapter 1 might end on page 1-17, but Chapter 2 always starts on page 2-1.

Page numbering style affects the numbering of other document elements, including figures, tables, and equations. If pages are numbered continuously, then figures, tables, and equations should also be numbered continuously. If pages are numbered by chapter, then other elements should also be numbered by chapter.

(Whether headings should be numbered is a separate issue that I won't discuss here.)

Editorial choice - some criteria

Editors often need to decide which way documents are numbered and record that decision in the company's style guide. This is one of the many editorial situations where there is no "right" or "wrong" answer, but rather an answer that's best for the audience and the document.

If the audience has strong expectations or preferences one way or the other, you should probably choose the numbering style that they are familiar and comfortable with. But a clear-cut audience expectation is often lacking, so you need to use other criteria for your decision.

One criterion is ease of maintenance. If you are using Microsoft Word, and breaking long documents into chapter-length files, you'll know that page numbers within a file take care of themselves, and that figure, table, and equation numbers within any one file (if inserted as Word captions, using fields) will update automatically the next time you update fields. But I don't know of any easy, automatic, foolproof way to do continuous numbering from one file to the next. You have to manually set the first page number, figure number, and so on in each file, though the subsequent numbers will still update automatically.

So you might think that numbering by chapter is much easier, but setting up the numbering to work properly and be picked up in the table of contents and index is not a trivial exercise for the uninitiated.

(Other publishing tools such as FrameMaker handle the continuous-numbering problem without problems, so if you're not using Word, this criterion might not be an issue.)

A case for numbering by chapter

Another maintenance criterion has to do with revisions to a book or manual. Here's what one reader, Roger L. Boyell, Forensic Analyst, boyell@ieee.org has to say on the subject. He makes some points that I had not previous considered, about material intended for some specific uses.

"Since material is, or should be, logically grouped into chapters, the chapters should be semi-independent and self-contained, with a minimum of cross-references if possible.

"As an engineer who reads (and writes) a lot, I'd prefer separate numbering within each chapter, of its respective figures and tables. Example: Table 17-5 is easily found in Chapter 17. I think this has strong advantages.

"The practice, typical of textbooks, of keeping each chapter as a separate entity (a) affords you the author with ease of modification (changes do not require renumbering all successive figures in the entire volume), (b) provides us the readers with ease of reference (avoiding, for example, looking up Figure 1,630 out of 2,146 total figures in a mass of pages), and (c) assures the instructors of consistency from one edition to the next (allowing lecture notes to be used even under revisions of the original work).

"One may wish to extract a chapter without carrying the entire volume. Further, the figures and tables may be published in a different format (e.g. foldouts) which is not even part of the basic text. In many cases Web publications set up tables and figures simply as links to other Web pages. Numbering them by chapter serves the reader by correlating the figures and tables with their earliest references in the basic text.

"The volume as a whole may be kept intact by page numbers, but the page numbers float depending on the printing format (e.g. letter vs. legal size). Thus page numbers should not be the primary reference to a table or figure. Page numbers are still necessary to permit one to resequence a dropped or de-collated set of printed pages, and to assure all pages are present in any given publication.

"Of course, when you prepare the final index for any edition, printed or electronic, you can then make up a List of Tables showing their page numbers (along with chapter heading page numbers, etc.) for convenience of the reader of that particular edition. Occasional new figures and tables in subsequent editions can be inserted as 17-5.1, 17-5.2, etc. without renumbering the original Table 17-2."

Back to top

---

Website design: accessibility considerations

As I mentioned last issue, I have a particular interest in editing Web pages and Web sites for accessibility. Many Web designers and writers seem to be completely unaware of some of the relevant issues. Several of the lists I subscribe to have been discussing some of the issues recently (in some cases, in response to my rants on the subject).

Why don't people upgrade?

For example, many people don't understand why others don't upgrade their browsers or buy a faster modem, forgetting that many of us don't have a choice. A fast modem is useless to someone whose telephone line doesn't deliver a speed over 33K or 24K or even less. Most people do not live in areas where a broadband service is one of the choices, never mind discussing how much it might cost.

Going beyond cost and basic availability, many people also assume that upgrading a browser or getting the latest plug-in is simply a matter of downloading and installing it, since the two major browsers, and numerous plug-ins, are free. For people with home computers, that may be true (but they are more likely to have the slow access problem).

Employers' attitudes about the latest software

People using computers at their workplace often have no choice about the software installed on it.

Many companies do not want their employees viewing the latest and greatest in multimedia; it detracts from their work and wastes the company's time, even if the employees aren't playing games or viewing porn on company time.

Javascript is commonly disabled on business networks for security reasons.

Many businesses do not allow individual employees to upgrade software on their workstations, because it can lead to a lot of extra work for the computer support and maintenance staff. Upgrading several hundred workstations can take a lot of time and money, even if the software is free, so companies often are years behind the latest releases, choosing to make one big jump every year or two rather than lots of little jumps.

Using handheld computers at work

Another audience segment are those who primarily use handheld devices, often at work. These people may not be accessing the Internet, but they often need to access their organization's intranet. Examples include warehouse personnel who may need to look up data on products, and medical personnel accessing patients' records in a hospital. If the designers of that Intranet haven't taken this into account, the pages available (which may be essential for the handheld-users' work) may not display properly on their displays.

If the development of the intranet has been outsourced (as it often is), and the design company aren't as good as they should be (a not-uncommon problem) and doesn't do a thorough audience analysis, or if management hasn't written explicit enough specifications (another not-uncommon situation), the problem may not show up until rather late in development.

Using handheld computers to access Web sites

Then, of course, there's the companies that are selling products but don't seem to design their sites for their target audience. My favorite bad examples are several sites that sell software to be used on Psion palmtop computers, but that cannot be successfully navigated by anyone actually using a Psion to access them.

Isn't that the target audience? Do they expect Psion users to also have a machine running something that can access their sites? (In some cases, that's exactly what they do expect, as stated in answers to queries to the webmasters of the sites concerned. I think this is really short-sighted and off the mark.)

Do they decide that Psion users without another computer are not potential customers? Do they think that segment of the market is so small that they just don't care? Perhaps it is; I don't know; but it seems silly to me to deliberately ignore any potential customers. It wouldn't be difficult to make those sites accessible to that market segment as well, if someone chose to do so.

Back to top

---

Two views of the value added by technical editors

Another topic recently discussed on TECHWR-L was the contrast between what writers do and what editors do. Some posts revealed an all-too-typical narrow view of what editors do, and what their value is to a project.

Here are a couple of contributions from technical writers who do understand and appreciate the value of editors, reprinted here with permission.

Lisa Wright mailto:liwright@qwest.net said,

"I think editors who understand the content area can provide more value to a doc than one who doesn't. Like a technically adept writer, a technically adept editor can identify where content may not be complete or accurate.

"I also think that editors can contribute a great deal to keeping the content on track, ensuring that it meets the needs of the audience, etc. This partly takes the form of ensuring compliance with style guides and standards, but it also means that the editor needs to read the doc with his or her brain fully engaged and constantly asking questions.

"An admin can do the compliance part -- are styles properly applied, etc. But when I want substantive feedback on a doc, I want an editor who is focused on making the doc better and has more ways of doing it than just moving a paragraph here or there. The best editor I ever had was the one who constantly made me think about and question what I was doing. To me, editing can be a creative function, not because the editor is a frustrated writer trying to impose her will on a writer, but because she can bring the best out of the writer."

Brent Jones mailto:brent.jones@level3.com added,

"I agree. In my experience, a good technical editor has nearly as much, if not more, content expertise than the writer. This makes sense because an editor reviews the docs for all of the writers working on a project or for a functional group, and thus sees _all_ of the content for a given subject rather than one writer's piece of it.

"A good editor becomes a valuable repository of general subject matter expertise, and often asks informed content questions of the writer based on his or her broad view of the project: "You say here in your install guide to do this; in Sue's syad guide she says to do something else -- why the disjoint?"

"Note that I said a good editor, one interested in the subject matter and with a mind capable of assimilating and retaining lots of information as he or she reviews. An editor who doesn't do this, who just reviews for format, consistency, and adherence to company style, is about as useful as a writer who shoves SME information into a template without any understanding of the subject. In other words, not very.

"However, with regard to format, consistency, and adherence to company style, don't give them short shrift. While they have no purpose without good content, they can and do have a subtle but powerful effect on a reader's perception of the quality of the doc or doc suite, and thus on the doc's usefulness to the reader. A whole suite of docs that have a consistent and appealing format and writing style (even if produced by different writers) can have a strong confidence-inspiring effect on the reader. I would never entrust editing/enforcement of these items to an admin type.

"If I'm reading an application's docs and come across typos, ungrammatical constructs, or inconsistent structure and format between docs, it immediately makes me question the content itself. If the writer can't get the presentation right, he or she may well have messed up on the content too. And that seed of doubt planted in the back of my mind colors my perception of the usefulness of the doc and even the product it discusses. I think writers who dismiss the importance of presentation (consistent style, format, word use, etc.) risk dissatisfied users and unhappy clients."

Back to top

---

Australian government guidelines for electronic documents

The Australian government has a document titled "Guidelines for Commonwealth information published in electronic formats", Revised Edition January 2000, at this address: (no longer there).

It looked to me to be a rehash of material from various sources, and has probably been abandoned; a search for the page leads one to a reference to the W3C site.

Back to top

---

Question time: Current issues in electronic editing

Roger L. Boyell boyell@ieee.org asked,

"Reading a lengthy Web page (much more than a screenful of text, say) with a link, you click that link and access a new page. Good. Then you want to return to the original page by using the BACK button.

1. What is there in the original site's code which allows or prevents return to the same location on that page, instead of to the top or to an arbitrtary scrolldown location?
    
2. How do you tell your browser you want to keep the original site up and overlay that window with the linked site's window, so you don't have to wait after BACKing up for the original page to reload?

"I've tried setting Netscape's Preferences and IE's Internet Options for these features, without success."

I answered:

"Good questions. Unfortunately, I don't have any good answers, despite trying for some time to find out. These are things that I'd like to be able to do too.

"Opera has the facility you mention in point 2, along with a lot of other features giving the user far more control than IE or NN do.

"I don't know of any way to control (or even affect) where a BACK button takes you on the page, though I wish I did."

If anyone has a better answer to either of Roger's questions, he and I would greatly appreciate hearing it.

Back to top

---

A plug for Woody's Office Watch

Anyone who uses Microsoft Word or other Microsoft Office products should subscribe to Woody's Office Watch, a free weekly e-mailed newsletter. Many of the tips aren't relevant to what I do, but I find two items of particular value. One is information about security problems in Office (and what to do about them).

The other is pointers on whether and how to get upgrades to Office, including what to say if the person at Microsoft who answers your call tells you incorrect information, something that has happens all too often.

If you're not already a subscriber, I encourage you to join by using the link below. No, I don't get paid anything if you join, but Woody will donate US$0.10 to good causes for each new subscriber.

http://woodyswatch.com/aff.asp?src=PG

Back to top

---

Now available - Editing Online Help

by Jean Hollis Weber
155 pages
ISBN 0-9578419-0-6
Published October 12, 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

---

Still available: Electronic Editing

by Jean Hollis Weber
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.

---