1 Revision Information

This document is currently at revision level:
 $Id: CSE-1402-W-2001.tex,v 1.1 2001/07/09 22:00:41 carlo Exp carlo $

2

3

3.1 Proverb:

3.2 Observations:

1. Death certificates are a form of documentation.
2. Tax records are a form of documentation.
3. The earliest forms of documentation kept by all known civilisations were - taxation records.

3.3 Conclusion:

4 Unit Objectives (Writing Technique):

• Types of documentation and tools.
• Software life cycles.
• Hard copy vs online documentation.
• English grammar in documentation.
• English style in documentation.
• Software product proposals.
• Software product specifications.
• Commenting source code.

5 Unit Objectives ...

• Technical manuals.
• Reference manuals.
• Advanced user manuals.
• Beginner user manuals.
• Marketing literature.
• Reports and surveys.
• Team documentation writing.
• Writing research papers and white papers.

6 Unit Objectives (Tools):

• Documentation file types.
• Printing - Postscript and PDF.
• Graphics files - GIF, JPEG, CGM, DXF ...
• Source files - TeX, DOC, TXT, ...
• Using template files.
• Text Editors, Manual pages (vi, emacs), text formatters (nroff).
• Spell checkers.
• Documentation revision management - RCS.
• Typesetters (troff, TeX, LaTeX).

7 Unit Objectives ...

• Word Processors (StarOffice, Word) & DTP (Frame).
• Graphics (xfig, gimp, xv, Photoshop).
• Introduction to LaTeX (several lectures).
• Markup Languages (GML, SGML, HTML, XML).
• Hypertext - HTML, XML and PDF.
• HTML Documentation & W3 publishing.

8 Why is Documentation Important?

• Documentation is the means via which we record information.
• Documentation allows more than one person to work on a complex project.
• Documentation provides continuity in a project, since the loss of personnel does not stop a project.
• Documentation is central to every phase of a software project, and to the life cycle of the software product.
• Documentation provides a means of defining the intent, function, and attributes of a software product.

9 Problem Issues in Documentation

• Documentation is frequently “undervalued” in industry, as is the ability to perform it well.
• Documentation tasks are frequently not respected for their complexity, difficulty and required skills.
• Is there a price to be paid for this?
• Poor documentation frequently becomes the cause of major project failures.
• Examples: Mars Pathfinder probe and Ariane 5 booster disasters due to poorly documented software.
• Poor documentation is a frequent cause of catastrophic failures, as it underpins many “human error” problems in software and system design.

10 Problem Issues in Documentation

• Extremely complex systems must be rigourously documented at every level, otherwise mistakes will arise since people will “assume” the function of components, rather than “know” the function by having studied the documentation.
• A failure to properly invest in documentation can bankrupt companies or cost lives.
• Documentation tasks can consume as much time as the software programming effort itself.
• The ability to perform the software test function is itself critically dependent upon documentation.
• Documentation is the central point of reference for all other tasks in software development.

11 Documentation vs Software

• Software specifications must be documented, otherwise the product cannot be defined and thus properly implemented.
• Software test specifications must be documented, otherwise the product cannot be tested and its function proved against the product specification.
• Bugs and errors must be documented, otherwise programmers cannot replicate the problem and fix it.
• Design changes to the product must be documented, otherwise the product cannot be maintained and its behaviour might be seen to be unpredicable by users.

12 Electronic vs Hardcopy Documentation

• Hardcopy documentation today uses print media, such as paper or plastic sheet.
• Until the 1960s, all documentation was hardcopy.
• The author would type or hand write the document, and typesetters would then produce master plates for use in a printing press. A printing press would then be used to produce the document in volume.
• Pictures and diagrams had to be lithographically transferred to the printing plates.
• Low volume internal documentation was often handwritten or typed.

13 Evolution of Documentation Media

1. Clay paintings on stone - 30,000 B.C.
2. Stone reliefs - possibly 6,000 B.C.
3. Clay tablets - Sumeria 3,000 B.C.
4. Ink on papyrus and parchment - Egyptian, Greek, Roman civilisations.
5. Ink on parchments and paper - Medieval Europe.
6. Gutenberg’s “printing press” - Renaissance Europe.
7. Electronic typesetting - late 1970s.
8. Electronic publishing - late 1980s.
9. World Wide Web - 1993.

14 Weaknesses of Hardcopy Documentation

• Very labour intensive to produce, especially in volume, resulting in high costs.
• Changing hardcopy documentation is time consuming and expensive.
• The size and weight of hardcopy documentation makes it cumbersome to transport, especially over large distances.
• The durability of the “storage medium”, i.e. paper is often poor.
• High quality paper is an increasingly expensive resource, as the world’s forests are destroyed.
• Cost pressures, size, convenience will see hardcopy documentation replaced in most uses by electronic documentation.

15 Evolution of Electronic Media

1. Punch cards or magnetic tape for archival storage - 1950s.
2. Plain text on dot matrix or band printers - 1960s.
3. Word processors and markup languages - 1960s and 1970s.
4. WYSIWYG and laser printer - Xerox PARC 1970s.
5. Electronic typesetting (LaTeX) - 1970s.
6. Hypertext - 1980s.
7. Desktop computers with GUIs - 1980s.
8. World Wide Web - 1993.

16

17 Using English

• English is the most important tool you have when writing documentation.
• Modern English is the result of complex evolution over almost 2 millenia.
• The main varieties today are “UK/British/Standard English” and “American English”, which frequently use different spelling and pronunciation.
• Both “Standard” and “American” English come in a wide range of local dialects, each of which tends to use unique pronunciation and colloquialisms. If you are writing for an Australian audience, you must use “Standard” rather than “American” English, and vice versa. Beware of dictionaries in American spellchecking tools!

18 Texts

• You can find proper spelling in a dictionary. Many dictionaries also contain hints on grammar and style, and sometimes the origins and the preferred usage of words.
• Good dictionaries with preferred Australian spelling are the “Macquarie Dictionary” and the “Australian Oxford Dictionary”, both of which are available in pocket size editions.
• An excellent text covering English style is Strunk and White, “The Elements of Style”, published by MacMillan, also at
  http://www.bartleby.com/141/ .
• Students with an interest in the evolution of English should read “The Story of English”, by McCrum, Cran and MacNeil, published by Penguin.

19 The Origins of English

• The grammar and vocabulary of modern English is the result of mixing Germanic, Celtic, Latin, Norse and French influences.
• Britain, before the Roman invasion in BC 55, was occupied by Celtic tribes. These tribes spoke a Gaelic language, similar to what is spoken today in Ireland and parts of Scotland, Wales and Cornwall. Educated Britons of the period often spoke Latin.
• In AD 410 the Roman legions retreated from Britain as the Empire collapsed. In AD 449 Britain was invaded by tribes from Lower Saxony (Germany), Jutland (Denmark) and Frisia (Holland). These were the Angles, Saxons and Jutes.
• The Anglo-Saxon kingdoms were invaded in AD 793 by Norsemen (Vikings), who occupied the north of England.

20 Saxon, Frisian, Norse and Latin

• Some words with Saxon roots are sheep, here, swine, hound, field, laugh which in German are Schaf, hier, Schwein, Hund, Feld, Lachen.
• Some words with Frisian roots are lamb, goose, boat, rain which in Frisian are lam, goes, boat, rein.
• The greatest influence of the Norse was the simplification of grammar, since Anglo-Saxon was inflected. Prepositions like to, with, from are Norse in origin. Common Norse words are get, hit, leg, skin, want, wrong.
• The roots of modern English lie in these early Germanic languages.
• Christianity was reintroduced in AD 597. This brought a wide range of Latin words into the English language, especially words relating to religion.

21 French

• In AD 1066 French speaking Norsemen from France, the Normans, invaded and conquered Britain. French evolved from colonial Roman Latin, like Spanish, Portuguese, Catalan and Romanian.
• Britain was ruled by a Norman aristocracy, which spoke French, common people spoke English, and the church and academia spoke Latin.
• For 300 years English was only spoken by commoners, as the business of government and church were conducted in French and Latin.
• Much of the power and precision of modern English results from its huge vocabulary, which contains words with Anglo-Saxon, French and Latin roots. Very exact shades of meaning can be conveyed by using synonyms of Anglo-Saxon, French or Latin origin.

22 American English

• Australia and the United States, like New Zealand, Canada, South Africa, India, Pakistan, Malaysia and many other countries, are former British colonies. English has evolved its own unique styles in almost every one of these nations.
• Of all of the foreign varieties, we are most interested in American English, since most computing terms are American in origin.
• American English contains many words and colloquialisms which are not of English origin. During the 19th century, German was proposed as a second language. In 1990 Americans of German descent remained the single largest ethnic group in the USA.

23 Basics of English Style

• Planning. Before you draft your document, you must have a very clear idea of what the aim of the document is. What is it to say? Who will be reading it? What do they need to know? What do they already know? How should I best present the information?
• Put the reader first. It is always better to put things from the point of view of the reader, rather than your point of view. Write to the reader as though you were speaking in person.
• Choose your words carefully. Statistic: around 50% of the adult population in any developed country cannot understand any writing more complicated than a newspaper. Therefore you must always think of the reader’s limitations.

24 Basics of English Style

• Technical terms. Use technical terms you know the reader can understand, or introduce them and explain them.
• Avoid archaic or unusual words. How many readers understand words like heretofore, herein or aforementioned?
• Use everyday language. Your writing will be much easier to understand if the language you use is plain. The reader will be busy enough trying to understand the ideas you are presenting, without having to decipher difficult language.

25 Examples:

1. “Should you require further assistance” against “If you need more help”.
2. “Prior to and following” against “Before and after”.
3. “Upon accessing the menu” against “When you access the menu”.

26 Basics of English Style

• Use short sentences and brief paragraphs. Try to use short sentences where possible. Put one or at most two ideas in each sentence. If you need to explain a term or a point, use another sentence.
• Never sacrifice clarity for brevity. Making a sentence short does not mean it is clear. Ambiguous sentences will confuse readers. Make your sentences as short as you can, but use extra words if needed to make sure it can be clearly understood.
• A paragraph should contain one central idea. Organise your paragraphs so that each contains one central or basic idea. Avoid trying to put too much into one paragraph, since it will distract the reader.

27 Basics of English Style

• Avoid repetition and redundancy. Repeating the same idea twice in a sentence, or a paragraph, is clumsy. Using the same word too frequently is also cumbersome, a suitable synonym is preferable.
• Use active rather than passive voice. Some readers may become confused by the use of passive voice. Example: “The algorithm will be executed to yield the result” against “The CPU will execute the algorithm to get the result”.
• Avoid a tendency to over-capitalise. Modern writing uses capitals only where necessary. Some readers may be intimidated by the formality of excessive capitals. Example: “The Internet has in part produced the Digital Divide”.

28 Ambiguity

• Ambiguity is one of the most frequent problems which we find in documentation, professional writing, papers, and journalism.
• Ambiguity means the reader is left guessing about the meaning of the sentence.
• Ambiguity is a very frequent problem in student exam papers, causing the loss of marks, since the examiner cannot determine what the student meant.
• Example (1): explain the meaning of this sign which was used in the London subway: “Dogs must be carried at all times”.
• Example (2): explain the meaning of “If your baby does not like spinach, try boiling it in milk”.

29

30 Why Grammar?

• Poor use of grammar can result in documents which confuse or annoy the reader. Confused or annoyed readers may run out of patience and refuse to read the document further, thereby defeating the effort you put into producing the document.
• Poor grammar reduces your credibility in the mind of the reader. If the reader thinks you are illiterate or incompetent, they will be much less inclined to accept what you are saying in your document.
• Poor grammar reduces your credibility in the workplace, and this can often reflect in the level of responsibility and thus rewards which your employer is prepared to give you.
• If you want to sink your career in industry, using poor grammar really helps!

31 Grammar Guide

• This grammar guide is not a comprehensive discussion of every aspect of English grammar. It is a “survival guide” to provide students with a quick and basic reference.
• More detailed grammar references are available, on the web and as textbooks.
• A good reference is the “Oxford Dictionary of English Grammar” by Chalker and Weiner.
• Handy web references are at
  http://www.englishinstitute.co.uk/
  http://www.eslcafe.com/search/Grammar/ .

32 The Definite Article - the

• The determiner ‘the’ is typically used before a singular or plural noun, when the noun is familiar or previously mentioned. Example: The processor and the memory in the machine.
• Exception A: uncountable nouns with general meaning, e.g. the vector graphic engine performs calligraphy.
• Exception B: the name of a language, e.g. French, German.
• Exception C: names of countries, e.g. Australia, Britain.
• Exception D: days of the week, e.g. Monday, Tuesday.
• Exception E: names of meals, e.g. dinner.

33 The Definite Article - the

• Exception F: names of people, e.g. Ken Ritchie, Bill Joy.
• Exception G: names of towns, places, buildings, e.g. Melbourne, Monash.
• Exception H: some nouns, e.g. the student studies at university.

34 The Indefinite Article - a, an, some

• The indefinite article is used with singular and plural nouns, where these are general. e.g. a processor, an algorithm, some loop iterations.
• Usage: ‘a’ is used with a noun which starts with a consonant, e.g. a processor, a loop, a document.
• Usage: ‘an’ is used with a noun which starts with a vowel, e.g. an algorithm, an idea, an exception.
• Usage: ‘some’ is used with a plural noun, e.g. some algorithms, some loops, some processors.

35 Nouns

• A noun is traditionally defined as a ‘name of a person, place or thing’, and can function as a subject or an object in a sentence, and can be preceded by articles, adjectives and prepositions.
• Nouns can be countable, uncountable, collective.
• Countable nouns can be counted and have a plural form, produced by adding ‘s’ to the singular noun, e.g. one algorithm, two algorithms.
• Uncountable nouns cannot be counted and have no plural form, e.g. soap, glue (N.B. in technical language this may vary as the noun may be used as name).
• Collective nouns are either plural or singular, describing groups or collections of objects, people, or animals, e.g. a crowd of programmers, a herd of cats.

36 Exceptions to Countable Nouns (1)

• those with masculine and feminine forms, e.g. actors, actress.
• those ending with ‘s’, ‘sh’, ‘ch’ and ‘x’, e.g. lens, lenses, pass, passes.
• some nouns ending with ‘f’, e.g. half, halves.
• nouns ending in ‘fe’, e.g. knife, knives.
• nouns ending in ‘y’ after a consonant, e.g. foundry, foundries.
• nouns ending in ‘y’ after a vowel, e.g. key, keys.
• some nouns ending in ‘o’ may have plurals with ‘s’ or ‘es’, e.g. tomato, tomatoes, dynamo, dynamoes.

37 Exceptions to Countable Nouns (2)

• those which do not add ‘s’ to the plural, e.g. aircraft, media.
• names of animals and fish, e.g. sheep, fish, deer.
• nouns with no plural form, e.g. means, contents, pliers.
• compound nouns where the plural ‘s’ is attached to the first word, e.g. editor-in-chief, editors-in-chief.
• nouns which add consonants, change vowels, or add ‘en’, e.g. foot, feet, child, children, louse, lice.
• some nouns ending in ‘x’ or ‘ix’, e.g. appendix, appendices, index, indices.
• some nouns of French origin, e.g. bureau, bureaux.

38 Personal Pronouns

• Pronouns can replace some nouns in sentences.
• Pronouns are personal, reflexive, demonstrative and possessive.
• Personal pronouns such as I, you, he/she/it, we, you, they can replace a noun as the subject in a sentence, e.g. Mary wrote the code; she wrote the code.
• Personal pronouns such as me, you, him/her/it, us, you, them can replace a noun as the object in a sentence, e.g. The manager talked to Mary ; The manager talked to her.
• Personal pronouns such as me, you, him/her/it, us, you, them can replace a noun as the indirect object in a sentence, e.g. The manager gave Mary a task; The manager gave her a task.

39 Reflexive, Demonstrative and Possessive Pronouns

• Reflexive pronouns such as myself, yourself, himself/herself/itself, ourselves, yourselves, themselves can be used in two ways, e.g. Mary wrote herself some code; Mary herself wrote the code.
• Demonstrative pronouns such as this, these, that, those are used to refer to objects or people in relationship to the writer, e.g. Mary despised that bit of code.
• Possessive pronouns such as mine, yours, his/hers/its, ours, yours, theirs show that object/person belongs to somebody, e.g. Mary devised an algorithm and its was hers.

40 Adjectives and Comparisons

• Adjectives are used to add further information describing a noun, e.g. the slow algorithm, the dopey programmer.
• Adjectives are always placed just before the noun they describe, e.g. the unlucky code-cutter.
• Adjectives do not agree with the gender of the noun they describe, e.g. the argumentative woman, the argumentative man.
• Do not confuse some adjectives ending with ‘ly’ with adverbs, e.g. friendly (chat), lovely (actress), early (completion), daily (backup), hourly (complaint), weekly (insult), monthly (complaint), yearly (cull).
• The forms adjective, comparative and superlative compare nouns, e.g. a 100 MHz CPU is fast, a 233 MHz CPU faster, a 1 GHz CPU fastest.

41 Full Verbs

• Full verbs are traditionally described as ‘doing’ words, they can show contrasts in aspect, number, person, mood, tense and voice.
• Full verbs are usually divided into transitive, intransitive and linking verbs, and are/can be regular and irregular in how they form past tenses.
• Transitive verbs take a direct object, e.g. Mary was cutting code; the programmer denied the error.
• Intransitive verbs do not take a direct object, e.g. Mary worked toward her goal.
• Linking or copular verbs link a subject and a complement, the verb ‘be’ is the most common instance, e.g. Mary is a programmer; it seemed to be a good idea at the time.

42 Regular and Irregular Verbs

• Regular verbs form a past tense or past participle by adding ‘ed’ or ‘d’ to the base verb, e.g. look, looked, looked.
• Irregular verbs do not conform to the rules for regular verbs, e.g. see, saw, seen; put, put, put; fall, fell, fallen.
• N.B. there are very many irregular verbs in English which must be memorised!
• A good measure of poor English literacy is a propensity to confuse regular and irregular verbs.
• Tables of irregular verbs are frequently found in foreign language dictionaries.
• Many irregular verbs have Anglo-Saxon origins and similar forms to German irregular verbs.

43 Primary and Modal Auxiliary Verbs

• Auxiliary Verbs modify, change or assist the meaning of a regular or irregular verb.
• to be (primary): Present Continuous and Passive Tenses, e.g. Mary is talking to the programmer.
• to have (primary): Present Perfect and Past Perfect Tenses, e.g. Mary has never coded in LISP.
• to do (primary): questions and negatives in the Simple Present Tense and the Simple Past Tenses, e.g. Mary did not find the bug; did Mary find the bug?
• will/shall (modal): Future Tense, e.g. the team will finish the program.
• can/could (modal): describes an ability or willingness to do something in the present or in the past, e.g. Mary can program in C++; Mary can find the bug; Mary could write essays.
• may/might (modal): express a possibility now or in the future, e.g. if you code carefully, you may not have any bugs; if you are lazy, you might fail an exam.
• must (modal): obligation or necessity in the Simple Present and Future Tenses, e.g. you must use that compiler on this system; you must finish the program soon.
• ought to (modal): obligation or advice, e.g. you ought to use that compiler.
• would (modal): a situation/activity that is imagined, e.g. they would love to buy a 2 GHz processor.
• should (modal): an obligation or necessity where there is a choice, e.g. Mary should convince the manager.

44 Adverbs and Comparisons

• Abverbs modify or qualify a verb, an adjective, or another adverb.
• Verb: the program executed quickly.
• Adjective: a really buggy program.
• Adverb: the program executed really quickly.
• Adverbs can also convey manner, place, time and degree, e.g. hurriedly, there, soon and very.
• The forms adverb, comparative and superlative compare verbs, e.g. a 100 MHz CPU runs fast, a 233 MHz CPU runs faster, a 1 GHz CPU runs fastest.
• Irregular forms for comparisons: good, better, best; badly, worse, worst; far, farther/further, farthest/furthest.

45 Prepositions of Time and Space

• Prepositions of Time are used to the show the time and date of happenings.
• At: the manager started the meeting at 9 o’clock.
• On: the project budget ran out on the first of August.
• In: the program will crash in three hours.
• Prepositions of Space are used to the show the positions of objects, people and places.
• At: the programmers met at the pub.
• On: the heat-sink was installed on the chip package.
• In: the bug was in the third loop.

46 Tenses

• A tense is a form taken by a verb to indicate the time at which the action or state is seen to be occurring.
• English has arguably the most complex system of tenses in any modern language.
• Tenses allow for a very exact statement of relationships involving times and states, much more precise than in most other languages.
• The simplest division of tenses is into the past, present and future tenses. English has further divisions in its tenses.

47 Simple Present Tense

• The Simple Present Tense: actions that are continuing or happening repeatedly, e.g. Mary writes programs every day; do you enjoy programming?
• Exceptions: verbs which end with ‘y’ after a vowel or consonant.

48 Present Continuous Tense

• The Present Continuous Tense: actions that are happening now or for a limited time in the future, e.g. Mary is writing programs today; are you enjoying programming?
• Exceptions: verbs of ‘thinking’, ‘feeling’, ‘possession’, ‘reporting’ and some particular verbs, e.g. Mary understands this program; Mary wishes to finish the project; Mary owns a laptop; Mary says she is finished; the monitor weighs twenty kilograms.
• Negatives: the negation ‘not’ is placed after the auxiliary verb and before the verb ending with ‘ing’, e.g. Mary is not writing programs today.

49 Present Perfect Tense

• Form (1): activities or events recently completed, e.g. Mary has just written a program.
• Form (2): activities or events about to happen, e.g. Mary hasn’t written the program yet.
• Form (3): activities or events which started in the past and continue, e.g. Mary has always programmed in C++.
• Form (4): activities or events taking place up to now, e.g. Mary has never programmed in LISP.
• Negatives: not follows has/have, but precedes the verb.

50 Present Perfect Continuous Tense

• Form (1): activities or events which began in the past and are continuing, e.g. Mary has been programming for a month.
• Form (2): activities or events which began in the past and just completed, e.g. Mary has been programming and just finished.
• Form (3): ‘how long for?’ , e.g. Mary has been programming since she graduated.
• Exceptions: to be, have, hear, know, like, love, prefer, recognise, see, suppose, understand, want, wish.
• Negatives: not follows has/have, but precedes the verb.

51 Future Tense

• The Future Tense: actions that are to happen in the near or distant future. Four different forms can be used.
• will/shall with an infinitive: Mary will solve the problem today.
• Form (1): The Present Continuous of ‘to go’ with an infinitive: Mary is going to solve the problem today.
• Form (2): The Present Continuous with a phrase: Mary is planning to finish it later today.
• Form (3): let us or let’s in a question: let’s solve the problem today.
• Negatives: ‘not’ is always placed after will/shall and before the infinitive.

52 Simple Past Tense

• The Simple Past Tense: actions which happened in the past.
• Form (1): actions which happened in the past and are now completed, e.g. Mary wrote the program yesterday.
• Form (2): to describe past events, e.g. Mary entered the office and opened the drawer.
• N.B. irregular verbs are found in the Simple Past Tense.
• Negatives: ‘did not’ with an infinitive, e.g. Mary did not write the program.

53 Past Continuous Tense

• The Past Continuous Tense: actions which happened in the past.
• Form (1): actions which happened in the past over some time, e.g. Mary was writing the program yesterday.
• Form (2): actions which happened in the past while another action occurred, e.g. Mary was programming when the window broke.
• Form (2): reporting actions which happened in the past, e.g. Mary was programming and the manager was ranting when the computer crashed.
• Exceptions: verbs of ‘thinking’, ‘feeling’, ‘possession’ and some particular verbs.
• Negatives: ‘not’ goes after the auxiliary verb but before the full verb.

54 Syntactic Parsing

Parsing is a systematic technique for the analysis of a sentence.

55

56 Software Life Cycles and Documentation

• All software products have life cycles, during which they are defined, developed, modified, maintained and used.
• Documentation plays a vital role in every portion of the software life cycle, and cannot be separated from any portion of this process.
• Product Concept Definition is the very beginning of the SLC, during which the basic attributes of the product are thought out.
• Product Design Specification is the phase during which a system architect (or team of architects) produces a specification which describes the product in detail.

57 SLC and Documentation ...

• Product Development is the phase during which a programmer (or team of programmers) produces the code for the software product.
• Product Testing is performed during and after development, to find differences from the specification, bugs or other problems, so these can be fixed.
• Product Delivery is the phase during which the product is sold and the end user (customer) is supplied with a working product.
• Product Maintenance occurs concurrently with Product Delivery and requires the ongoing modification, removal of bugs, and incorporation of changes to the product requested by customers.

58 SLC and Documentation ...

• Specific types of documentation are required for each phase of the product life cycle.
• These documentation types must be written for specific types of readers, with specific styles and formats.
• The style, layout, composition and presentation of such documentation is frequently as important as the content, since poor choices can hide the message which you are trying to convey to the intended reader.
• For instance, a datastructure specification document written for a senior programmer would be wholly incomprehensible to an end user with little experience in using the product.

59 Presentation Media

• The medium used for presentation and distribution must also be well matched to the intended reader.
• For instance, an end user may want a fancy GUI based online viewing tool or an elaborate glossy manual, whereas a development programmer may prefer fast text based online documentation, or simple hardcopy which he or she can write on.
• Choosing the presentation medium poorly may also prevent your message from being properly absorbed by the reader. This is especially true for inexperienced readers who may not cope well with more complicated on-line viewing tools.

60 Types of Software Documentation

There are several basic types of document which are associated with each phase of the SLC:

• Product category surveys or reports.
• Product proposal or product concept definition documents.
• White papers.
• Software product specifications.
• Software test specifications.
• Source code comments and descriptions.
• Source code or product technical manuals.

61 Types of Software Documentation ...

• User manuals for beginners.
• Reference or user manuals for advanced users.
• Marketing and sales literature.
• Journal articles, academic or professional.

This subject will review each of these categories of documentation and discuss them in appropriate detail. Even if you will not be producing documents in a specific category, as programmers you may be required to contribute to their production, review them, modify them or assess them. Therefore you must understand their attributes, how to produce them and what problem issues may arise.

62

63 Reading

• Woolever, Chapters 1 through 5 contain detailed discussion of the material in this section. Students are advised to read through this material very thoroughly, as it will be referred to in later parts of the subject.
• Chapter 1 covers planning issues.
• Chapter 2 covers researching technique.
• Chapter 3 covers document organisation.
• Chapter 4 covers general document style issues.
• Chapter 5 covers the use of graphics in documents.

64 Document Planning

• One of the most common mistakes made by novice document writers is that of not planning the document properly.
• This is much like trying to write a program without having a clear idea of what it should do.
• Planning a document should be performed in a systematic manner, using a checklist of items which should be considered.
• The document must have a clearly defined purpose or set of aims.
• The document must be written around the idiosyncrasies of its intended audience.
• The document must use the appropriate writing technique and language.

65 Document Aims

• In the context of software documentation, the aims of specific types of documents are usually well defined by the type of document and established conventions.
• Example #1: a test specification will provide a detailed description of specific tests which should be performed on a piece of code, and what results these tests should produce.
• Example #2: a white paper will provide a general overview of the product, and may discuss many of its unique or special features in further detail.
• Example #3: comments inside a program source file are intended to explain the behaviour of the code to another programmer who needs to either alter the code, or fix a bug.

66 Document Aims ...

• Without a clearly defined purpose a document may ‘wander’, and thus dilute the message you are trying to convey.
• A document must always have a primary aim, but it may also have other aims.
• A primary aim for a white paper may be that of educating readers about a new family of products, a secondary aim may be that of impressing potential customers with how clever the product development team is, and a tertiary aim might be to embarrass a competing organisation.
• It is best not to attempt to change the aims of a document once you have written a large part of it, usually it is best to start a new document instead.

67 Analysing the Audience

• Understanding the abilities, needs and expectations of the intended readership is vital to successful document writing.
• Specific types of document will always be written for one or more categories of reader. Within these categories of reader, you may see a considerable variation in reader skills.
• The best technique for systematically analysing the intended audience is the use of a “checklist” or “grid”. This provides a framework for understanding the readership.
• It pays to be very thorough when analysing the audience, since getting it wrong can largely defeat the purpose of writing the document.

68 Audience Checklist

• Who will be reading the document? Are they programmers, managers, end users, customers etc?
• What do they need from the document? Is it to explain how something works, is it a tutorial, is it a reference document?
• What is their experience or skill level? Are they experts, users with some experience, complete beginners? Do they have a postgraduate degree, undergraduate degree or only a high school education?
• What prejudices or biases do they have? Are they “wedded” to particular vendors’ products and technical culture? Does their education or training predispose them to prefer particular solutions?
• What environment will the document be read in? Is it to be read while trying to debug a system under time pressure or otherwise?

69 Audience Checklist ...

• What is the readers’ job function? Are they technical workers, managers, administration workers or home users?
• What related documents may the readers be familiar with? Will they have read the manual for the previous release, or the beginner’s user manual, or a specification document?

 Some research may be required to fill out such a checklist, and it pays to look at the approach used by other writers. The best strategy is always that of interviewing some typical readers.

Beware of using too small a number of samples! Quizzing one or two readers may not give you an accurate picture of what a typical reader will be like.

You should also be cautious about using your peers as examples of typical readers, since they will mostly likely share your preferences.

70

71 Document Structure vs Planning

• Every document must have a basic structure of some type.
• The structure of the document is usually unique to a particular category of document. Examples: a software specification will differ in structure from a ‘white paper’.
• The structure must reflect the aims of the document, the audience and the type of document.
• Poorly structured documents can be very difficult to follow and many readers will find them very annoying to read.
• Document structure is best determined during the planning phase.
• Like document aims, it is often difficult to change the structure of a document once it has been written or largely written.

72 Typical Document Structures

What components must be included in every document?  

1. The name(s) of the author(s) and particulars.
2. The title of the document.
3. The name(s) of the publisher(s) and particulars.
4. Revision description and date.
5. ‘Sign Off’ table or list.
6. Table of contents if the document is large.
7. An introduction, abstract or other brief description of what the document is for.
8. One or more chapters or sections with content.
9. Appendices, glossaries, references, and indices in larger documents.

73 Author Name and Particulars

1. The author’s name should be complete, and preferably include middle initials. Abbreviating the first and middle name is usually acceptable.
2. Names and initials are always capitalised.
3. It is a common practice to include the author’s academic titles and job title.
4. Titles usually start with the lowest degree and end with the highest. Job titles usually come after academic titles, and may include the organisation name.
5. It is customary to include an email address with a name and titles.
6. In some documents, professional association membership is included.

74 Example Author Name and Particulars

Jane M. Doe, BSE(hons), MComp, MACM, MIEEE

SoftStuff Systems
janedoe@somewhere.null.org

75 Document Titles

1. Titles should be short, exact and complete. Long titles are cumbersome, ambiguous and incomplete titles are confusing.
2. A title may span several lines.
3. A common practice is to use a main title, and one or more subtitles in a more complex document.
4. The main title should include the name of the product discussed by the document.
5. Subtitles frequently explain the the main title, or describe the content or nature of the document.
6. Often the revision level or edition of a document is included in the title.

76 Document Title Examples

TROPPO Propagation Simulator: User Manual

TROPPO Propagation Simulator
User Manual
Technical Manual
Library Interface Manual

TROPPO Propagation Simulator
Technical Documentation, Third Edition.

77 Publisher

1. The information identifying the publisher should always be sufficiently complete to allow a reader to locate the publisher with no difficulty.
2. It is customary to include a complete or partial address, the latter where the publishing organisation is easy to find.
3. The name of the publisher should always be on the title page, address details may or may not be on the title page. Example: books frequently list only the name of the publishing house on the cover, and put the exact address on a dedicated second page.
4. It is a good practice to include copyright information, where applicable. Example: © 2000, Jane Doe, SoftStuff Systems.
5. Contemporary publications will often include the publisher’s URL.

78 Publisher Information Examples

CSSE, Monash University, Clayton

Computer Science & Software Engineering
Monash University
Clayton, 3800
Australia

Computer Science & Software Engineering
Clayton Campus.
© 2000, Monash University, Australia.

79 Date and Revision

1. Date and revision information is essential. A technical document without this information should always be considered “suspect”.
2. The simplest form of revision information and dating is a simple listing on the title page. Example: Rev 1.6.3 , 15th August, 2000.
3. It is a good practice with more complex technical documents to include either a revision page or pages, or an appendix or annex containing all prior revision information.
4. Proper use of the RCS system and the $Log: $ command can save a lot of time when producing documents using electronic media.
5. If the revision numbering of the document differs from that of the software, always ensure that a “mapping” list exists.

80 ‘Sign Off’ Tables or Lists

1. A ‘Sign Off’ table or list is a commonly used feature in most technical documents.
2. Its purpose is to show that all people participating in the production of the document have endorsed it as being complete and of satisfactory quality.
3. A minimal implementation will include the name of the author and the author’s supervisor.
4. More elaborate arrangements will have a list or table for each and every revision of the document.
5. Many Quality Assurance systems mandate the use of such lists or tables in every technical document.

81 ‘Sign Off’ Table Example

82 Tables of Contents

1. Large documents such as manuals, specifications, standards or reports require a table of contents (ToC).
2. Most good DTP, WP and typesetting packages can generate the ToC automatically, providing that we use the template properly.
3. The ToC should list at least all the chapters, appendices and other components of the document, it should number them and list the page on which they are located.
4. A more elaborate ToC arrangement will break down the sections in chapters and indent these by level.

83 Introductions, Summaries and Abstracts

1. The purpose of an abstract, summary or introduction is to familiarise the reader with the contents of the document.
2. Abstracts are usually found with simple documents such as papers or short reports.
3. More detailed introductions or summaries are customary with larger and more complex documents, such as reports, manuals or books.
4. Usually an abstract or summary should occupy no more than 400-500 words, or a typical page. An introduction may span several pages.
5. Such introductory descriptions should assume the reader has little or no familiarity with the contents of the document.
6. The aims and audience, if not implicit, should be identified.

84 The Body of the Document

1. The body of a document contains the detailed information which we wish the reader to absorb.
2. The structure of the body of a document varies with type. Large documents contain multiple ‘chapters’ or ‘sections’, small documents may only contain one or more ‘sections’.
3. Many types of documents follow conventions for the structure of the body of the document. This is especially true of specifications and manuals for software.
4. If a structure other than that which a reader expects to see, by convention, is adopted, we should explain this to the reader.

85 Appendices and Glossaries

1. Appendices are similar in format to chapters, but they contain supporting material. The inclusion of this material would clutter the body of a document.
2. Appendices typically contain tabular data, lists, plots, charts, drawings, flowcharts, smaller specifications, interface definitions and other bulky items which are difficult to incorporate in the body of a document.
3. A glossary is special type of appendix, which explains the technical terms used in a document.

86 References, Bibliographies and Indices

1. References or bibliographies list all of the other documents used in the production of the document.
2. Each entry in a reference list or bibliography must contain enough information to find the document which is being referred to.
3. The index lists important words or keywords in the document, with reference information such as page numbers.

87 Skeletons and Templates

1. The most efficient strategy for designing a document is to first produce a ‘skeleton document’, which lists the various parts of the document and includes notes on the intended content of each part.
2. Once the skeleton exists, it is easy to ‘flesh it out’ with content.
3. For many standard document types, DTP or typesetting packages will provide standard ‘templates’ which contain the required structure of the document and set the proper layout.
4. By editing a template appropriately, we can quickly produce a skeleton for a document.
5. Frequently a template may not fit the structure required for a particular type of document and must be edited as required.

88

89 What is a Product Proposal?

• A product proposal is a document which describes a product which doesn’t yet exist.
• Some product proposals lead to real products, some are rejected and end up quietly filed away.
• A product proposal can vary widely in complexity and content, reflecting the complexity of the product and the expectations of the people deciding whether the product is to be developed.
• A product proposal should contain enough information to allow an objective decision on whether or not to develop a product.
• Product proposals are frequently labelled “commercial-in-confidence” or “proprietary”, since the organisation producing the proposal does not wish its existence to become public knowledge.

90 What is in a Product Proposal?

• A product proposal should always contain enough detail to provide a reader with a very clear picture of what the product should be capable of doing.
• Frequently it also compares the proposed product against other related or competing products.
• A product proposal may include the results of preliminary development of algorithms or interfaces for proposed product.
• This is termed “concept demonstration” or “technology demonstration”, and the software written for this purpose a “concept demonstrator” or “technology demonstrator”.

91 What is in a Product Proposal?

• It is a good practice to include in a proposal preliminary estimates of the resources needed to develop the product.
• Resources can be the development tools needed, the number of programmers required and expected time to completion. Often these are tabulated.
• Simple product proposals for small items may contain only a description of the product itself.

92 Audience & Language

• The audience for a product proposal can vary widely, depending on the nature of the product and the organisation proposing it.
• Large products which may require long and very expensive development times usually lead to decisions at a very high level within the organisation.
• Therefore the people reading the proposal are very likely to be shareholders, financiers, senior managers, directors. The audience may therefore not understand technical detail well, and the language must be simple.
• Technical detail is placed into an appendix or annex to the document.
• Small products which require short and cheap development times usually lead to decisions at a low level within the organisation.

93 Audience & Language ...

• Therefore the people reading the proposal will be senior programmers, project leaders or managers.
• Such an audience is highly technically literate, allowing the use of technical language and detail in the body of the document.
• In general, it is important that a product proposal is very clear about the intended capabilities of the product.
• Since the product does not exist as yet, you should use modal auxiliary verbs such as ‘should’, ‘could’ and ‘might’ in describing proposed product capabilities.
• It is a good practice to outline future development paths for the product, to provide the reader with an idea of what other things the product could be made to do easily.

94 Product Proposal Structures

• The structure of a product proposal depends mostly on the complexity of the product and the intended audience.
• All proposals should have an introduction, a body and some conclusions.
• A large proposal may have a body divided into many sections or chapters, and may also include one or more appendices.
• If the proposal is to be read by people without knowledge of software engineering, an ‘Executive Summary’ or extended abstract should be used, and a ‘Glossary of Terms’ is advisable.
• A large proposal should include a ‘Table of Contents’ and possibly an index, to allow a reader to navigate through the document with ease.

95 Product Proposal Structures ...

• Author information, organisation identification, revision control pages, and authorisation pages are required.
• It is a desirable practice to ensure that the appearance of the document is very good, especially if the audience does not comprise software engineers, since such readers may be inclined to judge the document as much on its appearance, as its content.

96

97 What is a Software Product Specification?

• A software product specification is a document which describes in detail the function, structure and frequently implementation of a software product.
• This document is used by programmers as a basic guide for the implementation of the product.
• In many software houses, software architects or software engineers are wholly occupied writing detailed specifications for products to be implemented by programmers.
• The software product specification is the first step in the process of engineering a large software product.

98 What is a Software Product Specification?

• A software product specification can often be as large as hundreds or thousands of pages, depending on the complexity of the product.
• Such documents will often specify product implementation in very fine detail.
• Since programmers will use such specifications as a template for the product which they are coding, the specification must always be exact and unambiguous.
• The consequences of poor software product specifications are frequently problems such as hidden bugs, unwanted “features” in product behaviour, or product functions different from those intended. All can result in large costs to the developer.

99 What is in a Software Product Specification?

• A software product specification usually contains very detailed definitions of product features, such as language specifications, file formats and structures, datastructure definitions, GUI layout and menu structures etc.
• Example #1: A compiler specification will include the Backus-Naur Format (BNF) or similar definition of a language syntax, a description of the compiler command line interface, and mostly likely a reference describing the machine instruction set to be used. If such material is not contained in the specification itself, it will be in another document which is referred to.

100 What is in a Software Product Specification?

• Example #2: A library specification will include the definition of each and every function call in the library, if not actual function prototypes of the library calls. Again, if such material is not contained in the specification itself, it will be in another document which is referred to.
• Example #3: A GUI specification will include definitions of each and every facility in the GUI, and possibly calls to invoke them, if not actual function prototypes of the calls. As before, if such material is not contained in the specification itself, it will be in another document which is referred to.
• In general, a specification must fully define the product.

101 Audience & Language

• The audience for a software product specification almost exclusively comprises programmers, software engineers, project leaders or other expert readers.
• As a writer you can safely assume the readership will understand all technical detail you incorporate into the document.
• The language in a specification must always be exact.
• Ambiguity in a specification, or opportunities for a reader to interpret the contents in any way other than intended, is not acceptable in such a document.
• Features which are mandatory must be described using the modal auxiliary verbs “shall” or “must”.

102 Audience & Language ...

• Features which are optional must be described using the modal auxiliary verbs “may” or “might”.
• Sentences should always be short, encompassing a single idea alone, where possible.
• It is customary to use passive voice in such documents.
• The use of colloquial or conversational language is not acceptable in such documents.
• It is helpful to have the draft of such a document reviewed by another programmer to ensure that no part of the document is ambiguous or in any way open to interpretation.

103 Specification Structures

• The structure of a product specification depends mostly on the complexity of the product.
• All specifications should have an introduction and a body.
• A large specification may have a body divided into many sections or chapters, and may also include one or more appendices.
• A large specification should include a ‘Table of Contents’ and possibly an index, to allow a reader to navigate through the document with ease.
• As with proposals, author information, organisation identification, revision control pages, and authorisation pages are required. The latter are especially important.

104 Specification Structures ...

• The appearance of a specification is not critical to its function, since it will only ever be read by programmers, who are largely interested in the content alone.
• It is a good practice to ensure that the specification defines features or functions progressively, so that a reader does not have to look ahead to determine why something is being done in a particular way.
• Since a specification may be provided as a hardcopy document and also read online as an electronic document, it is helpful if the structure allows for the incorporation of hypertext.
• Because the specification amounts to a “master template” for developing a piece of software, it demands great attention to detail in both content and structure.

105

106 What is a Software Test Specification?

• A test specification is a document which details tests to be performed on the components and the whole of a software product.
• It is used during and after the development of a software product, to confirm that the product complies with the original specification.
• Frequently it is produced concurrently with the product specification, and employs an identical structure and format.
• For each item described in the product specification, the test specification defines one or more tests to be performed.
• While the software product is being written around the specification, the test code is written around the test specification. Production of test code and testing itself may amount to 50% of the total development cost of the product.

107

108 References:

Conway D. et al, “theStyle, A Guide to Writing Better C Programs”, Department of Computer Science, Monash University, 1994.

109 What are Comments Used For?

• Comments are used to explain the purpose and function of a program.
• Comments are used to explain the structure of a program.
• Comments are used to record the history of a program.
• Comments are used to explain the idiosyncrasies of a program.
• Comments are always intended to improve the readability of a program.
• Comments can save much time in software maintenance.

110 Issues in Commenting Code

• Many programmers neglect proper commenting of code, since they consider commenting to be a hindrance imposed by management, or a time consuming nuisance.
• Frequently commenting technique is not properly enforced in organisations, exacerbating the problem which exists with lazy programmers. Many programmers learn ‘bad habits’ in such organisations and then carry them to other jobs.
• Very few programming languages and development tools enforce commenting, as a result of which the quality of the comments produced is up to the programmer.
• Good programming technique incorporates the inclusion of good quality comments.

111 Style Variations

• The quality of commenting styles imposed by organisations can vary very widely.
• Many organisations will tolerate a ‘minimalist’ philosophy in commenting, and will accept very brief comments in a source code file.
• Other organisations will expect and enforce a ‘comprehensive’ philosophy in the commenting of source code files.
• A good programmer must be capable of producing comments in code which are consistent with a fussy employer’s expectations, indeed it is good practice to be detailed in commenting code.

112 ‘Minimalist’ Commenting

Several comments are essential in every source file:

• The name of the program or modules in the file.
• The name of the author.
• The copyright holder or owner of the intellectual property in the program.
• The date of the source file’s creation.
• Preferably, a short comment on what the program does.

These are always placed at the top of a file, as a ‘file header’.

113 ‘Minimalist’ Commenting Example:

 /*
  * flunk.c - int flunk(char *filename);
  * Jane Doe
  * (c) 2000, Softstuff Systems, Santa Clara, California
  * Created: 28/08/2000
  * Function: sorts a file by grades
  */
 
 int flunk(char *filename)
 {

 Blah ....
 }

114 Why ‘Comprehensive’ Commenting?

• Comprehensive comments make it much easier for a programmer to understand his or her code six or twelve months after it has been written.
• Comprehensive comments make it much easier for another programmer to maintain or modify the program.
• The more relevant detail is included, the more time can be saved later in the life cycle of the program.
• During a code review or audit by management, a programmer can easily show what work has been done.
• A large package which includes dozens or hundreds of files is easier to navigate and understand, if individual files are well commented.

115 The File Header

• A file header is a block of comments at the beginning of a file, which include the most important information describing the file.
• The name of the program or modules in the file.
• The name of the author.
• The copyright holder or owner of the intellectual property in the program.
• The date of the source file’s creation.
• Revision control identifier and logging information.
• A reasonably detailed description of what the program does.
• The command line usage or prototype summary of the program.

116 File Header Example:

 /* flunk.c - Test Failure List Sorter
  * Jane Doe, Systems Architect, Product Development.
  * (c) 2000, Softstuff Systems, Santa Clara, California
  * Created: 28/08/2000 from sortlist.c
  * $Id: flunk.c,v 1.2 2000/08/28 21:47:42 jdoe Exp jdoe $
  * $Log: flunk.c,v $
  * Revision 1.2  2000/08/28 21:47:42  jdoe
  * modified to include comments.
  * Function: flunk() is called by another program with
  * the name of a test list failure file in `test-2'
  * format.It sorts the test failures and writes them
  * to a buffer pointed to global variable char *buf.

117

  * It returns 1 if OK * and 0 if it fails.
  * Usage: int flunk(char *filename);
  */

118 Block vs Inline Format

• A good practice for all large comments is to use ‘block format’, in which the comment is surrounded by symbols or characters to clearly separate it from the code. ‘Inline format’ places a comment on a single line.
• C compilers recognise anything between the /* and */ delimiters as being a comment.
• C++ compilers use //.
• Unix shells such as csh, sh, tcsh, ksh use #
• other languages will use other techniques, e.g. Fortran uses C, Forth uses \, etc.
• Block format will therefore vary with the language being used, but the basic idea remains the same.

119 Block Format Examples in ‘C’:

 /*
  * This is ordinary C block format and the easiest
  * style of comment block format to use.
  */
 /***************************************************
  * This is a comment produced in block format,
  * with additional lines of `*' characters used to
  * emphasise the beginning and end of the block
  **************************************************/
 /* This is a comment produced without
 any blocking, observe how messy this looks! */

120 Block Format in Other Languages:

 // ***********************************************
 // This is block format in C++
 // ***********************************************
 CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC
 C This is block format in FORTRAN
 CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC
 \ ************************************************
 \ This is block format in Forth
 \ ************************************************

 ##################################################
 # This is block format in Bourne shell
 ##################################################

121 Inline Format Examples:

 /* This is inline format in C */
 
 // This is inline format in C++
 
 C This is inline format in FORTRAN
 
 \ This is inline format in Forth
 
 # This is inline format in Bourne shell

122 ‘Strategic’ vs ‘Tactical’ Commenting

• A file header alone merely explains the basic function of a program as a whole and incorporates necessary identifying information.
• Comments within the body of the code can be divided into two basic categories: ‘Strategic’ and ‘Tactical’ comments.
• A ‘Strategic’ comment is usually produced in block form, and explains in general terms the behaviour of a segment of code, or the interface to a program.
• A ‘Tactical’ comment may be in block or inline form, and explains the use of a specific variable, a particular algorithm, or other small portion of the code.
• Good coding practice is to produce a program by first putting down ‘Strategic’ and ‘Tactical’ comments, and then filling in the code.

123 Example:

     /*
      * At this point we can generate contents for
      * the arrays, first we do the loss/freq table
      * then we do the height profile etc
      */
     fprintf(stdout,"Generate Loss vs Altitude Table\n");
     for( i = 0; i < 2000; i ++){/*step thru altitude*/
         fprintf(stdout,"H0 = %d\n", i);
         startalt = i*0.01;  /* 10 metre increments */
         /* step through freq in 1 GHz steps */
         for( j = 1; j < 100; j++ ){
             td->flags = OXYGEN|WATER;
             td->f = j;   /* increment frequency */

124 Example ... :

             td->h = startalt;
             tropo_point(td);
             freq_table[i][j] = td->Gamma_gas;
         }
     }

125 Commenting Technique

• When producing comments, avoid stating the obvious. You can safely assume that the person reading the program can write code in that language.
• Use short and exact descriptions of the code, a lengthy treatise may be hard to follow and confuse the reader.
• Avoid redundant commenting, e.g. if you have described a variable and its purpose earlier in the program, avoid doing so again.
• Avoid the use of abbreviations which are not commonly used. You cannot assume another programmer will know them.
• A good practice is to align inline comments, to make them easier to read.

126 Commenting Technique ...

• When maintaining code, always update the comments, to avoid confusion in the future. A good habit is to identify the change.
• Upper case can be very useful to identify an important part of a comment, such as a title.
• With large and complex loops, a nice practice is to identify the end of each nested level with a comment.
• Beware of tab settings in editors, these may differ on different systems.

127 Examples:

 /* Aligning comments in your code     */
 int   failures;  /* failed students   */
 int   passes;    /* passed students   */
 int   enrolled;  /* enrolled students */
 /* Cryptic and hard to follow comments*/
 /* Cryptic & hd 2 flw cmnts           */
 /* IMPORTANT: upper case is useful!  */
 /* Updating when modifying code - CK 28/08/2000 */
 while( f <= outerStop ){
     while( g <= innerStop ){
          f++; g++;
      } /* end inner loop */
 } /* end outer loop */

128

129 What is a User Manual?

• A user manual is a document which provides explanations and reference material to a user.
• User manuals are the documentation most visible to a user, and therefore can be a critical part of the user’s assessment of the quality of a product.
• A user manual can vary widely in complexity and content, reflecting the complexity of the product and the needs of particular categories of users.
• A user manual should contain enough information to allow a user to perform his intended task using the software product, or solve a typical problem.

130 Observation:

User manuals of poor quality can damage or destroy the commercial viability of a software product, and must always be of the highest quality. One of the fastest ways to damage a new product being released into the market is the provision of poor quality user manuals. Effort expended on user manuals is therefore always justified.

131 What is in a User Manual?

• A user manual should always contain enough detail to provide a reader with a very clear explanation of how to use the software or solve a problem.
• Frequently a user manual contains examples of the product in use, to provide the reader with a template for his or her work.
• Some user manuals may include very detailed reference information for use with the software product.
• Given the wide range of user experience (or competence) levels which may be encountered, it is not uncommon to find products with ‘basic user manuals’ and ‘advanced user manuals’.

132 User Manual Media

• Over the last two decades it has become customary to provide user manuals in hardcopy and on-line formats.
• Recently there has been a trend to use on-line documentation in preference to hardcopy documentation. However many users still prefer having a hardcopy manual which they can read away from their desktop.
• A good compromise is to produce a hardcopy manual using electronic publishing tools, and use the very same electronic document as an online manual.
• On-line manuals can be produced in a wide range of formats. The most accessible are HTML, XML and PDF, which should be used in preference to platform-specific formats.

133 User Manual Media ...

• It is preferable to use a generalised markup language or DTP tools to produce user manuals, since such tools usually allow for conversion to a range of formats.
• Example: a master document in LATEX or FrameMaker can be used to generate HTML, XML and PDF, as well as PostScript for direct printing.
• Unix man and GNU info format are acceptable for short online references on Unix systems but are limited in portability to other platforms.
• Hypertext is exceptionally useful in on-line user manuals and should be used where opportunities arise.

134 Audience & Language

• The audience for a user manual can vary widely, depending on the nature of the product and the experience level of the intended user.
• Large and complex products will frequently be provided with ‘basic user manuals’ and ‘advanced user manuals’.
• The basic manual will be written for beginners, who may be very weak in computing skills, the advanced manual for experienced and highly literate users, who may have expert level computing skills and knowledge of related or similar software products.
• It is a good practice with all categories of user manual to include reference information in appendices or dedicated reference chapters at the end of the manual.

135 Audience & Language ...

• Small or simple products, or products with highly specialised technical usage, such as development tools, frequently have only one user manual.
• Such a manual must be ‘all things to all readers’, which is a demanding requirement to meet.
• The audience may vary between the highly technically literate and the virtually technically illiterate.
• In general, it is important that a user manual is very clear about the features and usage of the product. Short and simple sentences are needed.
• Since the product exists, you should use modal auxiliary verbs such as ‘is’, ‘are’, ‘will’ in describing product features.

136 User Manual Structures

• The structure of a user manual depends mostly on the complexity of the product and the intended audience.
• All manuals should have an brief overview section, a body detailing commands and modes and some reference material.
• A large manual will have a body divided into many sections or chapters, each of which discusses commands and modes. Examples are essential.
• If the manual is to be read by people without much experience, a ‘Glossary of Terms’ is advisable.
• A large manual should include a ‘Table of Contents’ and possibly an index, to allow a reader to easily navigate through the document.

137 User Manual Structures ...

• Author information, organisation identification, revision control pages, and authorisation pages are required.
• It is essential that the appearance of the document is very good, especially if the audience does not comprise software engineers.
• This is because most readers will gain their first impressions of the product from the appearance of the manual.
• If the product is part of a family of related products, all manuals should employ the same layout, structure and style where possible.

138 Illustrations and Artwork

• Illustrations and artwork are a valuable tool for the writer of user manuals.
• This is especially true of manuals written for products with GUIs, since it allows the reader to relate the text to the image they will see on the screen.
• The proverb ‘a picture is worth a thousand words’ is usually true of user manuals.
• Frequently complex menus, popup windows and other such features can not only be difficult to describe, but also confuse a reader with a short attention span or poor short term memory.
• It is essential that care be taken in using screen dumps, the reader must be directed to the specific button or menu to be used.

139 Example #1:

PDFslide viewing window displayed by Acroread.

140 Example #2:

Xfig open and export windows.

141 Manuals for Novice Users

• A mistake which novice writers of manuals make very frequently is that of patronising the reader.
• A reader who is a complete novice to the software product described in the manual may have a PhD in astrophysics or mathematics: never make the assumption that a novice user is ‘dumb’, you may succeed otherwise in annoying or insulting the reader and losing a client.
• A beginner’s manual can be an exceptionally difficult document to write for precisely this reason. You cannot assume the reader is ‘dumb’, yet you cannot assume the reader is a ‘genius’.
• Therefore the document has to use simple and unambiguous explanations of the function of the product, without having a condescending tone.

142 Manuals for Advanced Users

• Manuals for advanced readers are much easier to write than manuals for novice readers.
• You can safely assume that the reader knows what the product does, he or she has used the product before, and that the basic terms used to describe the product are known and understood.
• Advanced users get annoyed with lengthy explanations and tedious descriptions, and mostly prefer a dense, content rich document.
• It is a good idea to include more complex examples in such a manual.
• Advanced users usually appreciate tabulated reference information, or lists. An example would be a table summarising all of the modes in a program and how to invoke them.

143

144 References:

Woolever K.R., “Writing for the Technical Professions”, Longman, 1998, Chapter 5.

Kopp C., “An I/O and Stream Inter-Process Communications Library for a Password Capability System”, MSc Thesis, Monash University, 1996 (Misc. Artwork).

145 Why Should Graphics Be Used?

• Graphics are a powerful means by which a writer can convey information to a reader.
• Graphics can be used to clarify assertions in the text, e.g. by providing plots, charts, and diagrams.
• Graphics can be used to simplify and condense the representation of information, e.g. by replacing lengthy and tedious descriptions.
• Graphics can be used to emphasise information, e.g. by providing an illustration to focus the readers’ attention.
• Graphics can be used to reinforce and summarise information, or to attract and impress a reader.

146 Types of Graphics

• Screen dumps in bitmap formats can be used to show the appearance of menus and windows.
• Line drawings in bitmap or vector formats can be used to show block diagrams, flow charts, functional or state diagrams, address space maps and memory maps.
• Plots, graphs, bar and pie charts can be very useful for the display of measurements and data, e.g. when documenting the performance of a software product.
• Tables can be extremely useful for summarising information, especially commands, arguments, variables, and input and output from programs.

147 Example - Conceptual Diagram

148 Conceptual Diagrams

• Conceptual diagrams are used in proposals, specifications, technical manuals and papers to illustrate a basic idea or concept.
• They are usually implemented as block diagrams or charts.
• Colour can be used to emphasise relationships between components of the system or program being described.
• Conceptual diagrams should not be cluttered with too much detail, as detail can distract the reader.

149 Example - Memory Map & Concept

150 Memory Maps

• Memory maps are used in proposals, specifications, technical manuals and papers to illustrate the address space used by a program.
• Memory maps are commonly found where programs manipulate shared memory or the address space of a process, e.g. in operating systems documents.
• They are usually implemented as block diagrams.
• Colour can be used to contrast specific areas of the address space.
• Memory maps can also be used to show relationships between programs which interact using shared memory.

151 Example - Flow Chart

152 Flow Charts

• Flow charts are used in proposals, specifications, technical manuals and papers to illustrate the control flow or thread of execution of a program.
• Flow charts used to be very popular in programming texts, and are used to clarify the behaviour of a program to a reader.
• They are usually implemented as block diagrams.
• Colour can be used to contrast particular threads of execution.

153 Example - Datastructure Diagram

154 Datastructure Diagrams

• Datastructure diagrams are used in proposals, specifications, technical manuals and papers to illustrate the layout of datastructures.
• They are usually implemented as block diagrams.
• Colour can be used to contrast specific parts of the datastucture.

155 Example - Functional Diagram

156 Functional Diagrams

• Functional diagrams are used in proposals, specifications, technical manuals and papers to illustrate the interactions between programs or portions of programs.
• They are usually implemented as block diagrams.
• Colour can be used to contrast different programs or modules.

157 Example - Plot (GNUPlot)

158 Plots

• Plots are used in proposals, technical manuals, performance reports and papers to illustrate the behaviour or performance of programs.
• They are usually produced by plotting tools such as gnuplot, octave or maths packages such as Wolfram Mathematica.
• Colour can be used very effectively to contrast different curves.

159 Example - Screen Dumps

160 Screen Dumps

• Screen dumps are used mainly in user manuals, technical manuals and papers to illustrate the GUI or output display of programs.
• They are usually produced by dumping from the display screen using a tool such as xwd. Frequently they must be converted to formats which are compatible with the DTP, WP or typesetting tool to be used.
• Screen dumps can present problems with resolution and colour contrast in printing, and should be used carefully.

161 Placement of Graphics

• The placement of graphics in a document is very important. Improper placement can diminish the impact of graphics to the detriment of document quality.
• The placement of graphics can follow very specific conventions, particularly in user manuals for product families.
• If a large number of charts, plots or diagrams are to be incorporated into a document, consideration should be given to placing some or all into an appendix.

162 Placement of Graphics ...

1. Graphics should be placed in the document before they are discussed in the text.
2. Graphics should be placed as near as possible to the text which refers to them.
3. Graphics should always be labelled with a number, and it is a good practice to use a caption.
4. Captions should be brief and focussed on the content of the graphic.
5. Text in graphics should be horizontal where possible, especially in electronic documents.
6. The quality of the graphics can quickly impress a reader, poor quality graphics can convey the impression of a poor quality document.

163 Placement of Graphics ...

1. The size of graphics and the level of detail should be matched to the document carefully. Small graphics are hard to read, too much detail can make the graphic incomprehensible.
2. Colour should be used carefully, especially in electronic documents.
3. Bright colours can be annoying, poorly contrasting colours can make a document difficult to read.
4. Excessive use of graphics can clutter a document, and can also result in performance problems when viewing an electronic document, e.g. a web page.

164

165 What is a Technical Manual?

• A technical manual is a document which provides implementation details and reference material to a developer.
• Technical manuals are the documentation item which contains much of the substance of a product, and are vital to its long term maintenance.
• A technical manual can vary widely in complexity and content, reflecting the complexity of the product and the idiosyncrasies of its implementation.
• A technical manual should contain all information needed to understand the internal function of a product.

166 Observation:

Technical manuals of poor or marginal quality can introduce large costs in the maintenance of a software product. Like comments in source code, technical manuals must accurately reflect the inner workings of a software product.

167 What is in a Technical Manual?

• A technical manual should always contain sufficient detail to allow a developer to understand the function of the code.
• Whereas comments in source deal with the function of specific components of a software product, a technical manual aims to explain the structure of a program and interaction of its various components.
• It is customary for a technical manual to include very detailed reference information covering the product.
• The depth and level of detail in technical manuals can vary, reflecting the complexity of the product. Frequently smaller and simpler products do not have technical manuals, their function performed by comments in the code.

168 Technical Manual Media

• Traditionally, technical manuals have been produced as hard copy documents. In part this is because they are intended only for internal use by the organisation developing the product.
• In principle, a technical manual can be produced in any medium. A practical approach is to produce the document in electronic form using a DTP or TS tool, but only distribute the document in hard copy format.
• As technical manuals nearly always contain commercially sensitive implementation details of a product, hypertext electronic versions are uncommon. However, hypertext can be very useful in such a document.

169 Technical Manual Media

• With the availability of security measures, such as password access, in electronic document formats (e.g. PDF), electronic media may become used more frequently.

170 Audience & Language

• The audience for a technical manual comprises almost exclusively software developers, system integrators, project leaders and managers.
• Therefore the writer of a technical manual can safely assume that the document will only ever be read by knowledgeable users.
• A technical manual, like a specification, must provide exact and unambiguous explanations of the product’s inner function.
• Whereas a specification will refer to features in the future tense, and may discuss possible features, a technical manual must always be written in the present tense.
• Auxiliary verbs such as ‘is’ and ‘does’ are most commonly used.

171 Technical Manual Structures

• The structure of a technical manual depends mostly on structure and the complexity of the product.
• All technical manuals should have an brief introduction or overview section, a body detailing the function of the product and all necessary reference material.
• A large manual will have a body which is divided into many sections or chapters, each of which discusses specific components of the product.
• If the product contains a lot of unique terms and abbreviations, a ‘Glossary of Terms’ is advisable.
• A large manual should include a ‘Table of Contents’ and possibly an index, to allow a reader to easily navigate through the document.

172 Technical Manual Structures ...

• Author information, organisation identification, revision control pages, and authorisation pages are required.
• It is customary to use one or more appendices or annexes to put reference material into.
• The appearance of a technical manual is not critical, since its readers are only interested in the content. Because they are experts, they will less frequently form opinions based upon appearance.
• If the product is part of a family of related products, all technical manuals should employ the same layout, structure and style where possible.

173 Illustrations and Artwork

• Illustrations and artwork are very useful in technical manuals.
• Block diagrams, charts and flowcharts can be used to describe the interaction of components of the program, and are also useful for relating the structure of the product.
• Where GUIs are employed, screen dumps can be used to describe the function of various screen displays and modes.
• As with other artwork in technical documentation, accuracy is important. Quality of presentation is less critical since the readers are more impressed by the technical content than the appearance.

174

175 Journal Articles & Papers

• Journal articles and papers are documents which are intended to describe a product, a feature of a product, an aspect of a product, or some fundamental technology in the product to a public audience.
• The nature of the audience depends mostly upon the publication in which the article is published.
• Frequently, an article must be carefully restricted in technical depth, either to accommodate the limitations of the readers, or to preclude the divulging of proprietary information.
• Articles can be the most demanding of documents to write, since they must be well composed and nice to read.

176 Article Media

• Journals, until recently, were exclusively hard copy publications. More recently, an increasing number of journals are published on the web.
• Therefore, it is preferable to produce articles in an electronic format, using tools which can easily accommodate both hard copy and electronic distribution.
• The preferred format at this time is PDF, although XML/SVG is likely to displace PDF rapidly in coming years. HTML is not well suited if hard copy is to be produced.
• Articles published in glossy industry journals can be very demanding in terms of artwork quality.

177 Audience & Language

• The audience for a article will vary widely, depending upon the nature of the journal. An article written for Scientific American or New Scientist can make very few assumptions about the reader having prior knowledge, while an article written for an IEEE or ACM scientific or academic journal can assume a very high level of reader knowledge.
• The language must not only be clear and concise, but must also flow and follow the practice of essay writing. Repetitive use of phrases and words should be avoided, unless these are proper technical terms or names.
• Most journals employ competent ‘copy editors’ who can polish the language used in an article. Nevertheless, it pays not to annoy the editor!

178 Article Structures

• The structure of an article or paper depends largely upon the publication.
• In general, all articles should have an introduction, a body and a summary or conclusion section.
• Academic journals usually require a short abstract, and explicit introduction and conclusion sections, as well as a bibliography section.
• Industry journals and popular journals or magazines are less demanding of formal structure, but usually require introductory and conclusion sections. Frequently editors will delete references in such publications.
• High quality artwork is often expected for such publications.

179

180 The Aims of a White Paper

• The principal aim of any white paper is to impress the reader with a new product or a new idea.
• While the formal purpose of such a document is to inform the reader of a new product or idea, in practice this purpose is secondary to that of leaving the reader with a good impression.
• White papers are usually aimed at a professional audience, and this must be reflected in the quality of writing, the type of language used, and the content.
• A white paper which is deficient in any of these areas may not achieve the primary aim of impressing the readership.
• White papers are often described as ‘strategy papers’, insofar as they map out the long term objectives of a product or an idea.

181 Producing White Papers

• A ‘white paper’ is an article intended for distribution alone, or publication in a journal, which introduces a product or service.
• Like journal articles, all white papers should have an introduction, a body and a summary or conclusion section.
• Short white papers usually require an abstract, and explicit introduction and conclusion sections, as well as a bibliography section.
• White papers written for websites, industry journals and popular journals or magazines usually need less formal structure, however introductory and conclusion sections are typically expected.
• High quality artwork is often required for white papers, since the aim of such a document is to impress the reader.

182

183 References:

DeLamarter R.T., “Big Blue”, Macmillan, 1986

184 Marketing and Sales Literature

• Marketing and sales documents are employed for the purpose of selling products, either to distributors or end users.
• The aim of a marketing or a sales document is to convince the reader that the product offered is best suited to their needs. Given the diversity of user needs and user skill levels in any market, this can be a difficult task.
• A programmer or systems integrator will frequently encounter marketing or sales documents in industry: either when dealing with suppliers’ products or when supporting the marketing and sales effort of their employer.
• A programmer or systems integrator must therefore be capable of understanding and interpreting marketing and sales documents.

185 Ethics in Marketing and Sales

• Marketing and sales documents can be broadly divided into two categories: those which are ‘ethical’ and those which are ‘unethical’.
• An ethically sound marketing or sales document is one which is truthful in its descriptions of a product, or a competitor’s product.
• An ethically unsound marketing or sales document is one which is untruthful in its descriptions of a product, or a competitor’s product.
• Untruthful marketing or sales documents are frequently produced with the aim of increasing sales in the short term. In practice they can produce serious long term damage to the organisation which has created them, as the readers will eventually discover the deception and thereafter avoid the product or the supplier, thereby damaging prospects for ‘repeat sales’.

186 Ethics in Marketing and Sales ...

• There are several techniques you can employ to determine whether a marketing or sales document is untruthful:
  1. Look for statements which contradict fundamental scientific theory.
  2. Look for statements which contradict other documents produced by the same supplier.
  3. Evaluate or test the product and check whether the document truthfully describes the product’s behaviour.
  4. Check the supplier’s track record in truthfulness. If they have lied in the past, odds are they are still telling lies.

187 Ethics in Marketing and Sales ...

• One form of deception common in marketing documents is omission. Important parts which could reveal the limitations of the product may be missing.
• A programmer may frequently have to participate in the production of marketing and sales documents for their employer. Under these circumstances, care must be taken to ensure that overly zealous sales and marketing personnel do not knowingly or unknowingly change statements which are truthful into something deceptive or untruthful.

188 Types of Marketing/Sales Documents

• Marketing and sales literature can take many forms.
• A glossy brochure or ‘glossy’ is one of the most common types of such a document.
• Product description guides and product family guides are also very common.
• Advertisements and posters are also very popular.
• Marketing and sales documents can be broadly divided into two categories by content:
  1. Technical brochures and guides.
  2. Non-technical brochures and guides.

189 Technical Brochures and Guides

• A technical brochure or guide is aimed at an audience of programmers, engineers or technical managers.
• Such a document must contain a generous amount of detail in describing the product, to satisfy the expectations of the typical reader.
• Accuracy in such a document is important, since the reader will quickly notice any deficiencies.
• The language used in such a document must be technical.
• Clarity and brevity are important to avoid annoying the reader.

190 Technical Brochures and Guides ...

• Tables are very frequently used to summarise technical specifications.
• Diagrams and artwork are very commonly used, mostly block diagrams to explain the operation of the product.
• The layout of such a document must be attractive, and information very easy to find within the document.
• If the product is part of a family of products, the document will usually conform to a standard structure and layout.
• While no firm conventions exist for such documents, it is useful to provide at least a brief introductory description of the product.

191 Non-technical Brochures and Guides

• A non-technical brochure or guide is aimed at an audience with a minimal level of technical literacy.
• Such a document usually contains a very little detail in describing the product, since its aim is usually to impress a reader who cannot understand the technology in the product.
• The language used in such a document usually avoids the frequent use of technical terms.
• Non-technical literature often uses verbose and flowery language to ‘pad out’ the document.

192 Non-technical Brochures and Guides ...

• In practice, this category of document can produce counter-productive results by annoying technically literate readers.
• However, the large number of potential customers in any industry, who have inadequate technical skills, makes such documents useful in the marketing and sales process and they remain very popular.

193 Advertisements and Posters

• Advertisements and posters are designed to attract the attention of a reader to a product.
• Some advertisements may occupy several pages in an industry journal, more commonly they are sized for a page, or half a page.
• The technical content of an advertisement can vary widely. Some may includes lists of products and specifications, others little more than a product name.
• A good practice in all such documents is to ensure that they contain enough referring information to allow an interested reader to find more detailed information about the product.

194 Competitive Analyses

• Competitive analyses are a special category of marketing or sales document.
• In the most general sense, they are similar to a technical survey paper, in that they compare similar but competing products.
• The aim of such a document is to contrast the relative strengths and weaknesses of these products.
• An ‘internal’ competitive analysis document is not intended to be read by customers, since it usually identifies weaknesses of the products which are being sold by the authors of the document.
• An ‘external’ competitive analysis document is intended to be read by customers. It is a good practice to carefully validate the accuracy of such a document.

195

196 References:

Literate Programming Website,
http://www.literateprogramming.com

Literate Programming FAQ,
http://shelob.ce.ttu.edu/daves/lpfaq/faq.html

Norman Ramsey’s noweb page,
http://www.cs.virginia.edu/ nr/noweb

197 The Conventional Software Engineering Model

• The existing software engineering model is built around the model of discrete documentation and source files.
• In this model, documentation is developed in parallel with the code, and introduced as comments in source files and separate specifications and manuals.
• This model was introduced several decades ago and remains the standard technique for producing software products in the industry.
• The basic model of separating code and documentation reflects the early origins of the industry, when documentation was almost completely in hard copy format and typesetting and DTP tools were scarce and expensive.

198 The Conventional Software Engineering Model ...

• In many respects this model reflects ‘industrial age’ development philosophy, using personnel with different skills for different tasks.
• A typical approach would see programmers producing comments in code, specifications and technical manuals.
• Most manuals and specifications are written or re-written by professional technical writers.
• The result is that frequently different groups of personnel are working in parallel on documentation and coding tasks.

199 Weaknesses in the Conventional Model

• What problems arise with the ‘conventional’ model of software engineering?
  1. Programmers may spend little time on commenting code and may not do this very thoroughly.
  2. Technical writers frequently cannot understand the technology and introduce errors into the documentation.
  3. Project time estimates may not include documentation effort, resulting in insufficient resources to do so properly.
  4. Poorly written or minimal specifications may introduce bugs into the product.
  5. The product may become extremely expensive to maintain once the initial development work is completed and developers move to other projects.

200 Weaknesses in the Conventional Model ...

• These problems result very frequently in the following consequences:
  1. The project may run beyond its originally planned deadlines, thus increasing development costs.
  2. The project may run beyond is originally planned deadlines, thus allowing competitors to gain a bigger market share.
  3. Bugs in production code and documentation releases will diminish profitability and annoy customers.
  4. It may become very difficult to maintain synchronisation between code and documentation releases.

201 Other Problem Issues

• Let us assume that the developers of a software product do manage to master the problems inherent in partitioning coding and development tasks, and programmers diligently observe proper documentation techniques.
• Can other problems arise? The answer is yes, since:
  1. Traditional schemes such as tree diagrams to show the calling relationships between functions may not properly illustrate the actual inter-relationships between parts of the program.
  2. Conversely, block diagrams illustrating the functional relationships between parts of a program may not illuminate calling relationships well.
  3. There is no mechanism which forces a 1:1 mapping between source code and document structure.

202 Are There Remedies?

• Several strategies can be used to deal with this problem:
  1. A draconian disciplinary regime can be be introduced into the development process, with other consequences.
  2. A programming language which forces the inclusion of comments into code can be used, resolving part of the problem only.
  3. ‘Literate Programming’ techniques can be adopted to avoid the problem in the first place.

203 What is Literate Programming?

• Literate Programming (LP) is a technique whereby a single source file produces either an executable program or a formatted document, depending on which tool is used to compile this file.
• LP was devised by Prof Donald Knuth during the 1980s, as a way to solve many of the problems known to exist in the software engineering and documentation process.
• By using a single source file for documentation and program code, LP automatically achieves synchronisation between documentation and source code.
• The intent of LP is to change the way the programmer approaches the problem of creating a program, by integrating rather than separating the code and documentation.

204 Machine vs Human Readable Files

• A ‘conventional’ program written in any number of languages is primarily intended, by design, to be parsed and processed by a compiler.
• Comments which are incorporated in the source file are discarded by the compiler.
• Therefore a ‘conventional’ program is a machine readable document, with some optional human readable comments added in.
• A book or manual is, on the other hand, a human readable document, which is unreadable by a typical compiler.
• A source file written for an LP tool is readable by a human and produces suitable output for a compiler to use.

205 Using a LP Toolset

• A package designed for literate programming requires two basic tools.
• One tool extracts the machine readable program source for compilation, producing intermediate source files in a particular language such as C, C++, Java or such.
• Another tool extracts the documentation components as source files for use with a typesetting package such as TEX or LATEX.
• By running a compiler an executable can be produced from the machine readable program source.
• By running a typesetter a hard copy or online document can be produced from the documentation components.

206 Writing Literate Programs

• Literate Programming aims to shift the focus of a programmer away from ‘writing for the machine’, instead the programmer writes for other programmers. This achieves three important practical outcomes:
  1. The cost of maintaining the program is reduced since another programmer will find the ‘Literate Program’ easier to understand than program language source.
  2. By writing the program with the aim of making it a human readable document, the programmer is forced to think about the behaviour of the program and is thus made to understand it better.
  3. Since a literate program encapsulates the technical manual for the product, it can reduce the overall life cycle cost.

207 Problem Issues in LP

• LP exposes the total development costs of a source and documentation package, and may not be attractive to a manager whose aim is to create the appearance of a ‘cheaply developed program’.
• Using LP techniques may result in greater code development time, therefore shifting some costs to the beginning of a product life cycle.
• Many programmers have difficulty in writing well, and thus find the use of LP tools to be difficult.
• No major commercial tool developer has embraced LP techniques, which must compete against established ‘conventional’ development tools.
• It is much more difficult to integrate a debugger with a LP toolset, in comparison with a conventional programming toolset.

208