In all my 26 years of working as a software dev, in the ~20 companies that I've worked or consulted for in various countries, never once did I see code documentation work out well.
It wasn't that the will was not there: in almost every single of the companies the devs and management agreed that good documentation was important. And every now and then some heroic effort would be made to finally clean up Confluence or whatever system was used at the time. And for a little while that would work, then slowly documentation would become neglected here and there, and in the end it would become so bad that nobody would use it anymore. Except perhaps to showcase your commitment to best dev practices to your manager when it was time for your performance review.
It doesn't matter if documentation has to be added in the code, or to some external system or both. Sooner or later it will be neglected, become out of sync and eventually become worse than no documentation at all.
With the exception of external libraries or API's, software simply changes too fast. You'd need an army of technical writers to keep all documentation in sync.
And unlike what the author writes, I have actually been working for a couple of companies that gave up and simply used the code as documentation, and surprisingly this worked out pretty well.
Sad to read your n=20 was like that. There are also cases where documentation led companies to growth—one example is Stripe.
Poking the finger at documentation is easy because it's visible and readily available. Would you say the bit rot phenomenon you described never happened to code, or processes, or UIs? Docs reflect organizations.
> There are also cases where documentation led companies to growth—one example is Stripe.
when you said 'there are also' i thought you were talking about the same thing as the comment you were responding to. Not sure how existence of something totally unrelated to original comment is relevant.
It wasn't that the will was not there: in almost every single of the companies the devs and management agreed that good documentation was important. And every now and then some heroic effort would be made to finally clean up Confluence or whatever system was used at the time. And for a little while that would work, then slowly documentation would become neglected here and there, and in the end it would become so bad that nobody would use it anymore. Except perhaps to showcase your commitment to best dev practices to your manager when it was time for your performance review.
It doesn't matter if documentation has to be added in the code, or to some external system or both. Sooner or later it will be neglected, become out of sync and eventually become worse than no documentation at all.
With the exception of external libraries or API's, software simply changes too fast. You'd need an army of technical writers to keep all documentation in sync. And unlike what the author writes, I have actually been working for a couple of companies that gave up and simply used the code as documentation, and surprisingly this worked out pretty well.