For the past three years, I've been involved in the documentation, design, and document construction of the Black Magic, Help System II, and HyperWriter hypertext/hypermedia authoring systems. Considering this month's theme, preparing a hypertext version of Dr. Dobb's Journal using HyperWriter seemed an ideal, yet challenging, project. This article describes the steps I took and the decisions I made. While some of these steps were unique to the task at hand, overall this is typical of most hypertext projects.
Prototyping
My first task was to prototype the "look and feel" of the hypertext version. I took the September 1989 issue of DDJ and constructed two prototypes of the document -- one article-based, the other card-based. The major distinction between the two can be summed up in one word: scrolling. Article documents "scroll" up and down the screen while card-based documents "flip" from one screen to another. An article-based document can have unlimited length in any of its nodes, while a card-based document is a collection of screen-sized nodes linked together.
Initially, I didn't know which approach was more appropriate. Though I like card-based hypertext documents and understand that users often find them easier to navigate through, I first opted for the article metaphor. For one thing, card-type documents are nearly impossible to use without a mouse. Mice, though common, are not everywhere; with an article-metaphor system, keyboard navigation can be efficiently employed. In addition, article-metaphor hypertext tends to be significantly easier to create than card-based hypertext, which requires you to "chunk" the material across multiple cards. After evaluating the two metaphors and how readers might interact with them on the screen, I ended up using elements from both, as described in the next section.
Another decision I had to make during the prototyping stage involved the size of the document. The goal was to fit everything -- document, runtime, and source code -- on one or, at the most, two floppy disks. This conflicted, however, with my desire to create the best possible document, a full issue of DDJ on disk. I compromised by creating two versions. The version shipped with the listings disk is a bare-bones hypertext document containing articles and source code. To save disk space, the graphics for this version were created with the extended character set. The other version, however, is a complete issue of DDJ -- articles, graphics, letters, and more. Directions on how to obtain both documents are at the end of this article.
Preparing the Data
One of the first steps in creating this hypertext was data preparation. I was supplied with ASCII text files extracted from DDJ's typesetting system, which could be readily imported into HyperWriter. This made the text-end of things relatively easy. Graphics, however, were a different story. Most of the graphics were supplied in a Macintosh format. This meant converting the graphics from MacDraw to a MacPaint bitmap and bringing that bitmap to the PC with a Copy II PC option board. Next, I converted the MacPaint bitmap to a .PCX bitmap format, correcting the aspect ratio of the Macintosh bitmap to appear correctly on the PC's screen. Finally I converted the corrected .PCX bitmap into HyperWriter's compressed bitmap format to minimize disk space. Although this sounds like a lot of work, it is mostly just tedious. In addition to converting the graphics images, I had to construct versions of each graphics file with the extended ASCII character set. Once these tasks were done, the real work of building the document could begin.
Planning
When all the data was in the computer and in machine-readable formats, I was ready to start building the document. Right? Not quite. I've found that before creating any large hypertext document, a small amount of planning makes worlds of difference. An early constraint was to optimize the size of the hypertext document to accommodate HyperWriter (the toolkit I used), which currently works only with hypertext documents that can be contained within memory.
To provide fast access to the contents of documents that are actually spread across several files, I duplicated the Table of Contents cards in each hypertext document. This eliminated disk delays caused by simply accessing the Table of Contents. Now, disk delays occur only if the article being accessed is actually stored in another hypertext document. To help me build these documents that all share a common Table of Contents, I first created a "kernel" document that contained only the Table of Contents cards. I then used the kernel document as a base from which to create the rest of the hypertext documents.
The Actual "Hypertexting"
Once I finished building the framework of the hypertext documents and formatting each article, the real work of "hypertexting," or creating the cross-referential links, could begin. In the hypertext field, there is a growing distinction between what are called "objective" and "subjective" links. An objective link is a link from the table of contents to a particular article. A subjective link, on the other hand, is an editorial link that cross-references relevant material or makes a comment on existing material. What we've found so far is that while the objective links are essential, the subjective links are what add real value to the hypertext. They are the "frosting on the hypercake" (so to speak). The major example of subjective links in the DDJ hypertext are the links to the source code files. These links allow readers to dynamically view both the articles and the source code. Building the subjective links, beyond the source code links, required analyzing the material and then creating links where appropriate.
Using the DDJ Hypertext Document
When you first open the DDJ document, you'll see a screen like that in Figure 1, which represents a DDJ cover. This card-based format offers access to the different sections of the Table of Contents. Select any of the links along the bottom of the screen to access a section of the Table of Contents. Selecting one of these links yields a Table of Contents card like that in Figure 2.
You can select any of the links from a Table of Contents card and access an article. Articles are presented in article-metaphor format. A sample article from the issue is shown in Figure 3.
I made an interesting observation on the nature of hypertext during the design of the article-metaphor parts of the document. The basic user interface of a hypertext document is not the hypertext software but rather the document itself. The arrangement of a hypertext document -- that is, its node and link structure -- forms the bulk of the user interface that the reader encounters. The only time a reader steps outside the "document as interface" is when he or she elects to use the features of the hypertext runtime itself. To further enhance the document as user interface, and to lessen the learning curve for existing readers of DDJ, I adopted as many of DDJ's standard formatting conventions as possible. See Figure 3, which shows the beginning of one of DDJ's feature articles. The one major difference in formatting conventions is the substitution of different colors in the hypertext version for different fonts in the magazine.
Multiple Entry Points
Entry points provide a place to start reading or browsing. Part of the beauty of the printed page is that you have not only multiple entry points, but also easy access to those entry points. Some examples of commonly used entry points include subheadings, figures, and sidebars. To access any of these entry points on paper, you flip through the pages of a magazine article or book.
Although hypertext allows the same sort of entry points as paper does, those entry points are often inaccessible because they are off-screen. To address this problem, each article in the DDJ document has a top line similar to that shown in Figure 3, allowing easy access to all of the figures, subheadings, and tables (the different entry points into the article).
Conclusion
From the above description, you may get the impression that creating the Dr. Dobb's document was a lot of work. It was. We initially allotted six weeks for the job. The final version was produced, working part-time, in just under three weeks. Overall, much of that time was devoted to conceptual activities such as design and planning. Building the actual document was relatively easy with the exception of creating the subjective links -- that took real analytical effort.
