The myth and realities of C.A.S.E. for documentation
Authors: D. Patterson
Venue: Proceedings of the 7th annual international conference on Systems documentation (1989)

Hypertext seems to be the major focus of user documentation groups, and even some system documentation people. But system developers, engineers and architects are interested in C.A.S.E. More of our documentation work will be coming from or going into C.A.S.E. solutions and integrated systems, and documentation groups should begin to look very seriously at what C.A.S.E. advertises itself to be, what it is in fact, and what r&ocirc;le documentors are likely to play in the face of this touted &ldquo;software development revolution.&rdquo; C.A.S.E. is an acronym (and we thought those went out in the 70s) for Computer-Aided Software Engineering. Very little is new here, except the combination. A C.A.S.E. tool is one of dozens of possible pieces of software, techniques, and documents that were developed since the 70s, and which, theoretically, can be combined to create a black box for system generation. The object of the exercise is to put clear, organized, system documentation into the black box, and out comes a working system, for whichever computer (called a platform) you want, with complete user documentation, both on-line and &ldquo;manual&rdquo;. The concept should be highly threatening to documentation people, and yet I have not heard a single murmur in the community. The reason, I suspect, is not only that Hypertext is more distracting, being perceived as more glamorous, but also that C.A.S.E., in order to sound modern and revolutionary, has enveloped itself with a great deal of new jargon. The first step of the process, supposedly, needs to be done only the first time you begin using C.A.S.E. Actually, it is such an expensive step, that most firms ignore it, hoping for the quick and dirty answer. Plus &ccedil;a change, plus c'est la m&ecirc;me chose. In this first step the system architect analyzes the organization, known as &ldquo;the enterprise&rdquo;, that wants the computer system. He or she determines the minimum amount of data that the enterprise uses to do its business, and establishes the relations and processes that link pieces of data into meaningful combinations, called &ldquo;information.&rdquo; The result is &ldquo;The Enterprise Model&rdquo;. A system is conceived as a view of the enterprise model, that is, one department's use of the data and processes that really belong to the enterprise. Those of you who are familiar with this material may realize that I am simplifying some of this, but those of you who are not familiar with it are probably already confused, right? For those who are a trifle bewildered, let me get a bit more specific. We have an analyst who has created a very theoretical model of a corporation that says that a company is just a collection of data, and processes (programs, people, authorizations) that manipulate that data. Since most corporations keep more data than they need, and do many processes at least twice, this model can be useful in cutting waste. Because the object of the effort is to create systems that are clean, simple, and use a database, you can see why you begin to write your first C.A.S.E. system by doing not only a Spring cleaning, but a complete analysis of the foundation of your house! Because this model is so important, and because corporations are always changing, this model must be kept as a large software (and sometimes hardware) system of its own, with a huge database that documents each item of data, each process, and each combination. This work ordinarily takes years, because the data must be reconciled to show that Customer name, and Ship-to name, are in the end actually the same, and that each of them points to that basic data item called name. I have chosen an easy one, but you can imagine. The crucial thing about the model is that it must be right. And since the documentation is going to be used later for creating working systems and documentation, it should be clear and concise.* Some system analysts or software engineers believe that this accuracy means that only they can write this sort of documentation. They completely loose track of the importance of the text for later documents, and for the transfer of knowledge to another group of C.A.S.E. analysts who will build the view or modify it. This is not throw away documentation, and it must be done especially well. Such work is enormously time consuming, as I have already made clear, and so I have seen groups just put in the name of a data item, its length, and its data type (alphanumeric, usually), and ignore description, aliases, and other information not important now, but vital to a succeeding generation of C.A.S.E. tool users. Once the enterprise model is completely documented, system analysis can begin. The system is established as a view, by selecting the data elements it inputs and outputs. If the documentation of the data has been correctly done, all one needs is a list. The system is probably already documented as a high-level process, but the details are designed using &ldquo;upper C.A.S.E.&rdquo; or front end C.A.S.E. tools. These are microcomputer based drawing tools for ye olde Demarco and Gane and Sarson diagrams, with a little module at the back that makes a small database of the relations and data items. All of this is fun, so this is usually where less far-thinking firms want to begin using C.A.S.E., and it is probably where there is the largest population of C.A.S.E. tools in the spectrum of possibilities. Diagrams are sexy, and people who can't draw think that this is all just a game, but can be passed off as hard work. For the user, there are screen mock-ups that fit into this process. These are usually part of a &ldquo;Fourth Generation Language&rdquo; for one is either hidden, or very obvious, as part of the bottom level of the diagramming technique, creating pseudo-code for the &ldquo;primitive&rdquo; level of diagrams. The second-largest number of C.A.S.E. tools is probably in this part of the spectrum. They take the pseudocode, which they tell you is not really programming, but documentation, and the data descriptions, and create some form of brute-force computer code. The object of this exercise is to create something nearly foolproof, that is repeatable. Some code-generators produce COBOL because it is comforting, or C because it is trendy. Supposedly, you put this code on your machine, compile it, or simply copy load modules, depending on the sophistication of the tool, and the whole system is supposed to run first go. What actually happens is that there needs to be real programming done in order to tweak the system. If you have an unusual platform, or one with some unusual devices running on it, or you want to have a real-time system, there must be code written to tailor the brute-force code to fit. Virtually no vendor of C.A.S.E. tools has all of these parts. They may present a unified package by buying the rights to remarket someone else's portion of the spectrum. The big 8 (or are there only four now?) accounting and consulting firms usually just buy the company with the C.A.S.E. tools instead of the marketing rights, but the result is the same: there are some rough edges that need to be smoothed over by more code and perhaps some documentation. All right, I have been describing a system&mdash;one made up of hardware for graphics, such as &ldquo;mouses&rdquo;, software for diagramming and code generation, and methodology for doing the right steps in the right order. The usual possibilities for documentation are apparent, but what is special about this tool? In some ways there is nothing special about it. It only brings together the collection of problems that we have been working on for a long time, and are still hoping to solve, such as better on-line help, better system's documentation for tools that can be changed as the user desires, and better procedures and forms. In another way, it is very special and important, because the heart of C.A.S.E. is documentation. But the conglomeration of these documentation tools is now being put into the hands of software engineers and system analysts, and marketed as though no writing of prose were necessary. To make my point even clearer, let me explain the usual look and feel of C.A.S.E. products: The data dictionary, encyclop&aelig;dia, or central repository (I've heard all of these three names, and there may be many others) is just an on-line glossary. The standard names of data are entered, followed by pseudonyms, type (alphanumeric), and length (4 bytes, packed). Following this meager description is some prose to say how the data should be used, how it differs from something similar, if it does, and any other important information to the potential user of this data. If this glossary entry is a composite item, made up of other data items, then there is a list of what it contains, usually provided by the software, e.g. &ldquo;MAILING LABEL&rdquo; contains &ldquo;FULL NAME&rdquo;, and &ldquo;ADDRESS&rdquo;. When you look up ADDRESS you find it contains ADR LINE1, ADR LINE2&hellip;POSTAL CODE. What most of the project spends its time doing is looking at these data entries to decide if this is the one they want, and if it is, connecting it to process entries, or other data entries. For instance, an analyst wants to build a system for keeping an inventory of office furniture (there have been thefts lately), so he needs to find some identifier for the office furniture, and he might just use the catalogue number from the purchase order for this furniture. He them builds a new record that attaches that catalogue number with the name of the employee who has been assigned that desk. The employee name, and the catalogue number exist in the glossary, so he must find them, probably by starting a search through the personnel record description, and the purchase order records. He then copies the data names, and creates his new record containing them. He then attaches the record to his new system name. Sorting and searching requires some good text, preferably brief, and to the point. There are a great many names in any enterprise. Naming data well is a special skill that is best done by someone with a good vocabulary, but only prose will make it clear in the end that this is the right data item, and where it can be copied from. Sorting and searching is fully 50% of any C.A.S.E.-related, system-development project once the glossary is begun. These encyclop&aelig;dic data bases can, of course, be searched in any order. So here we have not only the usual problems of on-line documentation&mdash;how to put it all on a single screen and make it clear&mdash;but also the complications of a Hypertext&mdash;we know not in what order the information will appear to our reader; and we can give him no clues in terms of position in a book, as to what he might have been expected to read before he began reading here. Once the data has been identified, or more usually, while it is being identified, the children are playing in the Demarco, Gane-Sarson sandbox. Here are diagrams that are good tools for the designer, but which are useless without the glossary, and so are often ignored once the preliminary design phase is done. The circles and boxes ordinarily cannot have the well-designed names shown in Demarco, et al., because these diagrams are being used by the system to generate linkages for use later in the code generator. In some systems comments are allowed, and are usually ignored. The diagrams are the most attractive part of the process, but they are often cumbersome as they extend past the boundaries of the screen, or, when reduced, are too small to read. So while they are updatable and so on, they are employed much less than the glossary over the life cycle of the system. Imposed on all of this development so far is the notion of life cycle. This is some plan that can only partially be imposed by the system, and involves a good deal of good common sense. Everyone, without exception, hated the 1970s system development methodologies that were books of long-winded aphorisms followed by forms to copy a thousand times and fill out, one for each of the one thousand data items to be used in this system. And yet behind all these forms and writing down of mother's reminders to wash behind your ears, there was some important stuff, which cannot be done away with. Most C.A.S.E. tools try to gloss over the methodology by giving you a diagram, and telling you to wing it, hoping that you have learned enough in a course on the subject to do the right thing. Teaching planning, good habits and good models on which to base standards is still a job for writing, film or some other, non-software medium. All C.A.S.E. tools give lip-service to the methodology. None addresses it squarely for someone who has never used a C.A.S.E. tool before. The bulk would be bad psychology; the exposure to the real length of time all of this will take, and the effort involved would kill sales. Screen mock-ups begin pretty early on. Supposedly this is where user testing begins. The usual 4GL method of mocking up screens is integrated with the glossary and the diagramming tools to put the right data with the right length of field on the screen. Text for prompts may be taken from the glossary. It is a rare firm that sees this testing as the first opportunity for Usability Testing of the documentation and user interface, because the C.A.S.E. myth says that documentation will come as part and parcel of the system development process. This means that the documentation that users will be expected to see will be the prose in the glossary&mdash;if anyone could be bothered to write it. Although there is nothing to stop an enlightened system developer from hiring a psychologist to help in the development of the user interface, or a good word monger to put the mot juste in the prompt to keep the screen clear, and easy to use, yet not condescending, there is also nothing in the C.A.S.E. methodology to promote the use of experts here beside the user, who knows his system best. Here I may add that in addition to the myth of C.A.S.E. there is something of a myth that the users knows what they want, meaning what they need. The reality is that they know what they like, and that may just be the best of whatever they have seen so far. Shown something better, they usually ask for the system to be redesigned, and the cyclical part of that life cycle comes into play. Most C.A.S.E. tools recognize the cyclical problem, and try to take care of it here in the screen development. Much time may be wasted here because only software engineers and users are involved rather than experts in user interfaces. Once the screens are accepted, then coding begins. Of course this is not supposed to be programming, just the creation of pseudo-code, that last element in the Yourdon, Demarco, Gane-Sarson methodology. Actually it is programming in some version of a Fourth Generation Language, with some Third Generation features to take care of &ldquo;platform&rdquo; dependencies. Since this coding is part of the C.A.S.E. product no system documentation is needed over and above the glossary and diagramming. Actually, since the tools are usually separate, either there is some &ldquo;reverse engineering&rdquo; to take the code back to the glossary, or the code is really undocumented. As we know from many published papers, 4GLs are not easily interpreted without the help of documents. Once the generated code is merged with the platform-dependent modules, the code is supposed to be running. Actually, patches may well be required. There is practically no way to document the patches neatly in any of the glossary or diagramming niches, except in text. Some C.A.S.E. tools, which I will carefully not name, then claim that it is possible to use all the documentation that has been accumulated thus far to generate the user documentation automatically. What happens is a long print out of the help screens, which are, in turn, the text from the glossary. Reams of text with SGML tags is technically documentation, but of the sordid kind that I, for one, would like to see abolished. There can never be a point to documentation built out of homogenous blocks of object descriptions. There is no place for insight. If the C.A.S.E. tool permits the addition of text for prefaces and the like, then the documentation becomes ancillary to the construction of the system, and all the usual problems of keeping the documentation current will reappear. Having sat through what must seem like a diatribe on the design of C.A.S.E. tools, let me say that I like them, and believe that they are exciting additions to system development. What I decry is the promotion of them as minimizing the need for experts, such as documentation and user interface specialists, and even good programmers who can code in assembler. It is a myth that a few good software engineers, and a few sterling users will necessarily build great systems with C.A.S.E. tools in practically no time. Let me highlight the r&ocirc;le of documentation experts in C.A.S.E. Needs Document. In order to get any system implemented in any methodology, it is still necessary to have a needs document to ask for money and man power. Talent is required to get money where it is tight, and there is lots of scope here for the right sort of expert. Feasibility Studies. Feasibility studies, now written in plain language, must be made available to users as well as upper management with the new notions of C.A.S.E. Talent is once again required. Requests for Proposals. Many firms will need to hire consultants to develop the enterprise models and systems. Good requests for proposal are hard to find, and as a result, estimates for the work are often wildly out of line, and the whole project costs too much. A really good writer would be invaluable for these. There is not sufficient work being done in this area, and I believe that a few text books could be written for this work. Information Technology Strategies. Once the enterprise model is developed, and integrated into what it usually called an &ldquo;Information Technology Strategy&rdquo;, this plan has to be promulgated in the company, and among potential contractors to develop systems to adhere to it. These documents are either detailed lists of hardware and software, or collections of aphorisms that would do the boy scouts proud. I haven't seen any work done in this area, and there certainly should be. Glossary Entries. The texts that appear in the encyclop&aelig;dia for modelling are critical. The whole notion of C.A.S.E. stands or falls by them. The wording must be honed to perfection so that it is easy to comprehend in a glance at the screen, and yet perfectly accurate. Good writing skills should be complemented by genius in order to make the processes of searching and selecting items just tolerable. To permit the text to be used as user documentation, as well as system documentation, requires heaven-sent revelation beyond the scope of genius. Although there is certainly need for, and scope for, research in technique here, I quietly harbor the belief that only art, not science, can deal with this problem. Still, real people need to do this, and there should be real training in how to approach the creativity of the effort. Screen Design and Prompts. The wording on screens, as well as the layout, the typefaces, the amount of reverse video, and the balance of information on one or many screens takes some special expertise. The placement of the context-sensitive help in relation to the fields on the screen, and the manipulation of that help text, all need the same kind of attention as people are now giving to hypertext applications. This kind of help is a version, a variant, or a close cousin to a hypertext application, with special constraints to ensure that the text is concurrent with the glossary text. I have not yet seen anyone advertise hypertext as a C.A.S.E. tool, but this may be my limited acquaintance with the myriad C.A.S.E. products on the market. Code Documentation. System documentation of the insightful kind, which I believe still to be in its infancy, is very much needed for these projects. Project Documentation. Project documentation is also a requirement here as the system development methodologies have been shrunk to a few diagrams&mdash;who is responsible, and who had accomplished what so far? This is an on-going and thankless task, and perhaps rather mechanical, but tactical, as well as strategic, action is necessary. Training Materials. Training in methodology needs to be done, if not in a fat book, then in a course. More Training Materials. User training is still necessary. Even for systems that are so carefully designed that the user gets the point immediately, there is always some advanced knowledge, additional policy, or procedure indoctrination necessary to make things come together. Tutorials, Procedures and Policies. Tutorials, and other user documentation needs to be developed that may not easily come from wedges of text used to describe specific data items or program routines. I should point out here that I have mentioned that the better sort of glossary contains documentation about procedural elements of a system as well as programs, but usually there is just a pointer to the policy and procedure manual, not a complete procedure or policy. There is a text about the book containing the procedures and where to get a copy if you are lucky. Policy and Philosophy. C.A.S.E. is based on ideas, about information resource management, about reusable code, about strategic planning. All of these ideas may require not only the Information Technology Strategic Plan document, but corporate policies to ensure that the plan is followed, and to integrate the plan into the corporate goals. Policy writing is not normally considered a documentation function, but it most certainly must be done with the cooperation of the documentation leader of the enterprise model. Wording must match, and so on. There is certainly scope for research into how this can best be achieved. I perhaps have omitted something, and you will see it, and comment on it. Documentation, it seems to be me, is made more valuable because of C.A.S.E. tools, and requires more skill than is now given to the training of software engineers and analysts. Most computer science programmes do not give any instruction in writing skills for documentation, and throw the wrong kind of professional into the breech of C.A.S.E. While I have every sympathy for the marketers of C.A.S.E. tools who want to emphasize the good design, the coherence of systems' and corporate goals, and the benefits of simplified maintenance, there is a myth here that all of this can be done without very many people, and those few are system engineers and users. The truth is that a great deal of the value of C.A.S.E. lies in particularly well constructed documentation, and good programming skills in a high-level language. There is no simple black box that eliminates the need for talent, for clear thinking, for programming and for maintenance. The only thing that may have been eliminated is the coding of simple tasks in COBOL. None of the documentation is eliminated, rather adroitly constructed texts and supplementary materials are more important than ever before. C.A.S.E. tools require the skills of experts to use, and they challenge us to do much further research to bring the promise of C.AS.E. to fruition.