Ch01: Footnotes
Curriculum Vitae
The Dark Side
Limited Liability
Home Working
Work Projects
Freelance History
Employment History
Education Detail
Business History
Freelance History
Programmer
Projects Index
Software Packages
Technical Writer
Welfare (Benefit)
White Elephants
My original inspiration to go into Technical Writing • Start of my serious technical writing career • Setting up my own business • Building on-line manuals into the software they explain • Advanced techniques like HTML and semantic indexing • Developing a personal style in illustrated study notes • Using technical writing skills to improve software design • Developing software aids for technical authoring • EBS Marketeer User Manual, one of the many user manuals that I have written.
It seems to be a prevalent belief that programmers can code but they cannot write. Perhaps this is because programming languages obey rules without exception while English seems to have more exceptions to every rule that instances of obedience to it. Or it may be because programming languages are deterministic while English is highly subjective. In my early programming days of 1967-9, while documenting my flight simulator software, I began to recognise this general weakness in programmers.
This weakness first became painfully apparent when I was given vast assembler listings of complicated routines written by others which I had to adapt for the new system on which I was working. These listings boasted all of about two three-word comments per 50 lines of code. My first efforts at technical writing were therefore to block the code into functional chunks, and then head them and comment them in sufficient detail to make them easily understandable to any competent programmer. Later, by making use of the assembler's editing facilities on comment blocks, I included in my listings the program write-ups which previously had been laboriously kept up to date by hand, in pencil, on acetate transparencies. I subsequently proposed that the assembler's source editor be enhanced with what are now well known as word processing functions to ease and speed up the software documentation process.
My next excursion into technical writing was in 1970 when, in preparation for a new project, I was given a (then) Board of Trade technical specification to read. This consisted of clause after boring clause of dry over-cross-referenced verbiage. Nobody other than its authors was able to gain a cogent overview of the proposed system it was attempting to describe. In desperation, I studied the specification and made highly illustrated study notes which had a semi-cartoon flavour to them. People found them so helpful that the project director ran off a hundred or so copies and gave them to new project team members as an introduction.
In order to develop my technical writing skills to a professional level, between 1971 and 1976 I took time out from my career as a programmer to become a technical writer. To this end I got a job in the technical publications centre of a multinational. Here I wrote user and system documentation for the new generation of computer controlled telephone exchanges, concentrating mainly on call processing and traffic measurement. I also documented a store and forward voice/data message switch.
Although when I started EBS in 1976 my intention was to return to programming, I continued with technical writing. As things turned out, technical writing was to take up about half my time. My technical writing work came mainly from my former employer. This included the documenting of:
I also wrote (and frequently also produced) technical manuals and brochures for other clients. These included a system overview of a private national data network, a sales brochure for a COBOL soft machine, a sales brochure for a manufacturing package and a draft brochure for a payroll bureau. I have also written articles for magazine publication including one on a telecoms exhibition stand.
By far the largest single technical writing project which I have undertaken so far has been the user manual I wrote for my own contacts management package. It was the high cost of printing small quantities of large manuals which first inspired me to consider an on-line manual for my own software. This advantage of building the manual into the software was magnified by the ease with which its text could be updated and redistributed along with the software every time the software itself was updated. Furthermore, the fact that the relevant part of the manual could be accessed precisely from the context of the program made it easier for the user.
I experimented with several methodologies for implementing my on-line manual. I am a great exponent of hypertext (as used to great effect in this book and on my web site). But I came to the conclusion that this was not the best way to implement an on-line user manual. Much more direct access to information immediately relevant to the current program state was desirable. I therefore designed and wrote an on-line manual browser which was driven by what amounted to hyper-links embedded within certain program functions (or methods) within the package itself. To overcome the possible problem of unauthorised people modifying the text, the content of the manual was encrypted. It was then decrypted piecemeal on the fly whenever it had to be displayed. This was important for parts of the text such as licence agreements under which the package was supplied to users. The user also had the option to print out the manual in full.
Nevertheless, I am a great believer in 'horses for courses'. I have always been aware that software-driven context sensitive browsing is not appropriate for all technical writing tasks. I myself prefer to use hypertext to research new technical subjects and to locate information sources. On the other hand, I find a well written, well presented printed text book to be by far the best medium for learning a new subject such as HTML or Java programming.
I have also learned through my many years experience that the form or structure of a system is not necessarily the best model for a text describing it to a user. I believe that other readership-oriented approaches are often better. I am also a strong advocate of semantic indexing, especially in tutorial and reference texts.
I have developed an effective style of illustrated A4 study notes as part of my study process. Some are reviews of my accumulated knowledge in the technicalities of my past projects and the software environments I have used. Others are personal notes made during the reading of text books on various technical subjects.
I have used to great effect a reverse of the usual approach to software design and development. It may be summarised in the following procedure:
I here use the exercise of writing the user guide — the task of having to explain the metaphor to lay-readers — as the means of proving the validity of the metaphor itself. I assert that if it be possible to explain the system clearly to the uninitiated, then the system is logically sound. It proves the logic at the macroscopic level before either the design of the objects or the coding of the methods is begun. This invariably results in a smooth programming phase in which water-tight code precipitates effortlessly out of the earlier stages. This method has already been used to good effect.
At college in 1963 my general studies tutor encouraged us to use part of our student grants each to buy a portable typewriter and learn to type so we could submit our essays and dissertations in typed form ourselves. I took this advice and bought a small Olivetti portable typewriter and taught myself to type. This ability to type later proved invaluable — indeed essential — in my lasting relationship with computers.
When at Redifon (1967 to 1970), I had to write up a lot of program descriptions in pencil on acetate transparency paper for both customers and maintainers. This was long and tedious. About mid 1969, seeing how easy it was to update listings with the assembly language editor, I started to punch in my descriptions as comment-only source files. I was then able to update them using the assembler editor from a short update tape. Generic descriptions could thus be adapted to different versions of a particular flight simulator quickly with much less effort. I was thereby able to document my programs on the computer, producing acceptable presentations on the system's line printer. The idea was, however, thought a bit radical and was frowned upon by management.
When I left Redifon in 1970, I wrote a proposal which I touted around the main London software houses of the day with a view to their giving me a job of developing my 'text processor' idea. It was rejected by all with reactions such as: "I cannot see what possible commercial value it could have." and "What's wrong with a typewriter?" Shortly afterwards, Wang launched their 'word' processing systems.
When I started as a professional technical writer in 1971 I was provided with an Adler manual typewriter. My typescript was re-typed onto sprocket-driven magnetic tape cartridges which were fed into IBM composing equipment for camera-ready production.
I experimented for a time with IBM's Text/360 package as an authoring tool and later worked on a design for a complete in-house text processing system. However, this was shortly thereafter made unnecessary by the advent of Wang word processing systems, one of the first of which was installed at the centre where I was working at the time.
After starting EBS in 1976, I continued my technical writing work. For this I wrote an authoring package called Author's Delight. This referenced each paragraph and encouraged a good paragraph-oriented writing discipline. It first ran in 1981 on my ITT2020 — an Apple II clone. I ported it to the IBM PC XT in 1984. I continued to use Author's Delight until graphics came along. Back in 1972 while trying to establish the ideal authoring and production system, I had favoured a graphics approach. But the hardware simply was not there. No manufacturer could at that time be persuaded that there was any commercial value in developing graphics-based solutions. Since then I have done vast amounts of writing using Windows 3.1's Write & Paint accessories.
I now write mainly in HTML which I prefer to generate manually in a text editor. This gives me a degree of command and flexibility which automatic HTML generators cannot provide. I use 3 development and test environments: Microsoft Windows 95 and IBM OS/2 Warp 4 (probably for not much longer) and Linux.
In OS/2 Warp 4 I use IBM's excellent HTML/Java-sensitive Enhanced Editor for writing and maintaining documents and Netscape Navigator for display and testing. I shall greatly miss IBM's enhanced editor. I use Sun's Java Developers' Kit for creating applets. I also use IBM's Web Explorer as a non-Java browser for checking the presentation of substitution text for applets.
In Windows 95 I use Notepad for writing in combination with Internet Explorer for display. I also use Netscape Navigator and Sun Microsystems HotJava for presentation testing. I find HotJava's HTML error detector button very useful. For document creation I use Microsoft Word. Here I can check spelling, although to do this, I have had to create a special dictionary for HTML tags.
I think both operating systems have their merits but I am using Warp at the moment (Spring 1998) because it also allows me to develop Java applications which can run directly on Warp's desktop. Having said that, I can be frequently found working in Windows 95. At that time, I was just getting started with Linux.
[Addendum 2017: I preferred OS/2 until its demise in about 2001 and continued with Microsoft Windows until the end of the XP era. I found later versions of MS Windows non-intuitive and difficult to use. During this time, personal computers had become more and more powerful, until they were comfortable running Unix-like operating systems. After this, I saw no point in continuing with MS Windows. In 2007 I installed Ubuntu 06.06 (Dapper Drake). I continued with Ubuntu, switching to Xubuntu with the XFCE GUI in 2015. In 2017, I also started to use FreeBSD.]
The indexes of many technical manuals nowadays are computer-generated. They are a compilation of all words (other than common words) into an alphabetic index with page references against each word pointing to where that word occurs within the text.
I have often been frustrated by — and seen the frustration in others — when vainly searching the index for a subject item which the text definitely covers, but which does not appear to be in the index. This happens because the keyword which springs to mind when one thinks of a certain topic may not itself appear in the text which deals with that topic. The notion is often far more powerfully expressed in context by a phrase or statement which does not contain the formal keyword which the seeker thought of.
This is why I have for a very long time been an exponent of semantic indexing — the practice of placing within indexes keywords which do not necessarily appear in the text to which they refer, but which are nevertheless what may spring to mind when somebody thinks about the topic they wish to read about. This is a human skill which cannot easily or effectively be automated. It is one which I believe should be done by a technical author like myself, or even by a professional indexer.
I have practised this principle of semantic indexing when compiling the list of keywords to place in an HTML document's keyword meta tag. Stupidly, many operators of Internet search engines have programmed their spiders to penalise web pages whose meta tags contain keywords which do not actually appear in the text. Thereby, they not only defeat the whole advantage of semantic indexing, but end up penalising those who index their pages more properly. Their given reason for doing this is to exclude each web page whose author has placed false attractors in its keyword meta tag just to get more hits to his web site. For instance, the author of a web page selling vehicles may put the word 'erotic' in the keyword list, which is nothing to do with selling vehicles but which will undoubtedly attract more people falsely to the site. No wonder it is become so increasingly difficult and time consuming to find genuinely useful information on the Internet!