An Abstract View of Documentation

I've been thinking a little about the documentation of a system.

I think that there are two sorts:

• Descriptive
• Transformative

Descriptive documentation describes a system at a given state of time.

Transformative documentation describes the transformation of a system as a result of change.

Transformative documentation is only maintained for the duration of the change and is thereafter left as a record of the change. The work defined by transformative documentation results in change to the descriptive documentation.

Descriptive documentation is maintained for the lifetime of the system and is changed as the system is changed.

I think that by classifying documentation in this way one can start to define what documentation is required.

Ideally descriptive documentation should provide a clear, succinct and easily maintainable view of the system in question. Transformative documentation needs to clearly define the necessary changes and only be maintained to correct mistakes.

Prototyping

I've been working on defining development processes for NHSBT and have been discussing useful forms of prototypes.

The way I see it there are two main classifications:

• User Interface Prototype
• Technology Prototype

One typically prototypes to communicate concepts to a user or to prove a technology.

I tend to use two types of User Interface Prototype:

• Wireframe
  
• Ghost Town
  

A wireframe prototype is used in most projects that have a UI. It is typically a set of drawings (electronic or paper) that show the layout and flow of the UI screens. It is great when you have experienced users who are familiar with a broadly similar application and can visualise the final functionality. It falls down badly when the users are unfamiliar with the type of functionality.

A ghost town prototype fills in the gap. The UI is implemented in actual code as a shell with no actual business logic or persistence. It is called a 'ghost town' because it is like the towns in western shows and films where the entire street is just a set of thin facades held up by beams and boxes. The UI is fully interactive and it makes it very easy for the user to grasp the functionality. Traditionally ghost towns were considered 'throw away'; nowadays with the Model View Controller pattern it is very easy to implement ghost towns where the majority of code can be reused. The only real drawback is that they can give a false impression to the user that the application is finished and ready.

There are also only two technology prototype forms that I use:

• Proof of Concept
• Tracer Bullet

The proof of concept is a purely exploratory prototype which is done to investigate a new technology. It follows a simple process of writing code and seeing if it works in the expected way. This prototype can be very dangerous if clear goals and criteria are not established early on as it can become very undirected and any decisions made as a result can become matters of opinion that may not be in the best interests of the wider project or programme. The proof of concept should always be written expecting to throw the code away as the technology being investigated may not be suitable; that does not mean that the code should be written as if it were expected to be thrown away. A poorly written proof of concept can be less than useless in evaluating a technology, also with modern refactoring a successful proof of concept can be turned into production code.

The tracer bullet is used when the choice of technology is well established but the particular technology stack has never been used before. A very thin vertical slice of functionality is selected that touches all the novel integrations and the prototype is written to implement it. This prototype should always be of production quality as the code it produces will define the patterns and standards for the finished application and will normally be the first check in to the development repository.

These are the types of prototype that I use on a regular basis, are there any that I should be using that I have missed?

I've got to be careful not to let it grow out of control...

I've been working and thinking about my encrypted zip framework and in the process of refactoring and abstracting I find myself teetering on the brink of creating a grand unified storage framework for Java, where one defines 'entries' and those can be stored to filesystem, database, zip file, etc.

I think that a Grand Unified Storage Framework would not be a bad thing as I have long been frustrated at the Java API differences in writing data to the different storage media, but I really should focus on delivering the encrypted zip framework. I think that I need to keep the GUSF in mind so that whatever I produce for encrypted zip can be rolled in.

Mobile Broadband

Well I've taken the plunge and have got mobile broadband from T-Mobile.

I'm still trying to work out how to get access the the wireless hotspots as I need to send a text using my SIM card to get a username and password.

I think that I'm just going to have to stick the SIM card in my normal phone, send the text and see what happens.

I've been working on the Encrypted Zip on the train to and from work and having access to the internet has been a godsend. Especially when negotiating the deep, dark waters of Java Cryptography. Why are the APIs so overcomplicated? I'm facade-ing a lot away and so may end up with some classes that will be of wider use.

I'm also swearing at the wider Cryptography community. There is a dearth of decent keystore standards and implementations. For those who don't know what a keystore is, it is a type of file where you keep the keys and certificates that you use to encrypt things and to prove your identity online. The only broadly portable 'standard' keystore is PKCS#12 which is widely held up as an example of how not to create a cryptography standard. In my implementation I'll probably have to default to simple password based encryption and allow users to specify better levels of encryption at the cost of reduced cross-platform portability.

On the other hand I have working code and am beginning to see my way clear to a working encrypted zip.