Strategies for Producing Browser-Based Technical DocumentationBy Tom MaremaaApple Developer Technology Services (DTS) |
CONTENTSThe Omnipresent Trend: Web BloatFactors to Consider Developing a Few Strategies for HTML Technical Publishing Countering Resistance to the Strategy Using Tables in your HTML Template: A Sidebar Summary | For better or worse, Web browsers have become one of the preferred ways of viewing technical documentation. Some 30,000 pages of Inside Macintosh were recently converted to HTML for online viewing and retrieval -- a monumental and important achievement. Yet Web browsers and technical documents make strange bedfellows indeed. Viewing documents in a browser (especially if those documents contain complex technical data, extensive illustrations, block diagrams, tables and cross-references) may be less than satisfactory -- the equivalent of reading programmer manuals in a fishbowl. The problem may be that many technical documents originated in other forms, such as books, articles, or dissertations, and when converted to straight HTML -- without concern for how the material will be "read" in a Web browser -- show their true roots. They beg to be printed or read in book format, which may frustrate those engineers and programmers who are reading them through their Web browsers. This Note attempts to provide a few good strategies for resolving some of the issues around producing and viewing Web-based technical documentation. The Note may be useful for engineers, technical writers and content producers who must wrestle with issues of producing documents such as ReadMe files, Release Notes, technical articles, and other forms of technical communication that land on the Web. |
The Omnipresent Trend: Web BloatThere 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 ConsiderAs more and more technical documentation is being converted to HTML, it is important to consider several factors:
|
Strategy #1: Produce the Originals in HTMLIf 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 UseProducing 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. We've developed a template for Technotes, which you can download by clicking here. 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 StrategyIn proposing these strategies, I can hear the voices of resistance clamoring with arguments and counterarguments. Resistance #1Aren'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. Resistance #2How 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... Resistance #3What 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 SidebarIf 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. |
Further References |
Acrobat version of this Note (126K) Binhexed version of standard Technote HTML template (50K) |
Thanks to Otto Schlosser, Vinnie Moscaritolo, Jeanne Woodward, and John Gorham.