using_descriptive_devices [PATS2]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Using Descriptive Devices ======

Here we mention some well-established descriptive devices which you can use in your project report to improve its quality.

===== Cross-references =====

Cross-references are just references to other parts of the same document. For example,
<code>
This module contains procedures for operating on variables of type WINDOW (see Section 2.2).
</code>

Section numbers will change if sections are added or deleted. Good typesetting or word processing software provides suitable mechanisms to automatically number sections and create such references such that they will always refer to the intended section. Make sure you know how your chosen software does this and select the right software to make this simple. If you use software that does not support cross-references or uses an overly complicated  system, it is a good idea to wait until the report is almost complete before putting in any cross-references.

Backward references to sections earlier in the project report can make explicit connections between parts of the document that may not be connected obviously. Forward references can be used, for example, to reassure the reader that you are not going to leave them stranded after you have introduced a new idea without explaining it. For example,
<code>
This procedure uses the Volestrangler algorithm (to be described in Section 4.3).
</code>
Note that too many forward references are probably an indication that the report could be organised better.

===== Footnotes =====

Many word processors have facilities for handling footnotes. By all means use them, in particular when you want to make a comment which is not strictly relevant or which would upset the flow of ideas in the text. If the comment is closely related to the text you may consider including it in parenthesis instead.

===== Lists =====

Traditionally, collections of items are listed within the text using the adverbs ‘firstly’, ‘secondly’, etc. Often, though, it is clearer to tabulate these items, particularly if there are many of them. The simplest way of doing this is to use a "bullet" list. Various examples of bullet lists appear on this wiki. Sometimes there is a need to nest one list inside another. To distinguish the two lists, the inner one can be indented and have a different symbol. Lists with more than one degree of nesting tend to appear confusing and therefore we do not generally recommend them.

Listed items can also be keyed using numbers, letters, or other labels. Bibliography entries are an example of keyed items (see [[Arranging Material and Structuring the Project Report#The "References"|References]]). However, keys should only be used when necessary.

===== Figures =====

A project report that uses figures (i.e. diagrams or other pictorial techniques such as tables) to illustrate ideas will probably be easier to digest than one that does not. We therefore recommend that you use figures wherever appropriate (If you have a graphical rather than a textual/verbal kind of mentality, a good way to write text is to express your ideas in diagrams first and then describe these textually).

Be careful though. When drawing diagrams try to keep to a standard graphical notation that has been introduced during your studies, or that you have seen published widely, and use it consistently. Computer Science, unlike most other professions, has few established conventions governing the use of diagrams and this means that diagrams can sometimes make ideas more obscure rather than clarifying them.

If you feel you have to invent your own notation, remember that the best ones are usually the most economical, i.e. they use only a few different kinds of symbols. Also, you must explain the precise meaning of your symbols in a key. A very common mistake is to use arrows to illustrate some kind of relationship between items without declaring what that relationship is.

Graphics editors (i.e. image processors) can be extremely useful, particularly if you have a great deal of drawing to do or if there is a lot if commonality among the drawings (because cut and paste operations can then be used with great effect). However, some artefacts are difficult to produce using standard software applications, and in such cases it is quite acceptable to present hand-drawn diagrams. To include these into your report you may use a scanner or even take a photograph (or multiple partial photographs that you merge afterwards) of the artefact and include it in your report as any other computer generated image (help from staff for this is available).

All figures should be labelled and captioned, for example,
<code>
Figure 3.10: Sub-System Architecture.
</code>

The label can then be used to refer to the diagram within the text, e.g.
<code>
See Figure 3.10.
</code>

All diagrams must be explicitly referred to somewhere within the text. 

Similar to sections and subsections the labels may change if you insert additional figures or change the structure of the report. Again good typesetting software will support automatic label generation and keeping the references to the figures consistent (see [[Using Descriptive Devices#Cross-references|Cross-references]]). 

For some reports it may also be useful to distinguish between figures and tables and use separate labels for them (e.g. Figure 3.1 and Table 3.1 are two separate elements, sometimes also referred to as floats). Figures are diagrams, drawings, images, etc. while tables list information in a tabular layout, e.g. program running times for specific inputs.

===== Literal Text =====

It is important when writing about software systems to distinguish in the text between the ordinary natural language you are using and the program code or other literal text. If you are using a word processor which offers both proportionally spaced and fixed width character fonts then there is a straightforward way of doing this. Program code and other literal text can be written in a fixed width font such as "Courier New" while the natural language text can be written with a proportionally spaced font such as "Times New Roman".

Other similar kinds of text, UNIX commands for example, can be treated in the same way. Some typesetting systems also offer to include “verbatim” text, which you can use to insert small code examples, examples of the output of a program, etc. They are also typeset in a fixed width font. Using a fixed width font means that the code appears in the document much as it would do on a console. If you only have fixed width characters available on your word processor then put program code etc. into italics or bold text.

Note that using more than a few different character fonts, styles or sizes can make text look very untidy. Generally we recommend to use, e.g., a serif font for the main text (or a sans-serif font, if you prefer), a fixed-width font for literal texts as above, and optionally one sans-serif font for headings and captions (this can also be the same font used for the main text). Emphasis can be indicated by italics (or slanted text) or for stronger emphasis use bold text. If you use more fonts you should have a very good reason for this to support the content.
Site Tools

Page Tools
