This document gives a brief example of the sort of things that the requirements stage of the project should be concerned with. It starts with a very brief description of the project, similar to those available to you, and shows how this may be developed into a reasonable set of requirements from which a report can be written. Note that there are no hard and fast rules for this stage. We simply want you to think about the project you have chosen, and about possible solutions to it, and communicate them in written and oral form. As far as possible, try to be innovative. Do not let your current programming abilities cloud your imagination. That is, at this stage, do not think about how you will write such a program or how much effort it will take to do so. Later on we can restrict the design to whatever is realistically possible in one semester and leave the rest as extensions for improved versions in the future!
| The understanding/comprehension of paper-based documents is often aided by the inclusion of margin notes and by highlighting important sections using fluorescent marker pens. Since many people are now reading texts in electronic form, a program which can provide such aids to understanding would be a useful tool. |
Although this description seems very explicit in asking for margin notes and highlighting of electronic texts, it is a good idea to do a little brainstorming at the start. Ask yourself what additional things one might do to help achieve the goal of improving understanding of a text. Indeed, what exactly constitutes improved understanding? Does it mean remembering details or being able to appreciate the relationship of ideas inside or outside the specific text, or does it entail doing these things quicker than would otherwise be the case? What is or could be done with just paper and pencil? What further possibilities does the computer offer? Newspapers, magazines and journals commonly provide abstracts or summaries of books and articles. They may also offer reviews (personal opinion or commentary) on the original text. References to related material may be made, enabling it to be better placed in context. While margin notes can handle almost everything one might wish to say about a text, they may not always be the most convenient form. Certain tasks might be eased through the use of "between-the-lines" comments or perhaps by "crossing-out" some sections. The computer can obviously help in several ways. For example, there need be no limit on the size of margin notes, whole sections of text might be temporarily hidden or replaced with a summary. Related material or sections could be available at the touch of a button, or the same text could be marked in many different ways (perhaps by different people). The possibilities are endless!
Another question you should probably ask yourself at this point, is who might make use of such a program. Having identified possible users ask again what sort of facilities the program might offer that would help them to do their job. Obviously, in this case the intended users are researchers, and possibly students, who have to read potentially long and complex texts as part of their studies. However, once we recognise that the program is generally concerned with the "marking-up" of a text, a number of other possible users come to mind, for example, editors and teachers. What other facilities might they find useful? Well, teachers grading student assignments might wish to write notes which relate to two parts of a text, such as "you say this here, but then contradict yourself here". They may wish to simply indicate passages which are suspect, or which need rewriting, or which are particularly good or important.
Having done the brainstorming it is time to collect the ideas together and present them. Your report is a formal document by which you and the project will be judged, therefore, it is important that you make it as clear and precise as possible. It must be prepared using this CS102 Project Reports template. Note: This is a Word 2003 template that includes a macro to insert references into the text in the approved style. To enable the macro on newer versions of Word you need to click Review|Protect Document then select "Restrict Format & Editing" and finally click the "Stop protection" button on the newly opened tab.
This particular report is going to be relatively short, however, it is important that you present the ideas in a logical and easy to understand fashion. Remember, if people can't make sense of what you are saying, they won't buy the project/product and hence you will go hungry! The contents should offer a functional description of the program you intend to produce. Perhaps the easiest way to start this is to think of the report as if it were a sales brochure for your finished program. In other words, think about the sort of things you would need to say to potential customers in order to help them decide whether to buy/use it (however, be careful not to exaggerate!) It should probably provide answers to the following sorts of question,
What is it for? Motivate the need for such a program. Who will use it? What does it do? What facilities does it provide? What advantages/features does it offer (disadvantages?)
Do any similar products already exist? If so, provide brief details and references, and indicate what advantages yours might provide. Besides answering these questions it is also a good idea to try to distinguish between features that you consider essential, those which are merely nice, and those that will certainly be left for future extensions. The final report need not be very long (three to five pages would be reasonable), however, it should be self-contained, precise and easy to understand. Above all it should demonstrate that you have thought about the problem. It should not make wild claims or use advertising speak! Below is a brief example report for the problem given above (obviously, yours should be longer and more detailed, and better structured).
CS102 Project Instructor: David Davenport Group: 1A Assistant: T.A. Ornek An Electronic Aid to Text Understanding
NoHackersPlease!
David Davenport & Erkan Tin
Project Requirements Report
( version 1.0 )
7th Feb. 2001
Introduction Understanding long articles, particularly complex scientific texts, has always been something of a problem for researchers and students. There are a number of methods which readers commonly employ to help improve their understanding and/or comprehension of paper-based texts, including, for example, margin notes and highlighting with fluorescent marker pens. Increasingly, however, text is becoming available in electronic form where these techniques are not readily applied. We therefore propose an electronic reading aid which will provide the user with a range of facilities which can be employed to help improve comprehension of computer-based text. This tool will be of interest to researchers attempting to make sense of complex research articles and to students who may receive texts which have already been "marked-up" to make them easier to understand. Eventually authors may create their texts in such a form, making them more accessible right from the start. The tool will also be of interest to editors and teachers, since it will enable them to write comments, corrections, etc. on an electronic text, without disturbing the original. Features The electronic reading aid functions by allowing users to create any number of different "views" on a given text. The original text remains unchanged, a view simply presents the document in a modified form, thus the reader can refer back to the original text whenever they wish. The program provides the following facilities: - New views can be created and existing ones modified or deleted. - Any section of text can be hidden and optionally replaced with some new text. This allows less important details to be hidden, or parts of the document to be summarised or rewritten. The changes will generally be presented in some clearly identifiable form, for example, a different font or colour, thus signaling to the reader that it is not the original text. Such modifications can be edited, temporarily undone, or permanently removed. - Margin notes corresponding to any section of the text can be created, edited and deleted. - The user can define styles (which specify in what font, colours, etc. the text should be shown) and use them to change the appearance of any section of a document. This feature allows for a generalisation of the idea of marking important parts of a text using a fluorescent pen. The user can create styles with names like "highlight", "excellent" and "rewrite," each of which gets displayed in a different manner. For example, "highlight" might simply change the background colour to yellow, while "excellent" changes the text colour to green and "rewrite" is shown in strikeout. - Search facilities which enable the user to rapidly locate any text string or type of modification. For example, find the next occurrence of the string "comput" or find the next occurrence of text in the "rewrite" style. - The user can establish links between any two sections of a document and optionally add notes on the link. Readers will be able to quickly jump from text at one end of a link to text at the other and/or read the associated note. This facility will allow the reader to see relationships between various parts of a document or to quickly view references or notes which tend to be expanded at the end of technical articles. - The ability to place freehand drawings (scribbles?) over any part of a document may be a useful feature. This is not considered essential and may be left for future versions. Conclusion & Reflections This report developed the features required for a new and, hopefully, unique product intended to help students, teachers and researchers, improve their ability to understand complex texts. Applying computer technology to what was previously a manual task, has enabled us to come up with some new and innovative solutions that really exploit the advantages technology can offer. |
The above report is only an example, one which could certainly be improved. For example, there are other features which should perhaps have been included: the ability to print a view or to save it as text, the facility to move a section of text to another place, links to other files or url's, on-line help, etc. There are also questions which still need answering, such as whether the tool will work only with plain ascii text or whether it will allow HTML, MSWord, Postscript & RTF files to be worked on. The important point, however, is that your intentions are now explicitly listed and available for discussion and thus, hopefully, improvement. Sorting out a suitable set of requirements at the beginning of a project will stop you wasting considerable time and money later.
Finally, do not leave it to the last minute to write the report. Ensure you have enough time for at least one group member to give it a critical reading before submission. Correct as many omissions and mistakes as you can, and do, please, spell check your report before handing it in!
(c) 1996, 2001, 2011 - David Davenport
----------------------- O -------------------------