>What you have instead is knowledge debt as engineers turn over ... This isn’t tech debt
You know, if there only were a way to pass knowledge from one person to another aside from directly talking to that person. Perhaps if we had means of preserving knowledge, and even making it a part of the job description... But alas.
Joking aside, not writing technical documentation and product design docs is very much technical debt.
A lot of information that is lost with turnover is information that could have been written down and passed on.
Documentation is not jut code comments. It is:
-A solid bug tracking system, with clean and reproducible bug descriptions
-A version control history, where every change has a why in addition to a brief how, and which links with the bug tracker
-Well-written tests, which not only verify how a system works, but showcase how to use the APIs.
-Documentation for tests explaining why this input was chosen, what kind of output is expected, and why it was written that way
-High level comments in code (especially libraries) explaining how the API should be used
-High level documentation explaining the structure of the code that is checked in, and lives with the code. The documentation can be in Markdown or a plaintext README, but should be there
-A "code map" telling you what the code in various directories does, and where to look for things.
-And, most importantly, a lot of design docs - for every feature and algorithm. "We are solving this problem. Here are the alternatives considered. Here is what we are going to do and why. Here is how we'll implement this. We used ideas from this, this, and this paper".
Yes, all of that is needed. The price you pay is engineering time. But if you take on the debt, your new engineers will have Hours Of Fun[1] trying to figure out, say, whether the imaginary nanometers[2] model parameter increasing as a result of their change is a good or a bad thing.
What I am saying is documentation debt is technical debt. Documentation is just as important as the code. And having it does help[3].
You might think that your code doesn't need all of that. And that's fine; but that means you plan on never paying that debt. Maybe you plan for your startup to fail/sell out in a few years. Maybe you plan to leave that job. But anything long term means you have to write things down.
And if you haven't been doing so - now is as good time as ever to start.
[2]True story. There was a good reason for why the distance parameter had complex-valued nanometers as units; it was an elegant way to do improve a model while staying backwards-compatible. It was written down nowhere, and have fun googling "complex nanometers". They only exist in that code, AFAIK.
There is information which is readily transmitted through non-experiential means: tacit knowledge. Books, lectures, conversations.
There is information that must be experienced, drilled, and committed to habit and muscle memory: tacit knowledge. Drill, practice, experiment, coaching. Often 1:1 or at least 1:few.
It's highly arguable that individual knowledge does not become cultural knowledge until a means of transmitting it from one generation to the next becomes both established on institutionalised. It need not be a large institution, but it must have persistence.
Within any knowledge domain, the explicit knowledge transmits more readily than the tacit. With time and complexity, I suspect a situation much analogous to Amdahl's law is reached, in which generational knowledge transfer comes to be dominated by the tacit component -- it is harder, slower, and more expensive to transmit, and tends to irreducibility.
Technical cultures which become or incorporate a tradition of shared stories and lore, as Unix and Linux have done, seem to achieve this better than others.
And that neglects issues of semantic and cultural drift which affect written texts.
Though I'd come to this conclusion some years ago, I'm finding reading Mortimer J. Adler's How to Read a Book that this is a significant theme of that work.
You know, if there only were a way to pass knowledge from one person to another aside from directly talking to that person. Perhaps if we had means of preserving knowledge, and even making it a part of the job description... But alas.
Joking aside, not writing technical documentation and product design docs is very much technical debt.
A lot of information that is lost with turnover is information that could have been written down and passed on.
Documentation is not jut code comments. It is:
-A solid bug tracking system, with clean and reproducible bug descriptions
-A version control history, where every change has a why in addition to a brief how, and which links with the bug tracker
-Well-written tests, which not only verify how a system works, but showcase how to use the APIs.
-Documentation for tests explaining why this input was chosen, what kind of output is expected, and why it was written that way
-High level comments in code (especially libraries) explaining how the API should be used
-High level documentation explaining the structure of the code that is checked in, and lives with the code. The documentation can be in Markdown or a plaintext README, but should be there
-A "code map" telling you what the code in various directories does, and where to look for things.
-And, most importantly, a lot of design docs - for every feature and algorithm. "We are solving this problem. Here are the alternatives considered. Here is what we are going to do and why. Here is how we'll implement this. We used ideas from this, this, and this paper".
Yes, all of that is needed. The price you pay is engineering time. But if you take on the debt, your new engineers will have Hours Of Fun[1] trying to figure out, say, whether the imaginary nanometers[2] model parameter increasing as a result of their change is a good or a bad thing.
What I am saying is documentation debt is technical debt. Documentation is just as important as the code. And having it does help[3].
You might think that your code doesn't need all of that. And that's fine; but that means you plan on never paying that debt. Maybe you plan for your startup to fail/sell out in a few years. Maybe you plan to leave that job. But anything long term means you have to write things down.
And if you haven't been doing so - now is as good time as ever to start.
[1]http://wiki.c2.com/?HoursOfFun
[2]True story. There was a good reason for why the distance parameter had complex-valued nanometers as units; it was an elegant way to do improve a model while staying backwards-compatible. It was written down nowhere, and have fun googling "complex nanometers". They only exist in that code, AFAIK.