TheNewStack (https://thenewstack.io/no-testing-no-documentation-no-problem/) has an interesting article on the #nodoc concept. We all certainly encounter code that has no documentation, no comments, and no tests, but normally assume that’s extreme hurry or negligence. Instead, this concept is to create code simple enough that it has no significant bugs, or need for documentation because
“They believe that testing and documentation costs too much money and time, which of course costs more money.”
We can certainly sympathize with the traditional rigors and annoyance of creating documentation. It adds to what we call “engineering bureaucracy,” adding overhead to all operations, and seems destined to be out of date. This struggle remains true whether documenting through comments, annotations, long form, or whiteboarding. No matter how accurate the documentation starts (a hopeful condition), it soon isn’t. And, developers and users know the documentation probably isn’t quite up to par. Perhaps that suspicion contributes to the widespread reluctance to RTFM. In other words, people like reading docs more or less as much as developers liked creating them in the first place.
What if we flip that on its head and make the documentation costless, or nearly so, and accurate up to the last check-in? Integral from Massiv.io can reprocess code in moments and display what’s actually in modules, dependencies, APIs, conections among services, etc. This is useful for seeing what’s in your team’s code, and even more so when joining a code base new to you. See how everything is set up, and zoom directly to the code underlying any feature. Integral makes “Code the Source of Truth,” not some arms-length frozen documentation.
Almost explaining Integral for us,
“Marshall did say that there can be copious code examples, just no documentation.”
Want to find an example of an API use, in a particular language, using a particular framework. Just ask Integral, and zoom right to it, know who developed it, and be productive in minutes, directly from code.
Certainly, the #nodocs concept goes beyond just not writing docs. Proponents suggest that by only relying on docs, implementers avoid actually deep understanding of the user need, and the product will therefore inevitably miss the mark. If developers can’t produce a simple product immediately understandable without docs, then the problem and solution are not understood. The jury is out on this purity, but we’ll certainly keep tabs on it. However it goes, certainly thought provoking. Thanks!