The Omnipresent Trend: Web Bloat
There is no doubt that the number of technical documents produced and published on the Web over the last several years has grown exponentially. With powerful new search engines indexing every known document ever produced, the Web is a tremendous resource for developers and programmers who need to get information on the latest Macintosh system updates, for example, or answers to frequently-asked technical questions, such as those on Apple's Technical Q&A site. This has accelerated the trend for many companies to throw every imaginable piece of technical information on the Web -- often without regard for how that information is to be understood or used by the readers who visit that company's Website. Indeed, Web bloat is here and shows no signs of abating. This may make it more difficult, in fact, to find necessary documents to aid in your development efforts, but that's another issue, tangential to this Note.
Factors to Consider
As more and more technical documentation is being converted to HTML, it is important to consider several factors:
Developing a Few Strategies for HTML Technical Publishing
There are several strategies you can develop to make sure that your technical documents, when converted to HTML, are structured for optimal browsing.
Strategy #1: Produce the Originals in HTML
If your technical documents are produced originally in HTML, then reviewed and distributed as HTML documents before getting posted on your Website, you'll be in a much better position to assess if they really work for Web viewing and understanding. This may belabor the obvious, but you would be surprised how conditioned we are to think in terms of "paper first" and HTML only as an afterthought.
The idea is to be able to determine the response to a technical document by seeing if that document works structurally to get across its main points. By writing a document with your word processor and then printing that document for review and allowing reviewers to comment and mark up the document in pen or pencil, you are in effect avoiding all consideration of how your reader will view or respond to the content in a Web browser. It's a little like writing a screenplay and handing it out to moviegoers at the theatre and asking them to imagine the results onscreen.
Producing documents originally in HTML may seem like an impossible chore, and until recently it was because you had to write the document and then insert all the requisite HTML tags so your browser could display it. But that's changed dramatically over the last year.
Because of the quality of HTML authoring and editing tools available, you can ask your technical writers, engineers and programmers to produce documents initially in HTML. This won't be a big stretch for them, if they're not doing it already. I won't list all the tools -- Claris Home Page, Adobe PageMill, BBEdit, and FrontPage are just a few -- that offer technical writers and engineers the power and flexibility to generate HTML documents, often without having to write even a single line of HTML code.
If desktop publishing was the wave of the 1980s, propelling forward a new generation of graphic artists, illustrators, printers and electronic publishers, certainly HTML publishing is the wave of the 1990s. Picture an environment where all of us are familiar with the basics of HTML and work with one of the HTML authoring and editing tools available.
All indications are that HTML is becoming the lingua franca of the known universe, as more and more documents are written, exchanged, published, and read in Web browers. If Marshall McLuhan changed the world in one sentence -- The Medium is the Message -- I think the world has changed us by making us dance to the tune of HTML everywhere.
Strategy #2: Build an HTML Template That Everybody Can Use
Producing HTML technical documents at the outset not only makes more sense from the point of view of presenting content to your readers -- it just saves more production time in the fast and frenzied world of Web publishing.
For this process to work, you need to build a template in HTML for your technical documents. If you build and distribute such a template, you can then ask your technical writers and engineers to pour the contents of their drafts into the template for peer review.
With Claris Home Page, for example, you can use the Strikethrough feature and color text to indicate changes and markups made by your reviewers electronically, and then when you are satisfied with the results move to publish the documents on your Website.
The template is designed specifically for the content of Technotes. It's a distillation of what works best for those who read and rely on Technotes for information from Apple.
Because Technotes work with a Thesis-Antithesis-Synthesis structure, the first few paragraphs of a Note are important for setting up the main thesis. The thesis is not an introductory paragraph, as in the traditional essay structure, but rather a formulation of a particular theory or problem, which is then "proved" or "disproved" with code snippets, diagrams or examples that follow. Each section of the Note must contribute to the issues raised at the beginning. The thesis is then resolved in a summary section at the end of the Note.
With this content structure in mind, we designed an HTML format that would work most effectively for the reader's understanding of the issues presented in a Note. The idea here was a simple marriage of form and content with HTML as the minister of ceremonies.
Countering Resistance to the Strategy
In proposing these strategies, I can hear the voices of resistance clamoring with arguments and counterarguments.
Aren't we giving up the paper/printed versions of our documents by moving right to HTML?
The answer is yes and no. Anyone can still print out an HTML document and read it to their heart's content. In fact, they can print it out in a font of their choosing and seven different font sizes.
How can you assume that everybody who reads, reviews, or comments on a technical document has a Web browser?
I heard this one about a year ago and agreed with the answer implicit in the question. A year later, well...
What about the PDF or Acrobat delivery of my documents?
The answer is that it's not difficult at all to produce a PDF or Acrobat version of your document from HTML. It just takes a little tweaking of that document, then printing it from your Web browser to a file for Acrobat distilling and conversion to PDF.
Using Tables in your HTML Template: A Sidebar
If you download this Technote template, you'll see that it is set up with a series of tables for each section and each code snippet. The code snippets are in a gray table color, notes are in yellow. (Code snippets can be placed in a table and specified as preformatted text.) Tables, where you specify the width you want the information in them displayed, are the way to go.
If you open the template in Claris Home Page 2.0, for example, you'll see that the tables have a thin dotted line demarcating their boundaries. This is very useful for capturing and viewing technical information; it also helps in terms of reviewing the content.
What's cool is that you can embed tables within tables within tables and live happily with the results.
Web browsers are here to stay as one of the preferred ways of viewing, navigating and retrieving technical documentation. With that in mind, if you begin to produce your documents originally in HTML, you'll have a better idea of how they'll be read and understood in a browser-based viewing environment. This Note provides you with a few strategies you can implement to make this happen.
Contact ADC | ADC Site Map | ADC Advanced Search
|For information about Apple Products, please visit Apple.com.|
Contact Apple | Privacy Notice
Copyright © 2002 Apple Computer, Inc. All rights reserved.