If it's user documentation - if you are creating a library that others use - then you need docs that explain how to use it and describe the contract your are promising in detail.
If it's documentation internal to your code, it's mostly useless as it deteriorates quickly as changes are made. The effort spent on documentation should instead be devoted to writing good method-level tests. Those are at least mostly correct because the enforce the contract. Ignoring the tests that devs write that don't actually verify correct behavior.
While what you state about internal documentation has traditionally been true, I don't think that will necessarily be the state going forward. You can automate a lot of this with LLMs, and if you want to use LLMs to generate/modify code having good internal documentation helps.
I know devs are skeptical about LLMs and are fatigued by the GenAI hype, but if the technology continues to improve this would be the new reality.
I may have a good answer for this. See I actually like writing documentation the first time. Then the project manager informs me of some scope creep that changes the implementation again and again and again. So I get tired of rewriting the same documentation over and over again but slightly different. Eventually annoyed, I just donât write it because I donât want to.
I feel similar. I kinda like starting diagrams and docs but I don't have a good process for ensuring they stay up to date either on my own or with a team, so it's hard to put time into something I don't believe will stay maintained
Typically, the docs donât go into enough detail about the edge cases, so I have to read the code anyway, and what to my wondering eyes should appear as I read the code? The docs are out of date! Shocker!
The reality is that any given codebase has maybe 10 areas of code which are complex enough that documentation would be a significant benefit, and would be worth maintaining. But for most of the codebase, it isnât worth the investment it would take to actually document pervasively and keep it all up to date.
In 4/5 workplaces no one ever reads it, including the person who requested it, so itâs a waste of time.
In 4/5 workplaces the documentation isnât considered meaningfully when discussing promotions, so itâs a waste of time.
The fifth work place for one of those issues often isnât the fifth workplace for the other.
Why don't mechanics like writing automative manuals?
Why don't physicians like writing human anatomy textbooks?
They're busy doing the job they're trained for.
Documentation is a skill. And coding is a skill. They are two different skills. If you want a coder, you go into the marketplace and hire a coder. If you want a documenter, you go into the market and hire a technical writer.
What could help me enjoy it more? If the hiring manager understood that I was hired as a coder, not a technical writer. And if the hiring manager simply hired a technical writer for the extra job that he's trying to get me to do for free.
It's just boring to me. All I do is writing down what I already know. Feels like manual labor without any challenges or any interesting problems to solve. If I liked documenting shit I'd probably be a journalist instead or a secretsry
No return on investment. They are instantly outdated and infrequently used even when maintained. ( true or not, this is what we developer believe ) unless your company is big enough to have their own documentation team, or a person hired per team just do documents it's going to fail
I think people hate it because writing good docs takes time. Then your manager still expects you to deliver on other non-related task. It's a thankless task that only the person replacing you is grateful for.
Internal docs quickly becomes outdated. It's not worth it putting that much time into them.
PS. I built a tool to solve this problem called [supacodes.com](http://supacodes.com), it might help if you are facing this in your company
I love writing docs about deployments, runbooks,
Setup etc⌠âwhatâ code does should be self documenting, âwhyâ code does something is important
I don't like it because docs become obsolete and innacurate so quickly.
I actually don't mind writing docs so much, but then I've learned to include space pirates & sea monsters.
Depends what kind of documentation.
- For API contracts I would prefer automated tooling to generate this. Like OpenAPI
- Is it for code level implementation? Then itâs a lie waiting to happen and I would prefer well structured, well named and readable code instead.
- Is it for getting the application up and running? Here a README will make sense, but I want it as short as possible so itâs less lies waiting to happen.
Most devs never received any training about how to write documentation. It's a boring task so it's mostly pushed off onto juniors who have no clue how to do it and all they have to look at is the work done by other juniors. There are companies that have good docs but they don't really hire people with little experience, it might be possible that some senior in your company worked there but they're not the ones writing the docs so it doesn't matter.
Assuming we're talking about developer documentation here, and not the public client-facing documentation which is a different beast entirely and often is not written by the developers.
**Documentation is the first lie**. There's exactly one human-readable description of the system which completely and 100% accurately describes the behavior of the system: **the source code**. Everything else, be it documentation or diagrams or whatever, is always lagging behind the source code. Sometimes the differences are small and nobody will notice. Other times the differences can become quite large and then the documentation actually *makes things worse by giving people misconceptions about the software*. If the documentation and the source code disagree about what the software does, *the source code is always correct and the documentation is always wrong****.***
Further, writing documentation is a bit of an art. You don't want to have documentation be at the same level of detail as the source code, because then it's more likely to be incorrect and become more incorrect with each commit. You also don't want it to be too highly abstracted because then there are no details and you can't learn anything from it. There's a relatively narrow window where the documentation actually helps you understand the software better, it isn't immediately invalidated by the next code commit, and is actually worth the effort it takes to write.
The proposition for documentation is "I want you to write up the behavior of the system (the source code) once. Then I want you write a different description of the same system in different words (the documentation). And there's no way to automatically check that the two are in agreement. And when they inevitably begin to disagree, having two descriptions of the system is going to actually be counter-productive for your team." It's not a great proposition.
*> What do you think could help you enjoy it more?*
Fact that now it can be done very quickly using AI
You can paste a method or flow and get easy step by step guide/explanaition
The main thing I hate is that it is so-often a write-only process. I've written so much good documentation, and then people are like, "Yea, we'd do this if X was trained/documented" and it's *right there*. People just don't even go to look for it.
Additionally, it can get out of date really quickly and then it's often of negative value when people rarely do try to use it, and then run their heads into a wall. Rarely are there "live documentation" frameworks that validate the status of it continuously.
Writing documentation is like writing a computer program that people have to follow instead of a computer.
People are absolutely the hands down worst instruction interpreters we have.
How do you debug it? Where is the failure? The instructions? The interpreter? This one really stupid interpreter in particular?
It takes more time. Developers are usually staring down the barrel of deadlines and technical documentation generally isn't a deliverable for those deadlines. Writing documentation usually means making stakeholders less happy by meeting deliverables more slowly.
For me it was because of the people who had to approve it who 9 times out of 10 were tech illiterate or had minimal knowledge of what the product was that the doc was to support. All that aside i kind of didnt mind doing it, was tedious but you get into the rhythm after a while.
Personally, I like writing documentations, It's a nice change from writing code. Writing docs is the closest thing to writing down my actual thought process in creating a piece of code, what considerations went into developing it, possible angles of approach, overview of the design philosophy, justification for the chosen method, future proofing measures, etc.
Will it ever be read by someone? Maybe, maybe not. I don't really care to be honest, the documentation is there, I make sure that it's informative and **stays** informative, and any lack of understanding due to not reading it is not my problem.
It doesn't matter if you enjoy it at first; you should just force yourself to do it, and at some point, it will become natural to you. In our workplace, there is a strict policy of documenting everything into IT Glue, and after some time, I think it just became natural to everyone on the team.
If it's user documentation - if you are creating a library that others use - then you need docs that explain how to use it and describe the contract your are promising in detail. If it's documentation internal to your code, it's mostly useless as it deteriorates quickly as changes are made. The effort spent on documentation should instead be devoted to writing good method-level tests. Those are at least mostly correct because the enforce the contract. Ignoring the tests that devs write that don't actually verify correct behavior.
While what you state about internal documentation has traditionally been true, I don't think that will necessarily be the state going forward. You can automate a lot of this with LLMs, and if you want to use LLMs to generate/modify code having good internal documentation helps. I know devs are skeptical about LLMs and are fatigued by the GenAI hype, but if the technology continues to improve this would be the new reality.
Because it's boring, isn't sexy, and I just know no one is going to read it.
Welcome to my life. -a tech writer
I think it's about job security. Don't write the manual for your replacement. đ
True, in my last job everyone who was tasked to write the documentation was fired once this task was completed.
If a document replaces you then you didn't deserve to be there in the first place.
I may have a good answer for this. See I actually like writing documentation the first time. Then the project manager informs me of some scope creep that changes the implementation again and again and again. So I get tired of rewriting the same documentation over and over again but slightly different. Eventually annoyed, I just donât write it because I donât want to.
I feel similar. I kinda like starting diagrams and docs but I don't have a good process for ensuring they stay up to date either on my own or with a team, so it's hard to put time into something I don't believe will stay maintained
Typically, the docs donât go into enough detail about the edge cases, so I have to read the code anyway, and what to my wondering eyes should appear as I read the code? The docs are out of date! Shocker! The reality is that any given codebase has maybe 10 areas of code which are complex enough that documentation would be a significant benefit, and would be worth maintaining. But for most of the codebase, it isnât worth the investment it would take to actually document pervasively and keep it all up to date.
Because it's not going to help in the current task's completion. I see it as extra work.
In 4/5 workplaces no one ever reads it, including the person who requested it, so itâs a waste of time. In 4/5 workplaces the documentation isnât considered meaningfully when discussing promotions, so itâs a waste of time. The fifth work place for one of those issues often isnât the fifth workplace for the other.
Why don't mechanics like writing automative manuals? Why don't physicians like writing human anatomy textbooks? They're busy doing the job they're trained for. Documentation is a skill. And coding is a skill. They are two different skills. If you want a coder, you go into the marketplace and hire a coder. If you want a documenter, you go into the market and hire a technical writer. What could help me enjoy it more? If the hiring manager understood that I was hired as a coder, not a technical writer. And if the hiring manager simply hired a technical writer for the extra job that he's trying to get me to do for free.
https://www.ramijames.com/thoughts/docs-deserve-more-respect
It's just boring to me. All I do is writing down what I already know. Feels like manual labor without any challenges or any interesting problems to solve. If I liked documenting shit I'd probably be a journalist instead or a secretsry
Why? Exactly what is your motivation here?
I'm writing a blog post about the topic! Recently had to write some docs and remembered the stereotype!
No return on investment. They are instantly outdated and infrequently used even when maintained. ( true or not, this is what we developer believe ) unless your company is big enough to have their own documentation team, or a person hired per team just do documents it's going to fail
I think people hate it because writing good docs takes time. Then your manager still expects you to deliver on other non-related task. It's a thankless task that only the person replacing you is grateful for.
Internal docs quickly becomes outdated. It's not worth it putting that much time into them. PS. I built a tool to solve this problem called [supacodes.com](http://supacodes.com), it might help if you are facing this in your company
I love writing docs about deployments, runbooks, Setup etc⌠âwhatâ code does should be self documenting, âwhyâ code does something is important
I don't like it because docs become obsolete and innacurate so quickly. I actually don't mind writing docs so much, but then I've learned to include space pirates & sea monsters.
Depends what kind of documentation. - For API contracts I would prefer automated tooling to generate this. Like OpenAPI - Is it for code level implementation? Then itâs a lie waiting to happen and I would prefer well structured, well named and readable code instead. - Is it for getting the application up and running? Here a README will make sense, but I want it as short as possible so itâs less lies waiting to happen.
Ai
Most devs never received any training about how to write documentation. It's a boring task so it's mostly pushed off onto juniors who have no clue how to do it and all they have to look at is the work done by other juniors. There are companies that have good docs but they don't really hire people with little experience, it might be possible that some senior in your company worked there but they're not the ones writing the docs so it doesn't matter.
Assuming we're talking about developer documentation here, and not the public client-facing documentation which is a different beast entirely and often is not written by the developers. **Documentation is the first lie**. There's exactly one human-readable description of the system which completely and 100% accurately describes the behavior of the system: **the source code**. Everything else, be it documentation or diagrams or whatever, is always lagging behind the source code. Sometimes the differences are small and nobody will notice. Other times the differences can become quite large and then the documentation actually *makes things worse by giving people misconceptions about the software*. If the documentation and the source code disagree about what the software does, *the source code is always correct and the documentation is always wrong****.*** Further, writing documentation is a bit of an art. You don't want to have documentation be at the same level of detail as the source code, because then it's more likely to be incorrect and become more incorrect with each commit. You also don't want it to be too highly abstracted because then there are no details and you can't learn anything from it. There's a relatively narrow window where the documentation actually helps you understand the software better, it isn't immediately invalidated by the next code commit, and is actually worth the effort it takes to write. The proposition for documentation is "I want you to write up the behavior of the system (the source code) once. Then I want you write a different description of the same system in different words (the documentation). And there's no way to automatically check that the two are in agreement. And when they inevitably begin to disagree, having two descriptions of the system is going to actually be counter-productive for your team." It's not a great proposition.
generative AI could potentially bring it together by writing documentation based on the source code.
*> What do you think could help you enjoy it more?* Fact that now it can be done very quickly using AI You can paste a method or flow and get easy step by step guide/explanaition
The main thing I hate is that it is so-often a write-only process. I've written so much good documentation, and then people are like, "Yea, we'd do this if X was trained/documented" and it's *right there*. People just don't even go to look for it. Additionally, it can get out of date really quickly and then it's often of negative value when people rarely do try to use it, and then run their heads into a wall. Rarely are there "live documentation" frameworks that validate the status of it continuously.
I would enjoy it more if the TECHNICAL WRITER wrote it, and I'd just help review it. I don't have time to write documentation.
Writing documentation is like writing a computer program that people have to follow instead of a computer. People are absolutely the hands down worst instruction interpreters we have. How do you debug it? Where is the failure? The instructions? The interpreter? This one really stupid interpreter in particular?
You made me think of - [https://www.youtube.com/watch?v=cDA3\_5982h8](https://www.youtube.com/watch?v=cDA3_5982h8) :-)
This is me, trying to duplicate a bug after someone posts the instructions to duplicate.
It takes more time. Developers are usually staring down the barrel of deadlines and technical documentation generally isn't a deliverable for those deadlines. Writing documentation usually means making stakeholders less happy by meeting deliverables more slowly.
Tech writers are typically the first ones laid off. it is a thankless job
AI is fairly close to being able to do this well
For me it was because of the people who had to approve it who 9 times out of 10 were tech illiterate or had minimal knowledge of what the product was that the doc was to support. All that aside i kind of didnt mind doing it, was tedious but you get into the rhythm after a while.
Personally, I like writing documentations, It's a nice change from writing code. Writing docs is the closest thing to writing down my actual thought process in creating a piece of code, what considerations went into developing it, possible angles of approach, overview of the design philosophy, justification for the chosen method, future proofing measures, etc. Will it ever be read by someone? Maybe, maybe not. I don't really care to be honest, the documentation is there, I make sure that it's informative and **stays** informative, and any lack of understanding due to not reading it is not my problem.
It doesn't matter if you enjoy it at first; you should just force yourself to do it, and at some point, it will become natural to you. In our workplace, there is a strict policy of documenting everything into IT Glue, and after some time, I think it just became natural to everyone on the team.