Thread: Proper Documentation of Code

I'm in the process of changing Job roles and I don't want to leave my replacement in the dark as to the workbooks I have put together. One in particular is a front end order management system for SQL Server and is very object orientated.

I've no idea how VBA savvy the person who will look after the bits I've put together will be and I want to make things as simple as possible for them, so I'm trying to put together some documentation in case things need changing/go wrong.

From your experience, what's the best way of doing this and do you have any good links to guides as to make this as simple as possible. I have quite heavily commented the code, but it's difficult to have an objective viewpoint.

Cheers

Kyle

Hello Kyle,

When I worked at Standford Linear Accelerator Center, I wrote numerous test programs for the modules used by the physicists in their experiments. Each program had its own user guide and appendix to the program functions. What I learned along the way was the level of documentation depends on the user's needs and level of understanding about the subject.

What was useful for a physicist was not suited for an admin assistant. I your case, a lot will depend on the your replacements abilities and knowledge. If you are directly involved with choosing your replacement then your job is much easier. Otherwise, you will have to use your best judgement on the level of detail and time you have to spend on this project.

There are many programs available to help you create documents but what goes in them is up to you. Keep it simple, concise, easy to read (lots of white space), include illustrations, and move sequentially through the process. Most importantly, remember you can not plan for every problem or question that may arise. You are providing guide to help the person using it ask the right questions when there is a problem.

Thanks Leith, that's really useful.

Unfortunately, I'm unlikely to be involved in choosing a replacement.. I'll be long gone

Could you recommend any free UML applications?

Probably:

- writing down your coding style/habits
- leaving a functioning telephone number
- a working email address
- an agreement with your employer to reserve a total of a week to answer questions.

Documentation for an unknown audience is a huge amount of work that
- will not be read
- is 'too elaborate'
- is 'describing the obvious'
- is 'underestimating the reader's intellectual level'

The cost/benefit ratio is more often then not negative.
So I'd suggest to adapt to the successor's level/interests..

Thanks snb, useful points.

I think then that a class diagram and copious comments along with contact details and an overview of what's going on would be best.