Having up to date and relevant documentation is a challenge for any software maintenance team. The key to success is to write a minimum of documentation, but make sure that it is relevant. The details can always be sorted out from the code. The external documentation (that is not in the code) should focus on being a good introduction by giving an overview.
The documentation should point in the right direction to get started working with the code base and show what modules there are. It is a bit like when first arriving at a resort. You’d expect a map and some directional signs to use until you’ve got to know your way around the area.
Before going into how it looks like, let’s consider how it would be if the resort was documented the way most code is.
The instructions where clear: “Drive 24.7 km on the main road north, then take off to the right”.
The trip meter now is on 24.7 km. It is dark. No street lights to be seen anywhere close. No signs. No road to the right. Nothing but a trail of mud and sand between the dark trees. Well this is where it should be, so you take to the right.
The ride is bumpy but it is clear that cars regularly drive here. Suddenly the mud and sand is replace by a proper concrete road. The forest leaves place for a beautiful view of the large, luxurious resort close to a moonlit lake. You park the car among the other cars (although there is no parking sign, but it must be here) and head off towards the main building.
You find a closed door. There is a well used path in the grass around the corner so you follow it, just to end up on a small beach, still carrying your luggage. Going back you see a door which is open and head over there. It is the restaurant, but at least you find a waiter that can show you the way to the reception.
The receptionist is nice and your check in is processed quickly. You get the keys and head over to the elevator. Once inside you check for the right floor for your room number which is: D7BC. There is no D on the panel. Just plain numbers 1-15. Before you can decide what to do the elevator moves on to floor 7 where a family is waiting to get in the elevator. You get off to leave room and have time to think.
Think this is ridiculous? Unfortunately this is the very same feeling that I far too often get when first looking at a new code base. I’m not finished yet, there’s more to come…