Xref: utzoo alt.hypertext:659 comp.text:7614
Path: utzoo!utgpu!cs.utexas.edu!wuarchive!emory!stiatl!srchtec!glushko
From: glushko@srchtec.UUCP (Bob Glushko)
Newsgroups: alt.hypertext,comp.text
Subject: Re: Designing Online Documents
Message-ID: <307@srchtec.UUCP>
Date: 18 Nov 90 21:09:56 GMT
References: <5514@newton.praxis.co.uk>
Reply-To: glushko@srchtec.UUCP (Bob Glushko)
Followup-To: alt.hypertext
Organization: search technology, inc.
Lines: 98

In article <5514@newton.praxis.co.uk> mm@praxis.co.uk (Michael Mannion) writes:
>Having just scanned thru `Designing & Writing Online Documentation' by W.Horton
>can anyone offer some thoughts or share their experience on the
>following:
>
>1. Given a large paper technical reference manual which is suited to
>beig online and which is already word-processed, is it better to start
>from scratch and re-design the document into hypertext format or would
>it be better to take what exists and `mould' it into hypertext format?
> 
  It depends on a lot of factors.  You say the manual "is suited to being
online."  I assume this means that it is composed of a large number of
small topics that stand alone but which are enhanced or expanded upon
by reference to other topics.  How big these components are and the 
nature of the cross references they contain are important design issues
that determine how easily you can turn text into hypertext.
  At all costs, you want to avoid "doing it by hand." The hand-crafted,
artistic approach is always tempting the first time, but when the time 
comes to revise the manual you will hate yourself.  What you want is to
be able to extract the components using the formatting instructions that
indicate section headings or other natural partitions.  Likewise, you
want to be able to get the links because they are explicitly indicated
with some sort of structural markup.  If your word processing form doesn't
do this, then you may want to have a talk with the people who wrote the
manual and tell them how to use style sheets or formatting instructions
in ways that you can process automatically.

>2. If we can make the distinction between the hypertext `design' and
>its subsequent `implementation' how can we describe the design so that
>it could be formally reviewed.
>
  In my experience the most important thing to do is to separate all 
consideration of the logical design of the hypertext from considerations
of how it looks.  Most hypertext projects get infatuated with user 
interface aspects, and this focus drives out any serious consideration
of hypertext-design-as-database-design, which is what it really is most
of the time.  You want to ask questions like "how many links are there,"
"are they one-way or two-way," "what exactly is being linked to what (is
it a word, a filename, a bitmap)," and only afterwards worry about the
kind of icons or link markers you use.  HyperCard and other hypertext
programs encourage a bad engineering approach because you have to worry
about user interface issues (i.e., create buttons on cards) to develop
and debug the control structure of the program.

>3. Does anyone have a feel for how long it takes to put a paper
>document, book online?
>
Again it depends.  Putting it on line may mean loading it into a text
database, doing some kind of automatic or semi-automatic conversion, or
doing a carefully hand-crafted hypertext applications with lots of sexy
bells and whistles.  

It will take a lot longer than you think, that's for sure.  I have
worked on or consulted with a couple dozen projects of this kind and 
lots of things can go wrong:

    unrealistic expectations 
    missing people on the design and development team (especially
       when you start messing with multimedia)
    no design guidelines to follow (at least for realistic scale projects)
    installed base constraints (hypertext on a PC is a cruel hoax)
    poor quality source files
    no industrial-scale hypertext technology
    legal problems (what copyright category is an animated encyclopedia;
        you mean I can't scan in those pictures?)

Each of these can kill you; together they are almost guaranteed to do
so unless you think about them hard.

>4. Does anyone have any experience of  hypertext design teams working
>on the same document and could offer useful advice?

I wrote a paper on exactly that.  It is called "using off the shelf
software to create a hypertext encyclopedia" and it compares the
use of HyperCard, HyperTies, and Guide to do the same problem. It is 
in Technical Communication in February 1990.

I have written a fair amount about hypertext conversion in other places.
In February 1990 I have a paper in Unix Review called "Visions of Grandeur"
(terrible title, but the editors picked it, not me) that talks about
how hard it is to do hypertext on a practical scale.  I talk about
problems with online manuals in Unix explicitly.

I also have a paper called "hypertext engineering" in the Proceedings
of the ACM conference on document processing from December 1988 that
talks about the design and implementation issues in converting a
printed encyclopedia to an online one. 

I teach courses on these topics at various places; I'll be doing one
at the ACM CHI confernece in New Orleans in April.  I am also writing
a book about it, full of the case studies that led to my list of
ways to make your project fail.  Hang in there and good luck!

Bob Glushko
Search Technology
4725 Peachtree Corners Circle #200
Norcross, GA 30092 
(404) 441-1457