Archive for the 'Research' Category

53. Outline and Design Part 2

Wednesday, January 10th, 2007

Contacts
Points for approaching a contact:

* Areas needing clarification
* Queries on modifications
* Technical interpretation
* New information.

A visit should accomplish:

* Points answered
* Queries clarified
* Equipment examined
* Way paved for next stage.

Meetings
Chairman’s main considerations:

* Is meeting necessary?
* Who should come?
* Are they available?
* Subject of discussion?
* What is to be achieved?
* Start/finish times?
* Venue?
* Advance information?
* Supplementary topics?

Agenda
The agenda of a meeting will usually contain:

* Place, time, and date
* Subject
* Order of discussion
* Other business.

Next: 54. Outline and Design Part 3.

51. Reinforcements: The Field

Tuesday, November 21st, 2006

Manuals
Level of readership: Technical manuals are produced for the skill level of the reader/user. There are at least three levels for maintenance handbooks:

* Simple maintenance
* Technical maintenance
* Workshop technical maintenance.

Customer support documentation: All literature written with the aim of providing a customer with accurate, up-to-date information about a particular product.
Specification: Detailed description of a product. A document prepared by an authority as a basis for the production of a technical manual.
BS4884: British Standard specification for technical manuals. Uses a nine-category system of book organisation.
Synopsis: A document, varying in detail, providing a summary of the contents of a book or document. Typically it contains chapter headings, subheadings and subject breakdown. It may also include a page count and/or an estimate of the number of paragraphs. A list of illustrations is usually provided. Useful for costing and organisation of material.
Vetting: A technical check on draft material.

Reports
Product documentation: Literature which provides information on a product and its progress.
Purposes of a report: To give an account of a subject. To arrive at a basis for discussion. To reach a conclusion. To plan further action. To make recommendations. To disseminate data. To provide a record or reference.
Subject-orientated report: Divided into topics or subject groups.
Chronological report: “Real-time” record of events or progress.
Conceptual report: Abstract or philosophical aspects of a subject.
Main features of a report: Title, contents, aim, summary, body of document, conclusions, index.

Technical articles
Article: Compact piece with a central point or theme.
Angle: Journalistic term relating to the orientation of an article in terms of its subject matter.
An article requires: Organisation — construction allowing the reader maximum access to the subject; and Readability — quality of a piece of writing that maintains a reader’s interest throughout.

Technical sales literature
Glossy: A brochure produced on high-quality paper with coloured illustrations, and which attempts to maximise the sales of a product or service.
Motif: A theme or recurring logo linking the pages of a book.
Visuals: “Roughs” or visuals are a dummy copy of a brochure sketched out by a graphic artist.

Technical training material
Programmed learning package: A collection of aids, usually “mixed-media”, structured for layer-type or reinforcement learning. The aim is to administer a measured quantity of information in fixed units of time.
Reinforcement learning: A spin-off of Pavlov’s classic conditioning experiment on dogs, but this time aimed at humans. Reinforcement is achieved by ingenious repeating techniques, using data which may be subtly veiled to make it more palatable to a modern audience.

Software documentation
Software: Anything in a computer system not definable as hardware: the programs, operating system, compilers, utilities and documentation.
Program maintenance: The act of patching or fixing a program when a bug is found. In practice, there is no way of testing every loop and procedure in a long, complex program. Consequently, errors may be constantly discovered in even the most mature software. The documentalist annotates programs in such a way as to provide maximum assistance for subsequent maintainers.
Stages of software development: As any other technical product: requirement, specification, system design, software system design, program design, implementation, integration, acceptance testing, maintenance &c.

Next: 52. Outline and Design

50. Afterword

Thursday, November 9th, 2006

Fritjof Capra, in his book The Tao of Physics, explains the task of a technical writer as follows: “The notion that all scientific models and theories are approximate and that their verbal interpretations always suffer from the inaccuracy of our language was already commonly accepted by scientists at the beginning of th 20th century, when a new and completely unexpected development took place. The study of the world of atoms forced physicists to realise that our common language is not only inaccurate, but totally inadequate to describe the atomic and sub-atomic reality. Quantum theory and relativity theory, the two bases of modern physics, have made it clear that this reality transcends classical logic and that we cannot talk about it in ordinary language.”

That this theoretical sophistication will eventually filter through to the down-to-earth concepts of engineering is certain, and has probably happened already. As science continually reassesses itself in terms of its wider implications, engineering too will need to adapt to the new complexities and possibilities. Language will be forced to expand and develop in an attempt to remain abreast of the new philosophies. Even simple technical descriptions, essential for complete understanding, will need to reflect the depth of theoretical complexity inherent in modern devices.

Technical writers of the near future will be resourceful individuals. They will need to span disciplines even more than they do now. But while techniques move on, and change is there to be described, they will survive. And, with a bit of luck, prosper.

Next: 51. Reinforcements - The Field.

48. Copyright

Thursday, October 12th, 2006

Until recently, British copyright lasted for fifty years beyond the author’s death. Now, this has been extended by the EU to seventy years. There is support too for efforts to secure a decent return from those who would readily exploit an author’s work without paying for it. Photocopying used to be a licence to save money. Hardly anyone thought twice before reproducing articles, chapters from books or even a whole book without reference to the copyright holder.

There are now agreements with education and commerce on a licensing scheme for reprographic rights. Whether or not a similar scheme can be applied to electronic rights depends largely on developing an effective policing policy. Reports are already filtering through the technological grapevine of new metering systems which will allow publishers to monitor and record the use of their information on the Internet and other networks. In early 1997, the World Intellectual Property Organisation, the UN’s agency responsible for administering copyright conventions, required member states to outlaw devices aimed at bypassing technical measures to prevent unauthorised copying.

Meanwhile, there is much that the individual writer can do to guard against the free use of what is, or what might turn out to be, a valuable property. The starting point is the small print of the contract.

One unnecessary fuss over copyright, centred on a scheme launched by Simon & Schuster, followed by Macmillan and Wiley, “to keep works of academic value in print on a permanent basis” by printing on demand. (Modern digital printing techniques allow works to be stored on disk, updated frequently, and printed off “just in time” to the customer’s order). The drawback, from an author’s point of view, is that while under current rules if a book goes out of print for more than eight weeks the copyright in the text reverts to the author, this print-on-demand initiative could be used by a publisher to hold onto these rights. The issue will doubtless be decided eventually by combat between expensive lawyers. Meanwhile, we can only wonder at the further confusion over who owns what created by the new technology. In the Far East it is reckoned that over 90% of all videocassettes sold are pirated. Unauthorized printing of books in China, Russia and a motley of smaller nations is said to be depriving British publishers and their authors of £200m a year. As for the photocopier, it’s now responsible for some 300 billion pages of illegally reproduced material.In most books a copyright notice appears on one of the front pages. In its simplest form this is the symbol © followed by the name of the copyright owner and the year of first publication. The assertion of copyright may be emphasised by the phrase “All rights reserved”, and in the case there are any lingering doubts the reader may be warned that “No part of this publication may be reproduced or transmitted in any form or by any means without permission”.

But this is to overstate the case. In principle, a quotation of a “substantial” extract from a copyright work or for any quotation of copyright material, however short, for an anthology must be approved by the publishers of the original work. But there is no fixed rule on what constitutes a substantial extract. In any case, even a lengthy quotation from a copyright work may not be an infringement if it is “fair dealing”…for purposes of criticism or review”.

Difficulties can arise when the identity of a copyright holder is unclear. The publisher of the relevant book may have gone out of business or been absorbed into a conglomerate, leaving no records of the original imprint. Detective work can be yet more convoluted when it comes to unpublished works. When copyright holders are hard to trace, the likeliest source of help is the Writers and their Copyright Holders project, otherwise known as WATCH. A joint enterprise of the universities of Texas and Reading, WATCH has created a database of English-language authors whose papers are housed in archives and manuscript repositories. The database is available free of charge on the Internet. If, despite best efforts, a copyright holder cannot be found, there are two options: either to cut the extract or to press ahead with publication in the hope that if the copyright holder does find out he will not object or will not demand an outrageous fee. The risk can be minimized by an open acknowledgement that every effort to satisfy the law has been made.

With the 1988 Copyright Designs and Patents Act, the European concept of “moral rights” was introduced into British law. The most basic is the right of “paternity” which entitles authors to be credited as the creators of their work. However, paternity must be asserted in writing and is not retrospective. No right of paternity attaches to authors of computer programs, or to writers who create works as part of their employment, or journalists, or as contributors to a “collective work”, such as an encyclopaedia, dictionary, or year book.

A second moral right is that of integrity. In theory, this opens ways to forceful objections to any “derogatory statement” if derogatory amounts to “distortion or mutilation … or is otherwise prejudicial to the honour or reputation of the author”.

Moral rights may “be waived by written agreement or with the consent of the author”.

Writers trying to sell ideas should start on the assumption that it is almost impossible to stake an exclusive claim. So much unsolicited material comes the way of publishers and script departments, that the duplication of ideas is inevitable. A writer who is nervous of the attention of rivals is best advised to maintain a certain reticence in dealings with the media.

Next: 49. Contracts.