Part 6 - Describe the solution
In this part of developing a solution to a problem, you need to:
a) Explain and justify the structure of the solution.
b) Describe the parts of the solution using algorithms justifying how these algorithms form a complete solution to the problem.
c) Describe useability features to be included in the solution.
d) Identify key variables / data structures / classes / justifying choices and any necessary validation.
Things to consider doing:
a) Put a heading, The structure of the solution.
b) Look back at the previous section Part 5 and the list of jobs generated by decomposing the problem. One approach to justifying the structure of your solution could be to draw a very simple block diagram, showing how all of the parts identified in Part 5 are connected together or related. You can then give examples related to this diagram. For example:
You might talk about making sure that you have made sure each of your functions all do just one job, to make writing, debugging, understanding and documenting them easier, and give an example to illustrate this.
You might discuss the naming convention you have chosen for all data, and why this is important, and again, give examples.
You could discuss with an example the different user screens and how you have deliberately designed them in a consistent way to make sure the product 'feels' like one product.
c) Put a heading, Algorithms.
d) You should identify those parts of your solution that need coding, ideally in functions. You should then write algorithms for each of those functions. You can use whatever method is easiest for you to write the agorithms, either pseudo-code or flow diagrams, for example. You could start by simply writing out in short English statements what you want the code for a function to do, and then turn your statements into something more akin to pseudo-code.
e) Next, you need to make some observations about how all of your algorithms together form a complete solution to the problem.
f) Put a heading, Useability features.
g) You should give some examples of the design decisions you deliberately made to make the solution easy to use. For example:
You could discuss the use of consistent fonts, sizes and colours. A good way to do this is to produce a table that details what style should be applied to main headings, sub-headings, main text and so on. The same thing applies to buttons and menus and any other objects that may be included. If you put these things into a table and specify their design, you are demonstrating that you are thinking about consistency, and an understanding that that makes your system easier to use.
You could discuss the use of a HELP menu, a contextual help system or the use of tool tips.
You could discuss with examples your deliberate selection of colour choices.
h) Put a heading, Data structures and data.
i) You should write a few sentences defining the naming convention you will follow for naming variables, constants, data structures, functions, procedures, modules, libraries you create etc. And then you should make sure you follow it when writing your code.
j) You should create a data dictionary for the data items that will be used. This is simply a table that holds all the variables and constants in your program. The typical headings used in a data dictionary are Name of data, Data type, Example of a piece of actual data, the Validation rules that should apply to the data and finally, why you need that data.
k) You should create another table that holds the data structures that you will use. This should state the Name of the data structure, Type of data structure it is, What it is used for, Any other details e.g. size and finally, why you need that data structure.
l) You should create another table that holds details of any functions. Typical details will include the Name of the function, Purpose, Parameters it expects, Parameters returned and Any other details.
m) You should have another table for any other data or structures you intend using. For example, you may create your own modules or use some you have already written. You may be using a library of standard sort or search algorithms or using your own library. The details of these should go in your final table, including descriptions of them and why you are using them or creating them.
n) As you write your program, you should ensure these tables are kept up-to-date. This is because they form one part of your documentation and are a critical part of the documentation needed for maintenance.
o) If you are using an Object Oriented language, you should include a UML diagram, showing the classes, inheritance, names, attributes and methods in your solution.