 |
My Technical Writing Experience Originial inspiration to go into Technical Writing The start of my serious technical writing career After setting up on my own as Eastern Business Systems Building on-line manuals into the software they explain Advanced techniques like HTML and semantic indexing Developing a very personal style in illustrated study notes Using technical writing skills to improve software design Developing various software aids for technical authoring. |
I'm a proud member of  |
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.
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.
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 the time of writing, I am just getting started with Linux.
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 so difficult and time consuming to find genuinely useful information on the Internet!