Archive for the 'Documentation' Category

60. Punctuation — Part 1

Tuesday, June 26th, 2007

Tedious thought it may seem, the only way to master punctuation properly is to go through the elements of it one by one. The rules are not quite as onerous as most of us remember from our schooldays. In fact they’re great fun if we approach them in the right spirit of enterprise.

To command the dizzy heights of superior punctuating, only twelve elements need to be learned. Grasp these and you are in control. One hour of your time and you’ll be master of the dot in dotcom, if nothing else.

Enough of the pep talk, let’s get down to business.

Full stop
Or “point” in American. This minuscule entity ends all sentences which don’t end with a question mark or exclamation mark. The next character is usually a capital letter.

It can also be used for abbreviations: etc. or e.g.

After a quotation, the full stop goes inside the quotation marks if the whole sentence is the quote; outside the quotation marks, if the quote is only a part of the sentence.

Comma
Of all the objects in the world of punctuation, the comma is the most problematical. Placing this curiously attractive little entity in a sentence is a minefield of rules and, even worse, opinions. The old-school, rather disciplinarian approach, was to place a comma at every point where there was a natural pause for breath. Nowadays, whole texts seem to rush by with scarcely a comma to be seen. The latter solution is clearly unsatisfactory because it results in much ambiguity of meaning. The following is a fairly comprehensive guide to comma usage using the system suggested by Oxford University.

a) Between similar qualifying adjectives: “An abstemious, taciturn woman.”
But if there is no similarity, there is no comma: “A dull grey shirt.” Just think list. Abstemious and taciturn are a short list of qualities pertaining to the woman. Whereas dull and grey are different qualities; indeed a form of grey might well be described as dull. It’s clearly not a list.

b) Separating items in a list: “Books, CDs, and videos.” The comma after CDs is sometimes omitted. It’s often known as the “Oxford comma”.
Exception: “A black and white picture.” Where black and white form a recognisable phrase rather than a list. Black and white could be changed to monochrome. “Books, CDs” is not reducible because it is a list.

c) Separating co-ordinated main clauses: “Residents to the left, visitors to the right.”
Exception — when they are closely allied: “Listen to me and you might learn something.”

d) For parenthetical words/phrases: “If you do go, however, you may regret it.” Or “The man, who was not strong, soon gave up.”
Exceptions — restrictive relative clauses: “People who are short should wear high heels.”

e) Following participial or verbless clauses. “Having gone for a walk, I felt a whole lot better.” “The concert over, the audience left.”
Exception — “My daughter Mary.”

f) A separating comma is used to avoid misunderstanding: “From the houses above, the church seemed very small.” Otherwise you would read: From the houses above the church
followed by the meaningless “seemed very small.” These nuances can be very important, especially in technical writing where unclear instructions could lead to danger.
Exceptions: do not use a comma to separate a verb from an object that is a clause: “They thought, that they had it made.” is wrong, as is a comma used to separate a phrasal subject from its predicate: “A man with great strength, should always be careful of others.”

g) Use after words which introduce quoted speech: “He shouted, ‘Watch your back!’”

h) In letters following Dear Susan, Dear Sir, &c., and after Yours faithfully, etc.

But it’s not necessary following a number in an address, e.g. “10 Downing Street”; or between month and year in a date, e.g. “October 2001”.

Semicolon
A comma is the least emphatic break in a sentence. If there is a need for a more distinct break, but not sufficient for a new sentence — always a hair-line decision — a semicolon is mustered. Usually the semi will divide clauses of equal importance and similar grammatical construction, e.g. “Waking is a pleasure; sleeping on even better.” It may also be used in a sentence where commas are already employed, but where a stronger break is called for, e.g. “They approached quickly, though with some trepidation, and took stock of the situation; but decided it was none of their business.”

Colon
a) The colon connects two grammatically complete clauses where the second represents a step forward from the first, or gives further explanation, e.g. “The idea had widespread support: the merging of the two groups would improve finances.”

b) To introduce a list: one, two, three. Or after expressions, “For example”, “the following”, &c.

c) For an emphatic, formalized introduction to speech, “He emphasised: ‘Don’t do it!’”

Next: 61, Punctuation — Part 2.

56. Reinforcements – Final Draft

Saturday, March 17th, 2007

Final draft
Copy preparation: The following points should be observed when preparing copy for the typist or compositor:

* Use double spacing
* Type or print on one side of the paper
* Be legible
* Number each sheet consecutively
* Circle keying instruction so that they don’t become part of the text
* Conform to house style.

Cast off: Estimating the length of a document in terms of pages. Word processor packages, like MS Word, will give you the number of characters and words. No-one manually estimates these now.
Prelims: Preliminary pages. These may be:

* Half-title page
* Half-title verso
* Title page
* Title verso
* Preface/foreword
* Contents list
* List of illustrations.

End pages: The final pages in a book following the body text:

* Conclusions
* Postscript
* Glossary
* Notes/references
* Appendixes/annexes
* Bibliography
* Index.

Production Phase

Proofreading
Types of proof: There are three types of proof in the traditional printing process:

* Galley proofs
* Page proofs
* Machine proofs.

There is also an intermediate stage of proofing referred to as “page-on-galley” proofs. The first two categories indicate the textual arrangement of the type, but not the final print finish. The machine proof approximates this quality.
Corrections at proof stage: Two types of correction are acknowledged by printers:

* Compositors’ errors corrected by printer or author.
* Author’s corrections indicated during proofreading.

The first are usually made gratis, but the second may be limited to 10% of the total cost of composition.

Next : 57. Reinforcements - Printing

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.

52. Outline and Design Phase

Wednesday, January 3rd, 2007

Requirement
Identification of requirement: The adjacent points identify the key areas in eliciting a client’s requirements:

* Specification
* Target readership
* Deadline
* Information available
* Maintenance philosophy
* Subcontractors involved
* Commercial parts incorporated
* Author’s contacts
* Validation procedure
* Editorial procedure
* Documentation meetings.

Specification
Specification is a document prepared by an authority as a basis for the production of technical literature. In addition, we use this term to cover the format, length, and presentation of the document. As well as British Standards, there are many military and civil specs.

Outline design
The outline design anticipates:

* The information an author will need
* The synopsis of the document
* The cost estimate of the work to be done.

It summarises both the specification and the requirement, and looks forward to the sources and type of data that will be needed.

Sources of information
Types of information: Information may come in three ways:

* Printed information
* Verbal information
* Visual information.

The British Library: The national library of Great Britain which has a number of branches useful to the technology researcher.
Classification system: Methods — numeric or alpha-numeric — of allotting to publications a specific classification which distinguishes them from others.
Information search sequence: The following step by step sequence outlines a logical procedure for researching information at a library:

1. Establish subject areas and terminology.
2. Extract classifications from library catalogues.
3. Search index and directories for relevant publications.
4. Order publications not available at library.
5. Compile bibliography of the subject for further research.
6. Consult periodical indexes for state of the art data.
7. Obtain details of trade papers and journals from press guides.
8. Make list of relevant research organisations.
9. Examine year books for appropriate standards and specs.
10. Look through Patent indexes for useful information.

Universal Decimal classification: A ten-point classification system of which Class 6 refers to Applied Science and Technology, and 62 covers Engineering Sciences.
Library of Congress classification: An alpha-numeric method used to classify the publication stock of the US Library of Congress.
International Standard Book Number: A number prefaced by ISBN and found usually on the history page of most published books. Used extensively in computerised and tele-ordering systems.

To be Continued

Next: 53. Outline and Design Part 2.