There is an old adage in business that says that it is easier to sell to existing customers than to go after new ones. With that in mind, it behooves me to take advantage of every marketing opportunity we have with our existing customers. One such occasion I had recently was with the final delivery of a custom Java application. The project went smoothly and everyone was pleased with the end result. When it came time to deliver the files and complete the hand-off to the client, I put forth a little bit of extra effort in compiling a complete and organized package of files and documentation. This wasn’t asked for, and it probably will not even be noticed immediately. However, it will pay off in enforcing an image of professionalism and it is a small step in differentiating ourselves from our competitors.
First, we made sure that the final version of the application was running smoothly on their non-production servers, i.e. the development, test and UAT environments. (For various reasons unrelated to the project, the deployment to production will happen at a later date.) Once the application was verified, I put together the following package of files and documentation, in three separate folders:
1. Deployment folder – Here I put all the files required for deploying the application to the production server:
- database scripts – the SQL code required to upgrade the production application database
- ear file – built specifically for their production environment, ready to be deployed on the application server
- application specific files – document templates and sample files that the business users will require in order to use the software
2. Source folder – All the source code and everything the client would need to continue development. Everything is provided as Eclipse projects. The code has a consistent style. It is well commented and clean of ambiguous or incriminating comments: no TODOs or FIXMEs.
3. Documentation folder – The value of good documentation is not always recognized immediately, but it will be helpful in the future, whether the client continues development with an in-house team, hands the project off to another company, or even if it comes back to us in a few months or years. The following documents were included:
- Technical Requirements Specification – This document was already approved by the client. Describes in detail what was to be built.
- Addendum to the Technical Requirements Specification – All the changes made to the specifications after they were approved and the reasons behind the changes.
- Database Preparation Guide – Explains how to make the required changes to the application database.
- Deployment Instructions – How to deploy the application and an explanation of the configurable parameters available.
- Initial Configuration Guide – What has to be done by the application administrator to prepare the software for use by the business users.
- Release Notes – Explains quirks that might be confusing for users, administrators and future developers of the application. It is compiled from emails I tagged throughout the project and notes from defects that were not fixable.
- Developer Intro Guide – Explains the project structure, how the included open source technologies are used (Hibernate, Spring, etc.), how to start some basic development tasks, how to set up in Eclipse, and how to build the ear file for different environments.
- Development Road Map – Ideas for enhancements to improve the applications. Some of these came out during UAT, some were suggested by various members of the project team.
You might notice that there is no user guide. The user manual was taken on by the client themselves, written by their own freelance contractor. Technical writing is not our specialty, so we would rather not take that on anyway.