Documenting as a contractor

Question

Hi All, I am a contractor for a small software firm, and am wondering what sort of documentation other contractors tend to create to make things easier for the guy that comes after them? My current contract is a semi-permanent position, but I'd like to leave everything in good condition for anyone else who has to work on parts of the system I've built.

Currently I've done nothing but try to make readable code. The system is quite complex and I have rewritten a few parts, so the knowledge I have would be quite useful, but I don't know how to put it into writing.

Answer 1

It is always important to have your code clean and clear enough that someone can come behind you and understand what you were doing.

You do not have to tell them exactly how you are going to do it but I would recommend at least describing what you are doing in general and the important things that you think they should know before working on a complex set of code

Answer 2

Documenting is important, but time consuming. If it is in your contract then by all means document. If the customer is short sighted enough to skimp on documentation, look for another customer to contract with (of course they could also become a cash cow since no one else but you will understand the code).

Answer 3

I would create a one to two page design document, very high level, zoom out and show all of the components.

I would create a build document. This is the "how-to" install and configure any dependencies your system has. Make this as long as it needs to be and use plenty of screenshots.

If you're documenting for a development firm, then use SandCastle for .NET or JavaDoc for Java. Any developer should be able to work with documentation in that style.

Answer 4

Your system will have various sets of stakeholders:

• Developers that inherit the system. These people will need to know where to find stuff and specification documents - particularly of any fiddly bits or interfaces.

• QA people will need specifications in enough detail to develop test plans off.

• Business sponsors will want some sort of document that they can use to understand what they are getting.

• End users will want some sort of user manual, or at least a cheat sheet of a few pages to show them how to get into the system.

• Ops people will want an operations manual so they can see how to troubleshoot it in production.

I've found that a functional specification covering the basics of the app gets a pretty good sweet spot. It should have these items:

• Screens.

• Some sort of documentation for the data model. At a minimum you can reverse-engineer it in Visio and make some E-R models. Don't forget to show the data types foreign and any primary or unique keys. The data model has a lot of stakeholders. Developers and QA people will use it extensively. Also, anyone interfacing into the system (for example a data warehouse project team writing an extractor), writing reports or doing anything involving data will use the data model docs extensively.

• Data items and business rules for the screens with mappings to the database (this is a biggie for devs and QA types).

• Screen-screen flows where there is something non-obvious or intersting about them.

• Any interfaces should have mappings in the spec.

• User and ops documentation should be quite brief in most cases. These really need to be a cheat sheet and a manual to show ops people how to deploy and where things like error logs go.

• The spec should also have an architectural overview so developers can find their way around the code-base.

Functional specs are a bit of a drag to do with Word - I recommend Framemaker if you can get the Powers that Be to fork up for it. Specs of this sort are quite easy to do with a data model and screen shots from the application or a prototype. One nice feature of framemaker is the ability to import parts of the document, such as a data dictionary, and have stable index and cross-reference anchors. This means you can partially generate those parts of the document that lend themselves to this, and have two-way cross-referencing in and out of them (thanks to the stable anchors).