CA465 Project Preparation - Functional Specification Reviews

Name:                   David Reade 

Class:                 CASE4

Student Number:  99755629

Introduction

Writing a Functional Specification document is an extremely important part of any project life cycle. They are technical documents and so should be correct and concise and should always be presented formally and professionally.

The functional specifications which we write for our final year projects will be the last chance that we get to develop our writing skills before we enter the corporate world, and for this reason, producing this document should not be taken lightly.

Functional Specifications are produced in industry for the attention of management while being a guiding set of rules for a project team to work to. For this reason I have chosen to view the specs as if I were an IT manager and that these specs were for important projects being produced by what I would consider professional employees. Functional Specs should clearly make management confident in the ability of the employee to develop and complete the specified project efficiently and to the set of guidelines outlined in the document. They should not create any sense of doubt in the mind of management regarding the person’s ability and any points in the document, which for valid reasons cannot be developed further should be presented in a manner, which is both professional and assuring to management.

As these documents are not for the attention of the management in some large multi-national and the writers will not face unemployment at the production of bad documentation some small amount of leeway must be given to the writers, as they would not have had the experience of producing documentation that would be presented to management in real world situations. This does not however suggest that these documents are any less important than those produced in industry but rather allow for the fact that most students will not receive detailed feedback on the submission of functional specs which they have produced.

Reviewing documentation is only partly standardised and the rest is the personal opinion of the reviewer. Each document needs a clear layout structure and quality content but some areas such as writing style and font selection differ with each reader. During these reviews I will detail any areas that I feel are of a personal opinion and which other readers might not share.

For each doc I have decided to review them under the following headings while at the end of the review I will summarise in point form what I believe are the strengths and weaknesses of each document.

1.      General Layout

2.      Quality of content

3.      Writing Style

4.      Overall

Review 1: Simulated Shoal of Fish by Barry Handleman

1.     General Layout

At a first glance this document gives a good impression, it appears easy to read and is written in a fairly effective and naturally flowing layout. It is clearly broken down into readable paragraphs and sections, with clear headings and sub-headings. All of these features result in the document being easy to browse over and to get a feel for and in my opinion allows for easy inspection of the document.

2.     Quality of content

The quality of content varies at times throughout this document. Sometimes the author seems unsure of the way in which he intends this project to develop and he creates a general sense of uncertainty. In the introduction he does explain that this is not a final version and it will be updated as he does more research. This alone gives the impression that he has not fully prepared for writing this document and more planning should have went into preparing the content of it.

He does clearly layout the aim of the project, he portrays a clear picture of what he hopes to achieve but at times not exactly how he intends to achieve it. He also gives reference to where the idea came from and a link to it that allows any reader the chance to learn more about his direction with the project.

The overall quality of the content is mixed, the author has established the project aims but has not effectively detailed his intended guidelines for development. At times I feel the document is more reflective of a project proposal rather than of a functional specification document.

3.     Writing Style

The first line of the introduction sets the style of writing for the whole document. ‘This is a function specification for my 4th year project’. In my opinion the author fails to portray a solid base from where to start. This line conveys the feeling that the author himself is not fully confident with the document as he writes ‘This is a’ rather than ‘This is the’ which is reflective of a type of ambiguity whereby this is not the only functional specification for this project.

The author uses a number of terms throughout the document, which I feel again give a negative impression. His style includes phrases like ‘attempt to schedule the workload’ and ‘the system will probably be based on’ which again convey an uncertainty in his confidence.

The final point on his style of writing is his spelling mistakes and grammatical errors. The author should have taken more care in proof reading the document and should maybe have got one or two other people to check the document for any mistakes before submission. Examples of errors are ‘fishes’ instead of ‘fish’ and ‘there’ instead of ‘their’.

4.  Overall

Overall this document is not a bad attempt but resembles a first draft more than a version ready for submission. If the content had been more clearly decided on then I feel that the author could have prepared this document far more confidently and would have produced a more direct and professional publication.

Strengths

                        1. Gives a good first impression - readable.

                        2. Effective and flowing layout.

                        3. Conveys the final result that he wishes to end up with.

                        4. Gives the background to him choosing this project with a reference.

Weaknesses

                     1. General uncertainty as to how he will approach this project.

                     2. Portrays a lack of confidence in his ability to develop the project.

                     3. He points out too often that he needs to do more ‘adequate research’.

                     4. Writing style is at times unclear and reflective of a first draft.

 

Review 2: Search Engine by Ian Wright

1.   General Layout

This document gives a bad first impression. It is blocky and badly spaced out. The author uses a mixture of different fonts, which give an erratic shape to the document. The structure improves in the reference section but this along with the bad use of mixed fonts give the impression of inconsistency.

This document also has badly structured use of sub headings. The sub-levels in section two range from 2.1 to 2.1.4 without going to 2.2. This is an in effective use of structuring and adds to an overall feeling of inconsistency in the document.

The final point on the visual layout of the document is that, in my opinion this document comes from the old school of badly laid out technical documents whereby technically complicated material was presented in a technically complicated manner.

2.       Quality of content

The quality of content in this document starts off pretty well with the author getting to the point about the project in a simple and precise fashion. This continues as he outlines his objectives, constraints and his justification for attempting this project.

The data description is informative but reads more like a brief overview and I feel that a more detailed description was necessary here to show that this project has been researched thoroughly and that the author knows what path he will be taking in developing the project.

After this the quality of content drops enormously. If this was a functional specification for an important company project, I don’t think that any manager would be happy with the projected schedule reading anything like ‘Hell for leather from the Monday after I finish my exams in April’. This shows that the author is unprepared for developing this project and entries like this will never be taken seriously in any professional context.

3.       Writing Style

Again I feel that the first line of any document is essential in portraying the author as a capable and confident person who has put time and effort into developing this documentation. The first line of this document gives the impression that the author has not taken the time to read over it once it has been written and has no idea of how it reads to other people. I believe the following line would have been more effective. ‘My final year project will involve taking the document-query matching algorithm TF*IDF and building a search engine index over more…..’. I personally feel that the sentence started in this way is more readable and flowing.

The author also makes some confusing statements such as ‘These are the approximate scales to which Google – the best search engine at the moment’. This leaves the reader unsure whether he means to which Google runs or to just Google and adds to a feeling of confusion on the part of the reader.

The document also contains typing errors such as ‘thetechnology’ which if proof reading had taken place would certainly have been spotted.

4.       Overall

Overall I would rate this document poorly as a finalised version of a functional specification. The layout is structured badly and the quality of the content which starts off alright soon deteriorates and displays a lack of planning in the development of this document. However this document would again be a good first draft and with a little work on the layout and more detailed content could be acceptable for submission as a final specification document.

Strengths

                     1. Good overview of the project as a whole.

                     2. Data description starts off good and could be improved with more detail

                     3. The reference section is well laid out and informative.

Weaknesses

                     1. Bad layout – Text packed too closely together, bad use of sub-headings.

                     2. Use of different fonts makes the document harder to read.

                     3. Little detail about how the project will be approached and achieved.

                     4. Bad use of language – casual and at times confusing.

                     5. Coveys a lack of planning and does not seem to have been re-read once written.

 

Review 3: Documentation made Easy by Jen and Jenna

1.     General Layout

This document gives a very good first impression with a well thought out structure and a clear and easy to navigate table of contents. I found the colour of font made the document slightly difficult to read but that’s more of a personal aspect than of any fault of the authors.

There is a good use of diagrams in this specification to clearly lay out in a visually sound way the concepts and ideas in the project. I feel that the only real minor fault with the document is layout of the text. I think that it would be easier to read if the sections were more clearly broken up into paragraphs with the possible use of points to develop a more robust layout. 

2.     Quality of content

The quality of content in this document is at a very high level. All areas of the development process are laid out with clear guidelines and are well detailed as well as being informative. This shows that a lot of research and effort has gone into developing this document and that the authors have developed a clear and complete plan on how to approach and develop this project.

This document covers all relevant areas of the project and leaves little room for misinterpretation of any aspects of the system which they intend to develop. In the real world any manager would be happy with the directness and completeness of the information contained within this document. The authors provide a clear and concise description of the project and the development cycle as well as a detailed explanation for the reasons behind them choosing this specific project.

There is a general sense of completeness to this document, the objectives and constraints are well detailed and all areas of the system architecture and subsystem are clearly defined with guidelines set out. The authors have also given a complete outline of the schedule by which they intend to develop the project. This again shows that adequate research and preparation has taken place before this document was produced.

3.     Writing Style

It is evident from reading this document that it is not the first draft which the authors have submitted but rather a document which has been read and re-read until it was of a necessary high standard. Maybe the fact that there were two people involved in the project ensured that it was at least read by one other person. The first line of the introduction creates the notion of decisiveness and confidence and does not create any doubt in the mind of the reader regarding the abilities of the authors.

The overall style is descriptive and informative and well presented to the reader. This shows that the authors had a clear vision for their project and a natural ability to transfer that vision onto paper.

4.     Overall

Overall I would rate this document higher than the other two. It is well researched and well presented with a good use of diagrams to portray their intentions. There are one or two very small mistakes which any modern word processor would have picked up such as the misspelling of ‘Important’ but these do not take much away from the complete and well-documented development process which the authors have cleanly laid out in this publication

Strengths

                     1. Good layout, thorough and not confusing – easily navigable

                     2. Document and project both well researched and planned

                     3. Provides efficient guidelines for all stages of the project.

                     4. Good use of diagrams to explain concepts in detail.

                     5. Complete and detailed description of the architecture involved

                     6. Full list of requirements – software and hardware necessary.

Weaknesses

                     1. First few paragraphs could be a little better spaced out.

                     2. Colour of the font – personal opinion

David Reade Computer Applications Software Engineering - Last updated November 2002
-
Projects Semester 1

Project Preparation
OO Project
Databases
Multimedia Essay
Graphics Assignment

Project Semester 2

OO Models Z-specification
Multimedia Essay
Distributed Assignment I
Distributed Assignment II --

Final Year Project

1. Proposal
2. Functional Spec.
3. Technical Manual
4. User Manual

Third Year Project

1. Functional Spec.
2. Technical Manual
3. User Manual
4. Battleship Game

Course Description

Computer Applications

Subjects Semester 1

1. Object Oriented Metrics
2. Multimedia Retrieval
3. Computer Graphics
4. Database Theory
5. Project Preparation
6. Digital Signal Processing

Subjects Semester 2

1. Object Oriented Models
2. Distributed Prog.
3. Multimedia Technology
4. Final Year Project

Structure in Years

1. First Year
2. Second Year
3. Third Year
4. Fourth Year