Newsletter
Newsletter Issue 45, 21 January 2001
ISSN 1442-8652
Editor: Jean Hollis Weber
jean@jeanweber.com
http://www.jeanweber.com
In this issue...
Separating layout from content development
Editing multiple-use material
Creating vanilla HTML from Microsoft Word
Resources: Grammar and diagramming sentences
Follow up: Browser questions
Australasian online documentation conference
Now available: Editing Online Help by Jean Hollis Weber
Still available: Electronic Editing by Jean Hollis Weber
Subscription information
Separating layout from content development
In the last ten years, technical writers and editors have often been responsible for designing the layout and presentation of pages, both for print and for online display, in addition to developing the content. Most content is developed in a WYSIWYG program, and even early drafts show the intended layout. This practice has both good and bad points.
In my opinion, the main bad point is a tendency to focus on presentation in situations where this is counter-productive. For example, content that is carefully designed for print may need rework when it goes on a web page or into a help file. The emphasis on presentation obscures what might be a more fundamental issue: chunking or writing the material so it can be combined and presented in different ways -- that is, reused without being reworked.
Instead of looking at how to write the content with re-use in mind, we find ourselves doing things like:
- looking for ways to deliver material online while preserving the print-oriented design
- using conditional text in files so we can extract material intended for print or online viewing, thus adding a layer of complexity to our writing and our files
- maintaining two or more sets of the same data, for use in different situations (marketing, training, user guides, help desk material, and web sites, for example)
I contend that the increasing use of XML and various database methods of storing a single copy of written material (everything from words and phrases to whole articles), so it can be re-used in different situations, is once again separating content from presentation. Many of us don't like this, and even those who see the necessity are often uncomfortable with the practice, but I think it's something we need to become familiar with and get good at, because we're going to be asked to do it.
Editors can play a major role in helping writers learn how to separate content from presentation. Many of us have worked (or still do) in publishing situations where writers have never had responsibility for design and presentation, though we probably edit with a specific output in mind. Others are used to working with input from several writers and re-chunking it for a specific purpose (for example, an annual report or a research proposal).
I'm not suggesting that all content can, or should, be developed separate from all aspects of presentation, but I am suggesting that increasingly writers and editors will be called upon to find solutions that are good, and fast, and cheap. Rather than saying "it can't be done; pick any two," we should be trying to find ways to meet that demand, in as many instances as we can.
Editing multiple-use material
Relevant to my discussion of separating layout from content development, a recent thread on the Austechwriter list was concerned with the use of the phrase "click here" on Web pages. Various arguments were put forth for and against its use. Here are some of them.
Michael Cudmore mcudmore@email.com:
Can you be sure that the material you are writing will not be reused in a
print version of the documentation? If you are asked to turn a web site into
a book quickly, the rewriting is less fiddly when your links start life as:
"For further info, see the FAQ" [FAQ being the link] rather than "For further
information, click here for our FAQ" [click here as the link].
Bruce White white@msn.com.au: "Click here" means that you have hidden the URL from the reader. I prefer the predictable approach of making the URL and the link the same, especially if the site is not in the current set. If it is in the current set, then use a link showing the topic title.
To illustrate the usefulness of the external URL, consider these lines taken from another message on my list backlog:
==========<sample>=====
Microsoft now have Desktop certification for MS-Office.
http://www.microsoft.com/trainingandservices/default.asp?PageID
=mcp&PageCall=desktop&SubSite=cert
==========</sample>=====
PRO
You know:
- it is a link to somewhere outside the current set of pages
- whose site it is
- that there is a chance that the page won't be there
If:
- you get a printed page, you still know where the link was going
- the target page gets moved, finding the page again is easier
- you wish, you may choose to visit the whole "microsoft.com/trainingandservices" section first
CON
- The URL is long enough to be daunting
- The URL may wrap in plain text or in the tool that you use (and you will lose some information by line breaks popping into the string)
Creating vanilla HTML from Microsoft Word
Someone asked on the TECHWR-L list,
"I need to identify some choices for (Windows 98/NT/2000) HTML editing software
that:
- uses only HTML 3.2 vanilla tags
- is easy for all those Word-dependent office folks to use or learn quickly
- is business-affordable and has quality documentation and support
"I need to propose one or more HTML-editing tools for the dozens or hundreds of content contributors in our company who aren't developers, but are writing most of the web content for a new industry-specific portal. The tools need to stay out of the way of the content, while providing basic HTML tags for headings, bold and italic, bulleted and numbered lists and simple tables. The interface is in the hands of developers who are handling all the CSS and JavaScript for the user interface."
My response:
Given the constraints as stated in your note, and the fact that your contributors are not supposed to be doing layout, I would not choose ANY of the available HTML editing software products, whether WYSIWYG or not.
Since your contributors are already familiar with Word, I would strongly recommend that they create their content in Word. Yes, this can work; I do it all the time. (Note: I use Word 97. I haven't tried this with Word 2000.)
Although Word is notorious for inserting superfluous tags when converting to HTML, you can easily avoid this problem.
The secret to keeping junk out of Word-created HTML is to not convert from a DOC file to an HTM file. Instead, create a file based on the HTML.DOT template which is supplied with Office97 (at least it was in my copy). The easiest way to do this is to choose File > New which open the New dialog box that lists all the templates. On the Web Pages tab, choose Blank Web Page.
Make sure you use ONLY the H1, H2, H3 etc styles for headings (NOT Heading 1, Heading 2, etc) and Normal for everything else. For a list, first type the list items, then select all of them and click either the Number or Bullet button on the toolbar. For bold, italic, or underlined words or phrases, select the word or phrase and click the relevant toolbar button. Do NO manual font/character formatting except bold, italic, or underline. Do NO manual layout formatting at all. I tried some simple tables and they worked fine; I haven't tested this method with complex tables.
When you save the document, it is saved as an HTM file, not a DOC file. Open the HTM file in NotePad and you'll see that it's clean (except for some META junk at the top of the file, easily stripped out).
In a different situation, where the contributors were expected to do the layout as well as the content, other methods might be more appropriate.
Editor's note, April 2001: For more about Word-to-HTML, see Chapter 7 of my book Taming Microsoft Word. The book also has many other tips for using Word more effectively. It is only 116 pages long and is available in downloadable PDF format. Contents list, downloading, and payment information are at http://www.jeanweber.com/books/tameword.htm.
Resources: Grammar and diagramming sentences
This section has been moved to http://www.jeanweber.com/links/grammar.htm.
Follow up: Browser questions
Last issue Roger L. Boyell boyell@ieee.org asked some questions about returning to the place you were on a Web page after following a link from that page, and about opening a link in a new browser window.
Several people wrote with answers to Roger's questions. I'll summarise the responses.
To open a new window for a link, right-click on the link and select the open to open the link in a new window. (For Mac users, this context menu appears when you hold down the mouse button on the link and don't release it until the menu pops up.) When you want to go back, either close the second window, or switch to the original window, which will still be at the place you left it.
Michele Marques marquesm@autros.com adds, "if you do this from a site with frames, you may run into errors, as you will not have the full "frameset" in the second window. Also, on sites with extensive javascript, this sometimes doesn't work (in which case, usually clicking on the link brings up a second window, anyway)."
Kat Brand kat.brand@mfe.govt.nz notes that in Internet Explorer, "holding down the Shift key when you click a link will bring up a new screen."
Some of the responses had to do with how the designer of a website can control what happens (or at least provide assistance to the user), but those suggestions are relevant only to special cases, not the general situation.
For example, Geoff Hart ghart@videotron.ca wrote, "If you [the designer] want users to easily return to a specific location on a page, you have to insert an "anchor" at the point from which they jumped, and provide a link that specifically returns to that anchor."
The problem with this suggestion is that it only works if there is only one link from page A to page B, and no links to page B from anywhere else. If users can get to page B from several other pages, then where do you send them "back" to? You don't know where they came from.
Australasian online documentation conference
The 4th Annual Australasian Online Documentation Conference will be held at Rydges Lakeside, Canberra, Australia 28-30 March 2001.
AODC 2001 is for everyone involved in hypertext development, corporate documentation, technical writing or Web authoring. Cost is $1095.
Call Penny Bradley at HyperWrite on +61-(0)3-9853-3666, pbradley@hyperwrite.com.au, or register online at http://conference.hyperwrite.com.au
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
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
© 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.
Home | About | Books | How to | Links | Newsletter | Business | Site index | Search
Articles © Copyright by their authors.
© Copyright Jean Hollis Weber, Technical
Editing Consultant
WeberWoman's Wrevenge, Airlie Beach, Qld., Australia, jean@jeanweber.com
ABN 18 005 740 467
