Contributed by Bruce L. Stegner, Ph.D

One of my favorite lines from the old Laurel and Hardy movies was “Well, here’s another fine mess you’ve gotten me into.” This memory came to me as I was thinking about documentation today compared to pre personal computer days. This point of view is that of an end user, rather than a professional programmer. The professional programmer has additional documentation requirements that end users seldom encounter. We had a Wizard on our team who would write routines to facilitate or streamline our end users’ use of the centrally maintained mainframe computer. After he brought up one of his routines someone said “Where is the documentation on how to use this routine?” His answer, given in all seriousness, was “Read the source code.” The routine was written in Assembler and he was indicating that he had commented his code sufficiently that it would describe how to use the routine.

This anecdote captures the state of documentation at that time. To use a computer to accomplish a task was just falling out of the realm of professional. A common use for computers was to calculate statistics. Editors were written by professional programmers for their own use in writing programs. They were not word processors although the University of Waterloo had written a system called Script which let you imbed commands in a file and then process that file on the mainframe. This “mark up” language was one of the first tools available for “end users” and was considered a gift from the Gods. The previous gifts from the Gods had been “White-out” and “Correcto-type” which allowed those of us who used typewriters to fix a typo on the fly. Prior to that an error meant the whole page had to be retyped. I think half the dissertations I saw acknowledged the author’s spouse for typing.

There was another aspect to Script. It came with a manual. And the function of the manual was to teach the end user how to use Script, regardless of the computing environment. The early statistical packages all came with a manual. At that time all computing was done on mainframes. There were a few hobbyists’ starting to play with microcomputers, but their power was quite limited and documentation would have been useless to most users.

In August, 1981 (I think) IBM announced their microcomputer and one of the major assets that made it attractive was that it came with good documentation. That was the first domino in a series of rapid changes as the impact of microcomputers changed not only the way we computed, but the way we lived. The internet was still years away, but many companies and entrepreneurs saw the advent of the microcomputer as a business opportunity. The level of documentation varied widely - we were grateful if there was any at all.

Did I mention that microcomputers and their peripherals were very expensive? I think I paid about $4000 for one of the first IBM micros (thank God for student loans). It came with single sided floppy disk drives. The only printer available from IBM was a rebranded Epson dot matrix printer that could handle the full set of IBM PC characters (256). You could buy the same Epson for about $200 less but it was not programmed to handle any of the characters with ASCII codes greater than 128 (I think that was the hateful number). The Epson printer came with a big, thick manual. I stayed up most of a night reading this spiral bound tome and it was reasonably well written.

It took a while for the statistical packages to show up on microcomputers. The machines were barely more than toys and the operating systems had many constraints. We all had to wait a few years before SAS was available. When it arrived it came with two manuals – one for SAS and one for using SAS on your type of computer.

Once the microcomputers started having the horsepower to run an operating system that would let SAS run, other things became possible. One of these was documentation built into the product. Manuals were books and books were expensive. For a long time the F1 key was the standard “Help” key. Eventually companies like SAS put their complete books online. Not only did that provide a convenient and helpful way to use the product, it also let new concepts creep into our idea of documentation.

Documentation for microcomputers was finally respected and documentation standards became more professional. While the plethora of SAS manuals available today is astonishing, they are very well written and well edited. They meet the standards of text books. Indexes are professional and complete. A large portion of the SAS documentation is available online. Having grown up with books I still have a personal preference for reading a manual, but having the information in help documents has opened up the world of SAS and its many faces to thousands of people in a wide range of businesses.

One of the things that has surprised me about documentation has been animation and movement have not been used much. To have such tools in a help document would finally leave a book behind. In fact, many of our figures and graphs in statistics might benefit from animation. One of the changes that has come is in the world of Dictionaries. I now prefer my online dictionary to my bound versions. Why? Because my online dictionary will pronounce the words outloud for me. My reading vocabulary is much greater than my spoken vocabulary. So when I encounter a new word I can hear what it sounds like when spoken. Can you imagine reading the word Yosemite and trying to use it in a discussion without knowing how it should sound?

I wonder what new things future documentation will show us? New visual ways of informing us? Sound? Should online SAS let us click on Bonferroni or Cronbach to hear how they sound? In terms of learning, we know that the more parts of our brain we use to incorporate something new, the better we will retain it. I am interested in what some of your thoughts are on the state or future of documentation.

Bruce L. Stegner, Ph.D. is an executive consultant in the state of Washington and has worked as a scientific manager on both coasts of the USA. He teaches SAS programming and has written a 100-page book for beginners. Contact Bruce at brucestegner@comcast.net