Documentation. I know we all hate having to create it. I don’t like writing it and feel like I always leave something out. However, our assumptions of what other developers should think we are trying to accomplish by our masterpieces of software are usually filled with potholes (sometimes big ones). The truth of the matter is that no matter how stellar your code or software is – if you’re the only one who understands how it works, it doesn’t do any good.
These are not paintings or sculptures that would live the rest of their days in a museum, untouched by human hands and just collecting dust as they run. In reality, documentation will be added to and changed as the information they describe evolves.
In this blog, we discuss two suggested strategies for the creation of useful and concise software documentation.
Moving On To What Concerns Us…
When considering software development documentation specifically, it generally targets developers; usually regarding a framework, library, or interface of some sort. These need to be fairly specific and detail the information needed for use.
Two of the biggest questions you should ask yourself when setting out to write this kind of documentation are:
- What level of complexity should the documentation be taken to?
- What does the documentation really need to convey?
As such, I encourage you to consider the following recommendations the very next time you are tasked with documenting your software application. By keeping these things in mind, you will be better suited to help those who will read what you write.
- Ensure the level of complexity is tailored to the intended audience
- Ensure your documentation includes all key parts and pieces that encompass your software, while keeping an eye for brief, concise, and comprehensive information.
Levels (Complexity) of Documentation
Documentation ultimately targets a specific set of people with the intent in mind of describing the features and use of what it does. Let’s call this the “levels” of documentation.
Let’s take the example of a new hardware gadget. It does not matter what it is, but let’s say a smartphone. There is always some sort of documentation included when we open the box. The documentation tells us what features it has, each button’s function, how to set it, use it, etc. If the manufacturer didn’t include this with all new purchases, they would have too many phone calls and their product would be useless. This documentation is directed at the end-user. As such, the tone and level of information are constructed for their “use” level.
Conversely, the documentation used internally by the manufacturer will read differently. Say it is specifically targeting the engineers designing the product. The documentation will be at a more detailed level; it could detail the parts that went into making the gadget, how they interact, and why it was designed in a certain way. It could be extremely complex.
The “level” of a user will not be the same as the level of the developer and what they will use to put together the application in the first place.
In theory, this is fairly simple to understand. Yet the format of what is to be conveyed must be consistent and allow for changes as time progresses. Allowing other tools to convey information such as changes might not be the best approach because if a change control package is changed out, those tracking records might be lost. It might be wiser to document the change in the code itself.
Ensure It Has All of the Key Parts
To ensure the documentation is comprehensive, you may need to include a variety of information depending on what you’re describing. This can include a variety of things, perhaps tutorials, explanations, reference guides, FAQs, and more. The key is to keep it brief, yet comprehensive.
In practice, I have seen enterprise-level documentation fall short by not giving a simple “Hello World” approach as an example, and not taking it to the level required for actual understanding of how all of the pieces fit together. Each API in a library does not always work by itself. They may require initialization or some call to another API before it will function the way you would expect.
What might be the biggest let down of documentation is writing in free-standing or one-off applications that most of us write. These are the typical client programs produced by consulting or in-house developers. Documenting the interfaces to API’s within the code should contain at least the same level of detail as third-party software does. This will facilitate reuse and reduce the overall footprint of the code base, especially in large organizations even after the originator is gone.
Ultimately, if a user interface exists within this software, a document for the end-user on how to navigate through it and what error messages mean, etc would need to be provided.
Self-documenting tools are useful for getting a base of information but do not convey the meaning of the API to the degree that is desired in most cases. In other words, all they can usually provide is the parameter name and type and that is not sufficient. Generated code should not be documented unless it is a one-shot generation. This allows for persistent documentation in those cases, otherwise, document the source of the generation.
Too little, too much? In my opinion, there is never enough documentation, unless it rambles on and does not convey any useful information for the subject at hand. Wordy or poorly formatted documentation can be confusing for the “use” level involved, as well.
Too little, or no documentation, what can you say about it. Cuss, cuss, cuss…
As you complete the documentation for an application, remember the “use” level audience and anticipate the questions they would be asking. Keep the documentation concise, as short as possible. Being overly wordy can lead to confusion. But ensure it is complete.
Always ask yourself, “does this actually tell me what I need to know?”