Question: What does software project documentation commonly lack?
Answer (from Robert Ogilvie):
Technical documents like this are commonly flawed in 2 areas:
- They simply do not exist
- While they may have the knowledge right, they’re not designed/formatted for readability and usability.
So, what does good documentation do well?
- It clarifies the requirements (the functions and features) of why the software exists
- It summarizes the architecture. Whether procedural, object oriented, or some other type of design, it gives a sense of how this software was built and the “structure” of it- which helps in aligning future use and evolution to this existing structure.
- It lays out the different variables and objects/modules which use them. Good commenting is really key here.
- It’s readable, visual, and clear. You don’t need to be a Senior Software Engineer to understand it. To this end, the more pictures and diagrams, the better. Use quick UML or Flow Diagram mockups to show relationships, and I’d suggested lots of screencap pictures and highlighting to show specific areas of code as needed. This is so critical for open source or outer shared software; the easier you can make you software to use, the lower the barriers to entry and higher the market uptake and retention (more of a business strategy issue).
For long-term use, consider it both a Living Document (it’s grows and gets better over time and with ongoing usage). Also, I’d suggest making it entirely a Digital Document, whether that means stored in the cloud (Dropbox, Google Drive, etc) or a Wiki online, which is great for other document hyperlinks, online references, and shared collaboration. You’re now starting to get into LMS territory, but that’s kind of the aim: how do you make software documentation an effective learning tool for your teams and users?