Site Tools

Trace:
using_descriptive_devices

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
using_descriptive_devices [2011/11/11 14:20] – scmfclusing_descriptive_devices [2022/05/04 16:10] (current) – [Figures] scmfcl
Line 1: Line 1:
 ====== Using Descriptive Devices ====== ====== Using Descriptive Devices ======
  
-Here we will mention some well-established descriptive devices which you can use in your project report to improve its quality.+Here we mention some well-established descriptive devices which you can use in your project report to improve its quality.
  
 ===== Cross-references ===== ===== Cross-references =====
  
 Cross-references are just references to other parts of the same document. For example, Cross-references are just references to other parts of the same document. For example,
- 
 <code> <code>
 This module contains procedures for operating on variables of type WINDOW (see Section 2.2). This module contains procedures for operating on variables of type WINDOW (see Section 2.2).
Line 14: Line 13:
  
 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, 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> <code>
 This procedure uses the Volestrangler algorithm (to be described in Section 4.3). This procedure uses the Volestrangler algorithm (to be described in Section 4.3).
 </code> </code>
- 
 Note that too many forward references are probably an indication that the report could be organised better. Note that too many forward references are probably an indication that the report could be organised better.
  
Line 27: Line 24:
 ===== Lists ===== ===== 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” list1. Various examples of bullet lists appear throughout this guide. 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.+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 Section [[References]]). However, keys should only be used when necessary.+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 ===== ===== Figures =====
Line 39: Line 36:
 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. 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. picture 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 patial photographs that you merge afterwrds) of the artefact and include it in your report as any other computer generated image (help from staff for this is available and you may bring the original artefact to the viva).+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, All figures should be labelled and captioned, for example,
- 
 <code> <code>
 Figure 3.10: Sub-System Architecture. Figure 3.10: Sub-System Architecture.
Line 48: Line 44:
  
 The label can then be used to refer to the diagram within the text, e.g. The label can then be used to refer to the diagram within the text, e.g.
- 
 <code> <code>
 See Figure 3.10. See Figure 3.10.
Line 55: Line 50:
 All diagrams must be explicitly referred to somewhere within the text.  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 Section Cross-references). +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 separte 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.+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 ===== ===== 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”. For example: +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".
- +
-<code> +
-The procedure draw_circle (p:POINT, r:REAL) draws a circle of radius r at point p on the screen. +
-</code>+
  
 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. 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 stronger using bold text. If you use more fonts you should have a very good reason for this to support the content. +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.
  
using_descriptive_devices.1321021236.txt.gz · Last modified: 2011/11/11 14:20 by scmfcl

Page Tools

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Noncommercial-Share Alike 4.0 International