The Problem
Software Teams Can Not Document Their Software!!
Ever since Software has existed, there has been not been a way to document it in a way that can be shared within the Software Team. There still is no way for someone on the Software Team to choose some part of their system and simply go to some online source to find (or add) the documentation that should be captured about it. That's because the nature of Software makes it very difficult to create a structure to do so. That's not to say it can't be documented; only that a solution has not yet been found. Those who work in Software will understand why.
Why is Software so Difficult to Document?
For one, there are subjective, moving boundaries and different logical groupings as to what you are documenting. It could be a set of controls in a UI, a commonly used function and the objects that use it in the app code, or a database job and the files and tables it uses and interacts with. The question as to what level to document at is just the start of your problems. For example, if you were using a Word document, what would you title it, what would it include and what would it exclude. Should security be included, or should that be separate? How would someone else know where documentation for one area ends, and another begins?
There is also a heterogenous mix of systems and technologies that work together, but have their own types and organizational structure of objects. Should those be documented together, or kept separate?
And duplication of documentation becomes a major problem, when some objects are used in different logical groupings, which means you have to duplicate their documentation for every "module" that uses that object. You may have an object used 10 times, so every time you want to update the documentation, you have to find those 10 places and update them.
And finally, there is no "structure" to organize all of these objects and artifacts, so you have to figure that out from scratch. And you need some tool to create that structure (people have tried Wikis) but it does not match the structure of Software, and quickly becomes useless and your documentation efforts become more of a liability than an asset. The less people use it, the more likely the documentation is believed to be stale, and it gets used even less until it is not used at all.
There are other obstacles, but those are some of the most commonly found issues that inevitably prevent a workable solution.
Why Does Software Need to be Documented?
Because Software Teams have gotten by for so long without Software being documented, many just accept that it is not needed. We have found ways to work as efficiently as possible without it.
To this I ask, what if most of your questions you had about your Software, you could quickly find online?
What if you could also visually explore a model of the area of your Software you were working on, and drill into its different parts to find more information about it? The rules and requirements it implements, the design rationale, how to test it, how to handle errors or failures, where it logs to, what security and permissions it requires, when was it last modified, who is the SME, what improvements should be added next time around, etc.
How would your day be different? I'm betting you would have less stress, less interruptions, less meetings, higher confidence because you had more information to make decisions, and more pride because you were producing higher quality work and producing it faster. Those experts, who are the information bottlenecks in the organization today because they know the most about the system, could get back to being experts at completing tasks that help make the Software better. New employees, consultants, and remote Teams would also benefit from not having to rely on other employees to spend valuable time holding their hand and walking them through how the system currently works.
There are thousands of individual artifacts in your Software System, each with multiple important things to know about it. All of this information was thought about or discussed at some point in time, but it was never captured to be looked at later. Everyone one of these represent a cost that will be paid at some future date; the time spent to search out and try to find that information, and additional cost when the information can not be found, and wrong assumptions are made that create multiple rounds of development and testing. There are other costs as well, because people are constrained to only work on the parts of the system they are familiar with, so some software fixes or features must wait until resources are freed up.
Summary
Many who have worked in Software for a long time are well aware of the fact that the information they use today, will become a question some time in the future. They still to this day, say that we need to capture what we discussed so we can refer to it at a later time to remember what decisions we made. However, they know it is not really an option. There is no tool available that will work, and that the documentation will end up in a location that is mostly disconnected from other documentation that is also relevant to it, and needs to be considered as a whole. And it will end up being faster just trying to have the person who worked on it last try to recall it from memory as best as they can, and people will have to make decisions based on limited information, with limited time, and do the best they can with what they have.
All rights reserved. Your business name.
© 2019