Document it Please

Very good technical documentation skills are a must for any Software Engineer - to explain how a system works in detail forces you to think about the flaws present within the design. “Bad smells” of documentation often can be a sign of weaknesses on your product. Is this section too verbose or did we make it too complex for the customer? Should we explain ancillary parts of our system (either operating system components or other applications?) within our documentation besides the inherent risks (out-of-date documentation)?

These are all tough questions, but the important part is: it makes you stop and think. This not only applies to your customer facing documents, but internal documentation. In my job I am mostly the one who updates the “New Starts” section of our internal documentation. It is of huge benefit to any new starters on my team, to get them up to speed fast on our processes, tools and ways of working. I believe it saves the new person and myself countless hours of often trivial questions. Of course I always happily answer (and enjoy answering) the tough questions also. This is all well and I hear you say, you get productive software engineers faster, but what is in it for me as a company?

Better retention of customers for one. Recognising the need to keep things simple, have a short and easy to comprehend manual goes a long way to keeping customers loyal. I’ve been told that the biggest complaint received is poor documentation and we’re lucky that our customers are very forthright and vocal. Good documentation is understandably hard to do, time consuming and easy to sweep aside due to time and cost pressures. In a world where operational expenditure is a key pressure (in both employee and customer time) - I firmly believe that money spent reducing support costs is a very worthwhile investment. Like investments in refactoring code, these investments take time to pay off - but ultimately will.