Xref: utzoo alt.hypertext:663 comp.text:7627 Path: utzoo!utgpu!cs.utexas.edu!wuarchive!uunet!mcsun!i2unix!inria!seti!motown!mark From: mark@motown.altair.fr (Mark James) Newsgroups: alt.hypertext,comp.text Subject: Re: Designing Online Documentation Keywords: document design conversion hypertext online Message-ID: <1761@seti.inria.fr> Date: 19 Nov 90 16:45:18 GMT References: <40@s5000.RSVL.UNISYS.COM> <5514@newton.praxis.co.uk> Sender: news@seti.inria.fr Followup-To: alt.hypertext Organization: Altair/INRIA, France Lines: 89 In article <5514@newton.praxis.co.uk> mm@praxis.co.uk (Michael Mannion) writes: >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? The short answer is that it is always better to design something from the beginning for a specific purpose than to retrofit it later. The real answer, though, is that you (and/or your company) can probably find better uses for your time than to recast existing documentation. >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. Unless I miss my guess, the reviewing body is likely to know nothing about hypertext, except maybe that it facilitates cross-reference lookups. Stress the simple advantages, like information at your fingertips, automatic indices, easy updating of content (unless this is not true for your implementation); if you can work anything interactive into the bargain, you get double the brownie points. Don't go into object-oriented philosophy unless you're sure that your reviewer won't turn off. Above all, don't make it look too much like fun; this may be essential for the end-user, but it's poison for a reviewer (-;). >3. Does anyone have a feel for how long it takes to put a paper >document, book online? My experience is limited to software reference manuals, but my rule of thumb is to take your honest, gut-felt worst-case scenario and multiply by two to three. >4. Does anyone have any experience of hypertext design teams working >on the same document and could offer useful advice? The fewer the number of hands actually doing the conversion, the quicker the job gets done. Use your programming resources to build tools to automate the tedious tasks (finding and collating the \ref and \index commands in a LaTeX document, for example); use your literary geniuses to rewrite the turgid or incomplete parts; and be careful who you let decide where the buttons go. In article <40@s5000.RSVL.UNISYS.COM> gray@s5000.RSVL.UNISYS.COM (Bill Gray x2128) continues: >5.) Can anyone suggest "essential" reading in online doc design? There's lots of crap on this topic, but Horton's _Designing and Writing Online Documentation_ is good. >6.) Do users prefer online doc to paper doc? Perhaps more to the point, > do all classes of users have a preference, and is it the same? For > example, do programmers prefer paper while data entry personnel prefer > online doc? What studies exist to indicate preference by user task? I don't know of any studies, but you have raised an important point. Hypertext programmers (and authors of articles thereon) often tend to assume that everyone is dying for the stuff, since it's flashy and has buttons; it's supposed to give non-computer-literate people access to computer documentation. In fact there is one fundamental problem with hypertext, and with the whole concept of replacing paper documentation with it: You need a computer to use it. This means: o You can't take it with you (unless you have a portable 386 (minimum) with a modem plugged into a cellular telephone, and a porter to carry it for you). o You can't read it for long without eyestrain. In other words hypertext is fine for quick reference, but not for learning concepts or other long-term study activities. Programmers might not mind being tied down to a screen all day long, but lots of end users resent it. Their work rhythms involve occasional changes of scenery or at least of seat position (in fact RSI doctors and labor unions insist on it), and the need to look something up in a reference book provides an acceptable reason. In this context, hypertext is sometimes perceived as a further mechanization of the workplace. The hypertext designer must bear this in mind: Its purpose is to facilitate the rapid search of information, and not to butt in where rapidity is not desired. -- === T. Mark James ==== All opinions, errors etc are my own. === mark@bdblues.altair.fr ==== "Hardware is that part of a computer === +33 (1) 39 63 53 93 ==== system that you can kick." ================================ -- Grace Hopper