I wholeheartedly disagree with this article and I’m an agile purist. From a developer perspective I’ve never had a single engineer say I don’t want documentation. Yes it takes time but when you work in a world where there are varying standards and ways of work documentation is the necessary historical document. How things are coded, why they are coded that way and any code comments are documentation that is necessary. If you are talking about project artifacts that’s not always necessary and I agree. But you can’t rely on people ever. Things most be scribed to know where you can go next. This is just basic to me when it comes to great product operations
I’m glad this article and my reply sparked such great conversation. I agree with your stated point about code documentation. I agree on that he availability of free and quality documentation. I think you’re right AI as an assistant could provide the context to a developer so they understand why something was coded the way it was. Especially with legacy systems.
I second Mark's post. Almost every company I've worked for has slacked on their documentation and this has had a negative impact on the company. What I've found happens is that most knowledge of the codebase becomes embedded in the people who wrote it. As soon as they leave, productivity drops as their replacements have to figure everything out (this is especially dangerous for startups, and a point that one of my former employers did not seem to appreciate).
I've found there to always be something idiosyncratic in the codebase that makes no sense when you first encounter it, or some subtle configuration requirement that you won't see until you know about it. Just reading the code isn't always enough, especially for untyped languages with easily abused metaprogramming capabilities, like Ruby (I believe Ruby 3 added type annotations but my point still stands for older versions).
> It creates an often redundant branch of information that we must manually keep up to date. Since software engineering is collaborative, you’d need everyone to remember to update the documentation. It’s already hard enough to get one person to remember, let alone an entire team.
I've been told this before about comments in code, and it still rings false to me. Yes, documentation can become stale and misleading, but even that has value in that it provides context for how things used to be. Maybe you're thinking that commit logs already serve that purpose because commits should be atomic and have explicit descriptions of changes... and maybe where you work the development team is disciplined enough to do that (but then surely they'd be disciplined enough to remember to update documentation as well?). I've never seen that happen in practice. Even if that info is in the commit logs, you still have to go hunting for it, which is more time and distraction from the task you're supposed to accomplish.
> All the information is already in the codebase.
Yes it is, and I have a few reasons why I don't think that's enough.
1. Code should have descriptive names and be found in logical places, but it doesn't always happen this way. Deadlines, incidents, company policies ("Our engineers aren't productive enough, they need to make more pull requests!") can lead to code that's badly written and unclear.
2. Code isn't English. Simple things are easy and quick to understand by looking at it. Complicated things take time and focus. A quick description of why a function was written in a certain way/why it's doing something that looks strange to the reader goes a long way towards quickly understanding what some code is meant to do. You can then move to the higher cognitive-effort tasks of reading the code or looking through the commit history in the hope that whoever wrote it left a useful note and didn't shove it into an unrelated PR, or is still with the company and remembers this change. Even a somewhat inaccurate confluence doc describing the systems involved is better than nothing at all.
3. As teams grow, so does the range of programming skill at the company. What's obvious about the (undocumented) code/systems as an experienced developer may not be so obvious to a recent grad. And in that case, the grad will have to either track down someone to ask (and possibly get routed through multiple people to find someone who knows), or risk misunderstanding it, writing something bug-ridden or confusing themselves, and getting it through code review (review should stop things like this from making it into the main branch, but things that shouldn't have been approved will still get through).
I don't typically post comments, but this is a topic I care a lot about. I think that lack of documentation has contributed to my experiences with burnout, and I don't think the productivity loss due to that (for others, as well as me) is something that's likely to show up in an ROI calculation.
Thanks for the thoughtful response. One thing I'll note is that "documentation" is a potentially overloaded word.
When I say "documentation" I mean writing about the code. There are many other forms of writing like project updates, notable launches, design decisions, and potential plans that are valuable to write down.
> What I've found happens is that most knowledge of the codebase becomes embedded in the people who wrote it. As soon as they leave, productivity drops as their replacements have to figure everything out (this is especially dangerous for startups, and a point that one of my former employers did not seem to appreciate).
I agree that can be an issue. Two points to this:
1. Documentation isn't the only way to share information. Ideally they have been socializing the knowledge needed for the team to move faster as they went
2. Documenting code is a small fraction of their context. Ideally they have left some written artifacts about their projects (designs, launches, updates, etc)
I don't think a potentially out-of-date wiki talking about their code will help that much aside from reading the code itself.
> I've been told this before about comments in code
Comments are easier to find and maintain since they are so close to the code they describe. Much better than writing some static wiki somewhere.
I agree with you about "documentation" being an overloaded word. I may have been thinking more about comments when I wrote my reply, though I think most of my thoughts still apply to wiki pages.
Regarding points 1. and 2., I think these depend a great deal on the company. It would be ideal if that knowledge gets spread around in ways other than documentation, but I've found that to be rare and/or ineffective (it's not that I think it can't be done, but my experiences have led me to think it doesn't work out very often).
With point 2 specifically, I've not found it especially useful to go through written artifacts like that. They might be useful as supplementary information, but there's the potential for there to be a lot of cruft and missing context from those (as well as the same risk of the information being outdated). Documentation has an intended purpose of educating someone, artifacts exist because they were necessary to accomplish some other task. On balance, I'd still expect intentional documentation to be more effective to learn from than unintentional documentation (i.e. written artifacts).
Part of the difficulty with discussing the usefulness of documentation is that it's going to depend a lot on our experiences. I agree with you that before writing a wiki page, we should be considering whether it's worth writing or not, but we'd likely draw the line between "worth" and "not worth" in different places depending on our mental models of how the particular workplace operates. The engineering culture, the experience level of the team, pressure from leadership, the state of the codebase, etc. These are all going to change what the team needs to know and the most effective way for them to learn it.
> I agree with you about "documentation" being an overloaded word.
I'm thinking of rewording some parts of the post to avoid confusion
> I agree with you that before writing a wiki page, we should be considering whether it's worth writing or not, but we'd likely draw the line between "worth" and "not worth" in different places depending on our mental models of how the particular workplace operates.
Agreed. As usual, it depends on the specific company and culture you're working in
Hi Ryan, I would be curious to know your thoughts on the data gathered in the 2024 DORA report which was able to strongly correlate many aspects of team and organizational performance to having strong documentation practices?
Your title is a bit misleading. I don't think you're making a case against documentation, instead it's mostly a case for doing the right kinds of documentation (and your ROI section captures some good thinking on how to assess if it's the right kind).
Although, you kind of lost me with "All the information is already in the codebase.". This is absolutely not correct. Most if not all of the documents with a ROI address things that you can't gain/understand easily from looking at the code. In my 30 years in this field, I have never seen an organization document pseudo-code and try to maintain that.
While it is true that documentation must be maintained and that does take effort to do, given that the value is clear I consider it a 'cost of doing business' in a professional software engineering environment. Just like unit testing, etc. They key is to invest in the right types of documentation and put it in the right place (e.g. readme documents in the source repo, system design artifacts in the company's wiki, etc.)
> Your title is a bit misleading. I don't think you're making a case against documentation, instead it's mostly a case for doing the right kinds of documentation (and your ROI section captures some good thinking on how to assess if it's the right kind).
I changed the title to "the case against documenting code" to be more specific. I think there is a lot of value to a culture of writing. I just think documenting code is often not worth the time (there are exceptions as noted in my article).
> They key is to invest in the right types of documentation and put it in the right place (e.g. readme documents in the source repo, system design artifacts in the company's wiki, etc.)
Yes I agree. The title of my article was too general, I've fixed it. Thanks for your thoughtful comment
Right-on! I completely agree that documenting code itself is low value and can be made un-necessary by good naming practices, being well-factored as well as using comments where something wouldn't be clear to someone other than the person who wrote it.
Our team doesn’t document code so much as decisions. We create architectural decision records. This way in two years we know exactly why we made some sort of obscure choice in how we built something. Sometimes this gets out of date.
We also document processes. Like certain manual releases or testing. And we update the document as part of the process.
This is definitely an interesting take on this subject. However, in my experience all the information is not always in the codebase. Please document guys, it helps.
It's better to have it and not need it than to need it and not have it.
Best is to have it and need it. That is the point of my article. Only write documentation that matters and consider the ROI.
> all the information is not always in the codebase
To be clear, I am in favor of writing as a form of communication. Writing about plans, designs, updates etc are often worth it. I just think writing documentation about the code itself (which is in the codebase by definition) can be a waste of time.
It is a bad idea if I must dig in the codebase to know anything about the project. I suggest you take a better look at this matter again after a good rest and you'll see that what you're suggesting will do more harm than good. Even for a student doing toy projects, how else will they become better at writing good docs if they don't practice doing so on their petty projects and how will hiring managers understand their projects without any docs when they are applying? I guess, they too need to go through the source too right?
> It is a bad idea if I must dig in the codebase to know anything about the project.
There are many forms of documentation. Documenting the code itself is a small subset of all written communication. Writing about the high level project, plans, updates, etc are worthwhile.
Documenting the code itself is sometimes worth it (depends on ROI is my point).
I can see the argument about the time cost, but decent documentation can stand the test of time. I can't speak from a coding perspective, but a navigational one.
Sure, GUI may change from year to year, but people should be using context clues when things aren't 1:1, and navigate their way around.
Your code may changes, but the basics - something I often write documentation for on my blog - change far less, and have value to beginners and people not immersed in the space.
Yep, this is one of the cases where the ROI is worth it. If the information doesn't change often we get more value out of our time spent writing it down
I completely agree with you. One of the drawbacks of documentation or code related document is its maintenance cost. We usually use pseudo-code to explain things in this case since diagram is not always the best to explain stuff.
I wholeheartedly disagree with this article and I’m an agile purist. From a developer perspective I’ve never had a single engineer say I don’t want documentation. Yes it takes time but when you work in a world where there are varying standards and ways of work documentation is the necessary historical document. How things are coded, why they are coded that way and any code comments are documentation that is necessary. If you are talking about project artifacts that’s not always necessary and I agree. But you can’t rely on people ever. Things most be scribed to know where you can go next. This is just basic to me when it comes to great product operations
> From a developer perspective I’ve never had a single engineer say I don’t want documentation
If documentation was free and high quality then sure. That isn't the case though. This take misses the point of the article
You may be in luck though, I imagine LLMs will drive the cost of producing quality documentation to near zero
I’m glad this article and my reply sparked such great conversation. I agree with your stated point about code documentation. I agree on that he availability of free and quality documentation. I think you’re right AI as an assistant could provide the context to a developer so they understand why something was coded the way it was. Especially with legacy systems.
I second Mark's post. Almost every company I've worked for has slacked on their documentation and this has had a negative impact on the company. What I've found happens is that most knowledge of the codebase becomes embedded in the people who wrote it. As soon as they leave, productivity drops as their replacements have to figure everything out (this is especially dangerous for startups, and a point that one of my former employers did not seem to appreciate).
I've found there to always be something idiosyncratic in the codebase that makes no sense when you first encounter it, or some subtle configuration requirement that you won't see until you know about it. Just reading the code isn't always enough, especially for untyped languages with easily abused metaprogramming capabilities, like Ruby (I believe Ruby 3 added type annotations but my point still stands for older versions).
> It creates an often redundant branch of information that we must manually keep up to date. Since software engineering is collaborative, you’d need everyone to remember to update the documentation. It’s already hard enough to get one person to remember, let alone an entire team.
I've been told this before about comments in code, and it still rings false to me. Yes, documentation can become stale and misleading, but even that has value in that it provides context for how things used to be. Maybe you're thinking that commit logs already serve that purpose because commits should be atomic and have explicit descriptions of changes... and maybe where you work the development team is disciplined enough to do that (but then surely they'd be disciplined enough to remember to update documentation as well?). I've never seen that happen in practice. Even if that info is in the commit logs, you still have to go hunting for it, which is more time and distraction from the task you're supposed to accomplish.
> All the information is already in the codebase.
Yes it is, and I have a few reasons why I don't think that's enough.
1. Code should have descriptive names and be found in logical places, but it doesn't always happen this way. Deadlines, incidents, company policies ("Our engineers aren't productive enough, they need to make more pull requests!") can lead to code that's badly written and unclear.
2. Code isn't English. Simple things are easy and quick to understand by looking at it. Complicated things take time and focus. A quick description of why a function was written in a certain way/why it's doing something that looks strange to the reader goes a long way towards quickly understanding what some code is meant to do. You can then move to the higher cognitive-effort tasks of reading the code or looking through the commit history in the hope that whoever wrote it left a useful note and didn't shove it into an unrelated PR, or is still with the company and remembers this change. Even a somewhat inaccurate confluence doc describing the systems involved is better than nothing at all.
3. As teams grow, so does the range of programming skill at the company. What's obvious about the (undocumented) code/systems as an experienced developer may not be so obvious to a recent grad. And in that case, the grad will have to either track down someone to ask (and possibly get routed through multiple people to find someone who knows), or risk misunderstanding it, writing something bug-ridden or confusing themselves, and getting it through code review (review should stop things like this from making it into the main branch, but things that shouldn't have been approved will still get through).
I don't typically post comments, but this is a topic I care a lot about. I think that lack of documentation has contributed to my experiences with burnout, and I don't think the productivity loss due to that (for others, as well as me) is something that's likely to show up in an ROI calculation.
Thanks for the thoughtful response. One thing I'll note is that "documentation" is a potentially overloaded word.
When I say "documentation" I mean writing about the code. There are many other forms of writing like project updates, notable launches, design decisions, and potential plans that are valuable to write down.
> What I've found happens is that most knowledge of the codebase becomes embedded in the people who wrote it. As soon as they leave, productivity drops as their replacements have to figure everything out (this is especially dangerous for startups, and a point that one of my former employers did not seem to appreciate).
I agree that can be an issue. Two points to this:
1. Documentation isn't the only way to share information. Ideally they have been socializing the knowledge needed for the team to move faster as they went
2. Documenting code is a small fraction of their context. Ideally they have left some written artifacts about their projects (designs, launches, updates, etc)
I don't think a potentially out-of-date wiki talking about their code will help that much aside from reading the code itself.
> I've been told this before about comments in code
Comments are easier to find and maintain since they are so close to the code they describe. Much better than writing some static wiki somewhere.
I agree with you about "documentation" being an overloaded word. I may have been thinking more about comments when I wrote my reply, though I think most of my thoughts still apply to wiki pages.
Regarding points 1. and 2., I think these depend a great deal on the company. It would be ideal if that knowledge gets spread around in ways other than documentation, but I've found that to be rare and/or ineffective (it's not that I think it can't be done, but my experiences have led me to think it doesn't work out very often).
With point 2 specifically, I've not found it especially useful to go through written artifacts like that. They might be useful as supplementary information, but there's the potential for there to be a lot of cruft and missing context from those (as well as the same risk of the information being outdated). Documentation has an intended purpose of educating someone, artifacts exist because they were necessary to accomplish some other task. On balance, I'd still expect intentional documentation to be more effective to learn from than unintentional documentation (i.e. written artifacts).
Part of the difficulty with discussing the usefulness of documentation is that it's going to depend a lot on our experiences. I agree with you that before writing a wiki page, we should be considering whether it's worth writing or not, but we'd likely draw the line between "worth" and "not worth" in different places depending on our mental models of how the particular workplace operates. The engineering culture, the experience level of the team, pressure from leadership, the state of the codebase, etc. These are all going to change what the team needs to know and the most effective way for them to learn it.
> I agree with you about "documentation" being an overloaded word.
I'm thinking of rewording some parts of the post to avoid confusion
> I agree with you that before writing a wiki page, we should be considering whether it's worth writing or not, but we'd likely draw the line between "worth" and "not worth" in different places depending on our mental models of how the particular workplace operates.
Agreed. As usual, it depends on the specific company and culture you're working in
I completely agree with you.
Hi Ryan, I would be curious to know your thoughts on the data gathered in the 2024 DORA report which was able to strongly correlate many aspects of team and organizational performance to having strong documentation practices?
Your title is a bit misleading. I don't think you're making a case against documentation, instead it's mostly a case for doing the right kinds of documentation (and your ROI section captures some good thinking on how to assess if it's the right kind).
Although, you kind of lost me with "All the information is already in the codebase.". This is absolutely not correct. Most if not all of the documents with a ROI address things that you can't gain/understand easily from looking at the code. In my 30 years in this field, I have never seen an organization document pseudo-code and try to maintain that.
While it is true that documentation must be maintained and that does take effort to do, given that the value is clear I consider it a 'cost of doing business' in a professional software engineering environment. Just like unit testing, etc. They key is to invest in the right types of documentation and put it in the right place (e.g. readme documents in the source repo, system design artifacts in the company's wiki, etc.)
> Your title is a bit misleading. I don't think you're making a case against documentation, instead it's mostly a case for doing the right kinds of documentation (and your ROI section captures some good thinking on how to assess if it's the right kind).
I changed the title to "the case against documenting code" to be more specific. I think there is a lot of value to a culture of writing. I just think documenting code is often not worth the time (there are exceptions as noted in my article).
> They key is to invest in the right types of documentation and put it in the right place (e.g. readme documents in the source repo, system design artifacts in the company's wiki, etc.)
Yes I agree. The title of my article was too general, I've fixed it. Thanks for your thoughtful comment
Right-on! I completely agree that documenting code itself is low value and can be made un-necessary by good naming practices, being well-factored as well as using comments where something wouldn't be clear to someone other than the person who wrote it.
Our team doesn’t document code so much as decisions. We create architectural decision records. This way in two years we know exactly why we made some sort of obscure choice in how we built something. Sometimes this gets out of date.
We also document processes. Like certain manual releases or testing. And we update the document as part of the process.
I am 100% in favor of that. Lots of value in writing down high-level decisions, plans and processes.
Documenting the specifics of code is the part where it is often not worth it (there are exceptions of course)
This is definitely an interesting take on this subject. However, in my experience all the information is not always in the codebase. Please document guys, it helps.
It's better to have it and not need it than to need it and not have it.
> It's better to have it and not need it
Best is to have it and need it. That is the point of my article. Only write documentation that matters and consider the ROI.
> all the information is not always in the codebase
To be clear, I am in favor of writing as a form of communication. Writing about plans, designs, updates etc are often worth it. I just think writing documentation about the code itself (which is in the codebase by definition) can be a waste of time.
It is a bad idea if I must dig in the codebase to know anything about the project. I suggest you take a better look at this matter again after a good rest and you'll see that what you're suggesting will do more harm than good. Even for a student doing toy projects, how else will they become better at writing good docs if they don't practice doing so on their petty projects and how will hiring managers understand their projects without any docs when they are applying? I guess, they too need to go through the source too right?
> It is a bad idea if I must dig in the codebase to know anything about the project.
There are many forms of documentation. Documenting the code itself is a small subset of all written communication. Writing about the high level project, plans, updates, etc are worthwhile.
Documenting the code itself is sometimes worth it (depends on ROI is my point).
I can see the argument about the time cost, but decent documentation can stand the test of time. I can't speak from a coding perspective, but a navigational one.
Sure, GUI may change from year to year, but people should be using context clues when things aren't 1:1, and navigate their way around.
Your code may changes, but the basics - something I often write documentation for on my blog - change far less, and have value to beginners and people not immersed in the space.
> decent documentation can stand the test of time
Yep, this is one of the cases where the ROI is worth it. If the information doesn't change often we get more value out of our time spent writing it down
also an interesting take about this i just found today https://youtu.be/Y6ZHV0RH0fQ?si=SJYczoc_bXn-ls5k
Not necessarily agreeing the idea but the meme is brilliant 😂
I completely agree with you. One of the drawbacks of documentation or code related document is its maintenance cost. We usually use pseudo-code to explain things in this case since diagram is not always the best to explain stuff.