|
||
-- "You're the voice" by John Farnham |
These notes should help contributers to adapt their writing to the format fo sci-BOT. The first part, Section 9.1, treats stylistic problems, the second, Section 9.2, technical matter.
We do not require a contributor to follow Strunk and White's, "The Elements of Style" [Strunk:1979], though it is not a bad idea for any author to study this classical book on writing well. Instead here is some general and simple advice for writing. The following list is an edited excerpt from the author instructions of the American Institute of Physics.
Consider the beauty and efficiency of simple declarative sentences as the perfect medium for communicating complex information. Avoid long sentences in which the meaning may be obscured by complicated or unclear construction.
Avoid vague and inexact usage. Be as qualitative as the subject matter permits. Avoid idle words; make every word count.
Do not assume that your reader has all the background information that you have on the subject matter. Make sure your argument is complete, logical, and continuous.
Be rigorously self-critical as you review your first drafts, and ask yourself: "Is there any way in which this passage could be misunderstood by someone reading it for the first time?"
Some very good hints come from an article of George D. Gopen and Judith A. Swan [Gopen:1990]:
Follow a grammatical subject as soon as possible with its verb.
Place in the "stress position" the new information you want the reader to emphasize.
Place the person or thing whose "story" a sentence is telling at the beginning of the sentence, in the topic position.
Place appropriate "old information" (material already stated in the discourse) in the topic position for linkage backward and contextualization forward.
Articulate the action of every clause or sentence in its verb.
In general, provide context for your reader before asking that reader to consider anything new.
In general, try to ensure that the relative emphases of the substance coincide with the relative expectations for emphasis raised by the structure.
Always bear in mind that sci-BOT is a DocBook document, which means that
it is stored in machine readable format,
its HTML output is viewed online with a multitude of different browsers, and
its PostScript® or PDF output will be printed on paper with black-and-white printers.
Item i enables the author to make extensive use of cross-references (<xref>), preferably in both directions. Furthermore, authors should make heavy use of the automatic index generation (<indexentry>). <xref>s can go everywhere in the running text, but <indexentry>s should only go into chapter or sectionN elements even if this separates the indexed term form the index entry.
The different output media, as mentioned in item ii and iii, require that all included graphics are provided in at least two formats, one suitable for online viewing and the other for high resolution (assume at least 720 dpi) monochrome printouts.
FIXMEs. Probably has seen several almost empty sections marked with "FIXME" and some comment following it. These markers are a good thing. They remind the author[s] that the discussion is still incomplete, but the missing part has been identified and sits already in the right section. On the other hand, a "FIXME" tells the reader that the author is aware of a gap in the flow of information, and is probably working on it.