frank@adiron.UUCP (Corradino) (02/28/91)
briand@tekig5.PEN.TEK.COM (Brian D Diehm) writes: > [a well written discussion of differences between] > [word processors and documentation systems ] Wow! I hope Brian doesn't mind if I use his discussion in my justification to my management for migrating to Interleaf! Four years ago we migrated from word processing to desktop publishing through the acquisition of PCs and Ventura Publisher. That step resulted in significant productivity gains (from 50% to 100% reduction in man-hrs/page depending on the product or type of document). However, two tasks that Brian described--change control and effectivity--are becoming increasingly difficult using Ventura. The difficulty comes as our products become more complex through maturity and more diverse through customization for specific customers. Our experience indicates there are really three levels of tools. We characterize them as: 1 - word processors 2 - desktop publishers 3 - documentation systems with desktop publishers providing a bridge between the two extremes. The choice of which to use depends more on the type of documentation you intend to produce and less on your occupation or training. The type of person in our department has not changed; the product we document has become more complex and diverse. > I trust this is a content-enriched enhancement of my original raspberry! :-) You are commended for providing the enhancement without involving personalities. Frank Corradino email: uunet!adiron!frank PAR Technology Corp. phone: (315) 738-0600 Ext 338 New Hartford, NY 13413 disclaimer: you bet!
jwi@cbnewsj.att.com (Jim Winer @ AT&T, Middletown, NJ) (03/05/91)
I (Jim Winer) wrote: ||If you are professional writers, you won't like either Framemaker or Publisher. ||They are very easy to use for a novice, you just follow the menus. If you ||do something else for a living, this is ideal. If you write for a living, ||you will find that you have to follow the menus every time -- there are ||no shortcuts. It will drive you batty. ||You will also find that the integrated art is for amateurs too. If you are ||used to doing good art on your Macs, plan on driving your artists up a wall. ||In general, Framemaker and Publisher are good for projects where documentation ||is an afterthought. They are not compatible with people who write or draw for ||a living, but they are very good for engineers and supervisiors. Brian Diehm wrote: |Jim, I don't know about your background, and I will try to avoid making any |assumptions. Actually, I'm trying to avoid bringing personalities into this. |But, since you ask, here's a little about me. My background is 17 years of |software engineering, then a career change 4 years ago to documentation. Since |that change, I have been in a purely documentation environment, where we have |as many as 30 manuals in development at a time, and where we are maintaining |about 130 more. Clearly, this is a monstrous task. Also clearly, we can see |and experience the difference that electronic technology is making on the |workflow of our department. My role in this has been at various times as |document designer, human interface analyst, writer, editor, project leader, |futurist, technologist, and now as manager. I know the Interleaf system we |use from inside out, top to bottom, and have since Version 3. I am not alone |in our department; we were a beta site for Interleaf TPS 4.0, and we are a |beta site for Interleaf 5.0. My background is 20 years as a superprogrammer, systems analyst, and application architect followed by 12 years as a technical writer. I have been a project manager and a supervisor, and ran my own consulting company for a while. Obviously, paper qualifications aren't going to tell you anything about the differences between us and our viewpoints, so let me tell you what the paper doesn't show -- I am a drop-out from Engineering Physics at Cornell. I have worked on the staff at the State University of New York and Indiana University without ever having a degree. I dislike being a manager or supervisor. I have designed and worked on on-line hospitals and police systems including the FBI's National Crime Information Center. (In short, real-time systems where somebody's life might be at stake.) I have done Portfolio Management and Backroom processing for banks and stock brokers, worked for chemical companies, printing companies, and many others, on everything from the largest mainframes to the smallest PCs. I switched to Technical Writing because I was tired of being asked to solve the same problem over and over again. I am an independant consultant, and have been since 1972. |From our view, the fundamental difference between a word processor and a docu- |ment system such as Frame or Interleaf is just as great as the difference |between a typewriter and a word processor to start with. Those who make the |mistake of thinking of document systems as big brother word processors will |miss the real value of the document system. It is our opinion that Interleaf is |far ahead of Frame but that both products are on the same course, and neither |is comparable to a word processor. | |... [stuff left out] | |The point is that in order to get the capabilities of the product, the human |interface problems are a secondary consideration. When someone else comes up |with the same functionality AND a wonderful human interface, well, it might |be something to consider. Until then, we live with a few quirks, but it cer- |tainly is not something that slows this department down or gets in the way of |our work. Period. | |The same thing applies to the integrated drawing package. Some of our folks |migrated to Interleaf from packages such as Claris CAD and Adobe's Illustrator. |You're right, it's not as nice and the illustrators didn't like it at first. |But within a day, they were able to get their jobs done, and within a week, |when they saw how they could control drawing libraries and maintain changes, |they wouldn't go back. (More on change control below.) Again, the functionality |far outweighs the niceties of interface. I don't think that there's any thing wrong with your analysis, except the fact that in nine out of ten installations, it doesn't happen that way. To use a documentation system successfuly, you have to work to it's strengths, not attempt to force the system to fit your own sloppy procedures. In the beginnings of the data processing field, It was a standard joke that computers just let you make bigger mistakes, faster. This is the situation with documentation systems now. In several cases that I have seen, Interleaf has gone in and nothing has changed except that production drops by 15 or 20%. That doesn't have to be the case, it just often is. Other Interleaf installations have gone just fine. |The things that make a document system far beyond a word processor reflect a |global view of a document and the documentation task. As an example, take a |feature that Interleaf names "effectivity." (Frame, I understand, is working |fast to provide similar functionality.) You may be used to saying "Well, this |product is just like that one, except for these differences, so I'll just copy |that manual set and start from there." That works, as far as it goes. With |effectivity, you don't copy the file, you merely add new information to the |existing file. As you add things, you tag the ones that don't apply to your |new product, and you tag the new things that don't apply to the old product. |When you are ready to print, you enter a control expression that defines which |set of tagged items should be included, and hey presto, it prints out. | |... [more stuff left out] | |Let's say you have a tutorial example set, where you expect the user to perform |numbered steps in order. With a document system, if you add a step in the |middle of the sequence, the other steps renumber automatically. Or, if you add |a figure in the middle of the chapter, all the figures renumber automatically. |Better yet, if you use effectivity so that the added step or figure applies to |only one of the versions of the manual, when you apply the control statement |all the figure numbers and step numbers renumber automatically. Troff actually does all of these things better than Interleaf. It has some very extensive conditionals. Add the Source Code Control System (SCCS) and make files, and you are way ahead of Interleaf. -- It does have a stiffer learning curve, however. |Interleaf has announced what they call "active documents." These are documents |that access information through a database system, such as Oracle. The doc- |uments you create from the database information can be configured to match the |intended reading audience. For example, your document, when sent to your CEO, |can be heavy on the financials. The same document, sent to your engineering |manager, can provide the technical nitty gritty. Databases, spreadsheet, wordprocessors, and many other programs can all be dynamically linked under WINDOWS and many other DOS systems on the PC. In fact, Bestinfo's Wave 4 is probably a better system than Interleaf and it runs on PCs. It assumes (as does Xyvision and other high end programs) that writers write, artists draw, editors edit, and page layout people lay out pages. The documents are passed from workstation to workstation for experts to work on. Only Interleaf and its ilk try to force the writer to lay out pages. |For some time we have been advising our engineering teams that we will soon |have the capability of maintaining a specifications database, one that predates |any engineering effort at all. Specifications of projects in the early concept |phase are nebulous and subject to great revision. However, the database can be |used to begin building the document sets, including design documents, hardware |development, human interface development, and final user manuals. Each develops |in parallel with the engineering process, and all get finished simultaneously. |As the specifications database is changed, those changes are reflected |automatically in the manuals. You should have been doing this years ago. The tools were there, why are you waiting for Interleaf? |The advantage is that the project can be seen from all points of view as it is |being developed. Halfway through, if someone gets a wild idea, then it can be |put into the database as a tentative move. Then people can see how it affects |every aspect of the project, right to the user manuals. Of course, in the early |phases of the project, the user documentation will not be detailed, but later |on such a wild idea change becomes a "what if" scenario, much as spreadsheet |pilots do today. | |Until active documents, this was a pipe dream. We knew we were on the verge of |being able to do it; we knew Interleaf was working in that direction. It is |now in the realm of possibility, and we will be using it to the full. Ignorance of how to use existing tools leads people to look for new tools that are less powerful, but have better salesmen. 8^) |Ignorance of these aspects of the documentation problem, I have observed, leads |people from an engineering background to emphasize the less important aspects |and features of a document system, and to overlook the real power they offer. I |don't know your background, Jim, so I'm not pointing fingers at you, I'm simply |documenting my observations. | |... [more stuff left out] | |As I have made plain, I think that both Interleaf and FrameMaker are products |far beyond word processors. However, I do really feel that Interleaf is far |far ahead in the global thinking that moves documentation into information |management. Interleaf has shown that their thinking is far beyond the placing |of black marks on white paper, or even colored marks on paper. They go beyond |the assumption that paper is the medium of choice, to really bring the full |benefit of emerging technologies to bear on the discipline of information |management. For example, demand publishing (just-in-time manuals) is one |intermediate example. Interleaf's products reflect their futuristic bias. |FrameMaker is continually playing catch-up in this regard, and they seem |always to be two to three years behind. They do not seem to have the global |view that is so necessary if we are to move beyond Gutenberg's model of the |printing press. | |I trust this is a content-enriched enhancement of my original raspberry! :-) Actually, one of my main gripes with Interleaf is that the type represented on the (Sun, 19") screen is too small and it gives me eyestrain. A second gripe is that there are no shortcut keys. (Somebody else disputes this -- it depends on which hardware platform and software release you have.) Interleaf sold many systems that I know of with the promise that Release 5 (on the Sun platform) would have a zoom feature and short-cut keys. That was two years ago. Real soon now. 8^( Keep in mind that once you install hardware and pay for software, you must defend your decision, even if it is wrong. If you really want a documentation system instead of a wordprocessor, look at Bestinfo's Wave 4, Xyvision, and some of the other top end systems. Don't trust anything a salesperson tells you, or anything a supervisor tells you who has to defend their decision. See it with your own eyes before you believe it. Interleaf, in my opinion, is a half-way system. You can do better if you are willing to look. The opinions, of course, are my own. Your milage may vary. Jim Winer -- jwi@mtfme.att.com -- Opinions not represent employer. ------------------------------------------------------------------ "No, no: the purpose of language is to cast spells on other people ..." Lisa S Chabot