Software Documentation: What You Need to Document and How
Software documentation is all about bringing clarity into a code baseline. It provides clues to clarify the meaning of certain code structures. For this purpose, we use best programming practices and tools to clarify our software.?When documenting software, we aim to minimize time spent hunting for meaning. We want anyone using or reading our code to know exactly what we meant when we wrote it. In addition, they should also know how to use our code without having to look for extra clues. Whether it’s an API, a suite of REST services, or simply a method in your code, it should all be clear.? When things are not clear, you have to dig up the meaning from other parts of the code, and this is a waste of time.
In this article, we’ll explore what information to document and how to do it. Lastly, we will talk about presenting our software documentation.
One of the most anticipated acts at a circus is the juggler?a performer who can move five or six or more balls in the air at the same time. The really complicated juggling acts, however, add something extra to wow the crowd. The juggler?first climbs some stairs, high up but still close enough for everyone to see. He’s on a platform. The overhead lights are dim while one bright spotlight is on the juggler as he starts to juggle?one, two, three, four, five, and six balls moving effortlessly through the air, all in balance. He’s good!
Imagine you’re a software developer working on a financial application. One day you’re assigned (or, if you’re agile, you pick yourself) to implement changes to the overtime computation logic so your company can sell the application in France. In France, the official work week has 35 hours (lucky them) instead of the 40 hours in the US. Being new to the team, you’re not sure where to begin, so you start searching the codebase for the keyword “overtime.”