- Email: [email protected]
The professional's guide to writing effective technical communications
now, but also documentation is likely to be better for a program designed to be portable. A further advantage is ‘people portability’ ie if software conformed to standards, skilled personnel would have greater mobility between systems. On the other hand, portability may not be in suppliers’ interests, if the result is that customers can too easily transfer their programs to a rival supplier’s hardware. Software suppliers also have fears for the protection of their copyright if there are not these restrictions on its use. Wallis looks at the methods
presently available for designing and writing portable programs. Particular attention is given to the languages ADA, COBOL. and FORTRAN 77, as the three languages which have been subject to fairly strict standards, and therefore are highly portable. He sees his book as ‘an account of all the work that has been done on various aspects of portable programming’, and leaves the reader to follow up references for further information. Portable Programming by Peter J. L. Walk Pub~~~ed by MacMilIan Press. 141 pp. &5.9s.
Effective I~ technicalwriting Many technical people seem to be convinced that they cannot write. When reports have to be made, or programs documented, the standard of the work can be very low. Yet effective technical writing is a skill which can be learnt. It does not necessarily require a literary talent, but it does need a structured approach to collecting information, formatting it and presenting it in a style fit for its audience. J Van Duyn, a systems develop ment consultant in the USA, and lecturer in technical writing, has produced a book based on these precepts, showing how clear, effective writing can be achieved. She looks at systems studies, user manuals, progress reports, and policy and standards manuals. Writing sales proposals, and even articles for publication in computer journals are also covered. The book is full of useful advice, and is well set out itself, as an example of good presentation. There are plenty of examples for each point, and the topics range from general writing practice to how to put together specific reports, such as a systems study or a progress report. Always relate to your reader, says MS Van Duyn. Shun verbiage, but
~0124 no 7 September 1982
don’t mistake brevity for conciseness. Use direct, uncomplicated language, and always think of your audience. ‘A document will be rejected and all your efforts wasted, unless its personality satisfies its readers.’ This also means defining layout and content format standards at the start. In direct contrast to MS Van Duyn’s advice, in a wellknown computer company sales of&~, we developed an unhappy system for writing proposals or sales literature. One of the technical staff would produce the answers to the invitation to tender. The salesman in charge would then couch this in the sales language of ‘cost-effective’, ‘easytouse and ‘unique’ terminology, irrespective of the intended audience. Quite often his manager would then rewrite the document entirely in the most exotic language. He enjoyed using words that no one else knew. If MS Van Duyn writes truthfully, then this pair probably lost the company several contracts by not keeping to the rules of effective writing. As well as writing clearly, the author should present his work in an interesting manner. The methods available for presentation are fooked at here. For example, you can choose between the hierarchical, where an
overview is given followed by detail; or the spatial, where information is given in place order, according to physical location; or the chronological. Space is also given to the discussion of graphical representation. ‘It is axiomatic that one page ofgraphics can replace many pages of conventional, sometimes tedious text and succeed in making the subject clear ifnot interesting.’ MS Van Duyn is surprised at the of DP staff who use number o~anizational charts to present the structure of a company or department, but use text instead to describe projects, information flow, and even extensive hardware configurations. The first stage in technical writing is to define your audience. They need to be written to on the right level, so that they feel neither patronized nor confused by overwhelming technical detail. Then before the document is written, the following should be done: define the project gather the data get the most out of interviews check the software organize the collected data determine the document’s personality outline your material summarize your subject define the layout and content format standards. Several chapters then explain the information and format required for various documents, with plenty of samples. For an example of what is not effective writing, the author gives us this gem: ‘Action-oriented orchestration of innovative inputs, generated by escalation of meaningful ingenious decision-making dialog, focusing on viable intrastructure policy was the scenario of the meeting.’ The ProfesionaE’s Guide to Writing Eflective Tech&al ~o~rn~~~c~t~o~ by J Van Duyn. Published by WileyInterscience. 218pp. $38.
35
presently available for designing and writing portable programs. Particular attention is given to the languages ADA, COBOL. and FORTRAN 77, as the three languages which have been subject to fairly strict standards, and therefore are highly portable. He sees his book as ‘an account of all the work that has been done on various aspects of portable programming’, and leaves the reader to follow up references for further information. Portable Programming by Peter J. L. Walk Pub~~~ed by MacMilIan Press. 141 pp. &5.9s.
Effective I~ technicalwriting Many technical people seem to be convinced that they cannot write. When reports have to be made, or programs documented, the standard of the work can be very low. Yet effective technical writing is a skill which can be learnt. It does not necessarily require a literary talent, but it does need a structured approach to collecting information, formatting it and presenting it in a style fit for its audience. J Van Duyn, a systems develop ment consultant in the USA, and lecturer in technical writing, has produced a book based on these precepts, showing how clear, effective writing can be achieved. She looks at systems studies, user manuals, progress reports, and policy and standards manuals. Writing sales proposals, and even articles for publication in computer journals are also covered. The book is full of useful advice, and is well set out itself, as an example of good presentation. There are plenty of examples for each point, and the topics range from general writing practice to how to put together specific reports, such as a systems study or a progress report. Always relate to your reader, says MS Van Duyn. Shun verbiage, but
~0124 no 7 September 1982
don’t mistake brevity for conciseness. Use direct, uncomplicated language, and always think of your audience. ‘A document will be rejected and all your efforts wasted, unless its personality satisfies its readers.’ This also means defining layout and content format standards at the start. In direct contrast to MS Van Duyn’s advice, in a wellknown computer company sales of&~, we developed an unhappy system for writing proposals or sales literature. One of the technical staff would produce the answers to the invitation to tender. The salesman in charge would then couch this in the sales language of ‘cost-effective’, ‘easytouse and ‘unique’ terminology, irrespective of the intended audience. Quite often his manager would then rewrite the document entirely in the most exotic language. He enjoyed using words that no one else knew. If MS Van Duyn writes truthfully, then this pair probably lost the company several contracts by not keeping to the rules of effective writing. As well as writing clearly, the author should present his work in an interesting manner. The methods available for presentation are fooked at here. For example, you can choose between the hierarchical, where an
overview is given followed by detail; or the spatial, where information is given in place order, according to physical location; or the chronological. Space is also given to the discussion of graphical representation. ‘It is axiomatic that one page ofgraphics can replace many pages of conventional, sometimes tedious text and succeed in making the subject clear ifnot interesting.’ MS Van Duyn is surprised at the of DP staff who use number o~anizational charts to present the structure of a company or department, but use text instead to describe projects, information flow, and even extensive hardware configurations. The first stage in technical writing is to define your audience. They need to be written to on the right level, so that they feel neither patronized nor confused by overwhelming technical detail. Then before the document is written, the following should be done: define the project gather the data get the most out of interviews check the software organize the collected data determine the document’s personality outline your material summarize your subject define the layout and content format standards. Several chapters then explain the information and format required for various documents, with plenty of samples. For an example of what is not effective writing, the author gives us this gem: ‘Action-oriented orchestration of innovative inputs, generated by escalation of meaningful ingenious decision-making dialog, focusing on viable intrastructure policy was the scenario of the meeting.’ The ProfesionaE’s Guide to Writing Eflective Tech&al ~o~rn~~~c~t~o~ by J Van Duyn. Published by WileyInterscience. 218pp. $38.
35