Does documentation need incentive?
Posted by HademLeFashie@reddit | ExperiencedDevs | View on Reddit | 73 comments
My team's documentation (both internal and external) could use some serious improvement, and even my manager agrees.
But I noticed, even in myself, that documentation is sort of an afterthought, and it usually has to be explicitly instructed before someone gets to it. The only time it isn't is if someone has directly suffered due to its lack, but it shouldn't have to come to that first, right?
I don't think a cultural change would fix this, so I'm wondering if you know of any incentives or systems that would encourage people to document with forethought and without having to be directly told. Or is this just a fantasy?
nickchecking@reddit
Start making proper internal documentation a requirement to get PRs approved.
Create stories/tasks to complete and catch up on external documentation, then going forward, code enhancements must come with updates to existing documentation to be considered complete.
natziel@reddit
I've learned that the level of documentation tends to reflect the quality of code. Devs will procrastinate or sandbag writing documentation if anything is blocking them
Now, you can't really change your engineering culture immediately, but you can start enforcing things like making sure documentation is written before code
Life-Principle-3771@reddit
The incentive is that better documentation reduces the frequency of as well as the severity of getting paged. Over my years i have increasingly become a believer in the Amazon model of Devs owning everything as well as Devs being first in the line of fire when things go down.
Slow-Entertainment20@reddit
Yeah working at AMZN previously it was incredibly overwhelming being responsible for everything, but now that I’ve gone somewhere new, the amount of bottlenecks and time wasted because I don’t have access to everything is ridiculous. The red tape everywhere drives me insane.
bighappy1970@reddit
100% correct! However, I think documentation is rarely, if ever, the right solution to any problem a developer faces. DevOps, Telemetry, CI/CD, 12 factor, etc are universally more useful.
thekwoka@reddit
Yes, but I think docs for some kinds of things make sense.
Like a unified place to describe the goal of an implementation and any gotchas.
Since there can be lots of places in code bases where it's hard to tell if a piece of strange behavior is a bug, or intended for some unclear condition.
Like having a note next to some regex about what the regex should be doing (and hopefully people keep it updated), so that someone that needs to come touch it can know what the goal is, not just what the actual code is.
bighappy1970@reddit
A test is a far better place to “document intended behavior” than a comment, because I comment won’t tell you when it’s no longer true
thekwoka@reddit
A test documents input output relationships.
It doesn't test the actual business intent of the code.
bighappy1970@reddit
Go ahead, keep your comments, I don’t care, it’s not my career that will suffer as a result
thekwoka@reddit
????
What the fuck are you talking about?
In what world would comments that explain aspects of the code that can't be figured out from the code be something that hurts ones career?
Like??
wtf?
bighappy1970@reddit
Try using your brain, you might figure it out.
bighappy1970@reddit
Clearly you have only read about testing from people who don’t know how to do it
besseddrest@reddit
Nothing beats a solid On-Call Guide/Runbook
For everything else, I love me some tribal knowledge
bighappy1970@reddit
I wouldn't say I'm a fan of tribal knowledge - I see that has a huge problem also. Self-help/documenting systems are so easy to create I don't understand why it's not the standard.
For most apps/websites/etc, If a new dev starts, assuming all permissions are in place, they should be able to commit thier first change and have it running in production within the first two hours - and be completly confident the change is correct. Anything less is such a nightmare environment.
besseddrest@reddit
for clarity - there's always going to be some level of documentation in place, especially for the case you've mentioned for onboarding, dev env setup - no doubt this is essential
Setup, tooling, usage, FAQs, totally fine
In my case we had a widget that our team owned at the top level, and within that we had the type of tasks and UI experiences that changed often, short shelf life, and a codebase that was small that 6 engineers would touch the common files in parallel, several times in the sprint - We ran A/B tests, find out the winner, iterate and run the next test. Fast, rapid development. This day to day stuff, the intimate knowledge of the app and how things connect - this is the tribal knowledge that we just kinda gained after a few sprints. This was one of the more challenging positions I've had, but that made it fun, knowing that I"m capable of the level code I see, now I just gotta find out how to keep up with the veterans at the pace they develop at. There's no time to spend documenting, but there wasn't much of a need to.
So when we planned/pointed the tickets often had a lot of ambiguity, and that was fine because it forced me to kinda dig into the code and make my own decisions but also work with an understanding of how the rest of the team would approach similar problems. So it was pretty cohesive, efficient, and honestly felt like strong teamwork.
sorry if i misled this is obvious a development style that works well with tribal knowledge - but this is now what i look for when i'm on the job hunt
bighappy1970@reddit
Nothing more than the README.md on my teams - if the instructions are more than, clone the repo, run some install or setup command, and then run some start command - there is most certainly a problem. Setup never needs to be more than this - In fact, a couple years ago I was able to completely do away with environment setup by switch to Bazel.
Easily generated on the fly from source/config when/if needed
Perfect, I've never found a legitimate need for documentaton of the code under development - Shared libraries, Company wide UI, etc sure, whatever consumers of the project need - but the devs on the project should never need more than documentation generated on the fly.
I think we might have different definitions of tribal knowledge.
For me, tribal knowledge is defined as:
Meaning, there is no way to discover what to do, how to do something without someone with experiance on the team telling you or showing you how do it.
This is an uterly terrible environment to work in, IMO, and there is no excuse for such lazyness on a team of so-called "professionals"
I don't think that's exactly what you are describing, am I correct? From what I understand of what you described, its not quite fully self document/help environment but also not fully ad-hoc - rather somewhere in the middle - which is not unusual. However, I would not leave it like that - I would push to get everything about the processes, systems, and practices to be discoverable.
besseddrest@reddit
The nature of our work made way for being able to develop the next UI experience by looking at other implementations in the code.
But no, I wouldn't say that I needed someone to show me how everything works. There were a few things here or there that I would ask to show me before i got started. It was never "I dont' know what to do because there's no documentation."
Oh if anything, maybe this is a good example of "the code is self documenting". But yeah I think at most I had a 30 min session of "this is the general workflow"
bighappy1970@reddit
Yes, that sounds like self-documenting code
Life-Principle-3771@reddit
I guess that's what I meant by documentation. External documentation should be owned by the PM
DaRubyRacer@reddit
No, they shouldn't be first in the line of fire. Developers don't have the authority to plan or change scope. It should be the Team Lead who allowed the change to go through. Why else have a hierarchy?
tehfrod@reddit
I do not want to work where you work.
DaRubyRacer@reddit
Is it normal for a Developer to make up what they want, regardless of how the client presented it to the Team Lead?
bland3rs@reddit
People listen to your advice if they respect you, no? And they respect you because you give good advice.
So if a developer says something about the plan and scope and people listen, that sounds like the person has something smart to say.
Different roles exist because people like to do different things. Just because I have set up a k8s for a whole company doesn’t mean I want to, so I leave it to someone that actually likes that doing that work.
tehfrod@reddit
No. It's also not normal for a Developer to transform into a winged dolphin and fly to the moon.
You said "developers don't have the authority to plan or change scope". While even that isn't always true, that's very different from "developers making up what they want, regardless of how the client presented it to the team lead".
Not all developers work in whatever kind of environment you do. Not every company is a strict, "shut up and do what I say" hierarchy. I've worked in companies from 3-person startups to 100,000 person multinationals. They are all different, and you're making a lot of assumptions in your statements that don't apply to all of them.
For example, almost no startups work this way. It would be absolute suicide for a startup to try to function in a strict hierarchy way. For one thing, many of them don't have a specific "client" who would talk to a "team lead".
No-Garden-1106@reddit
Absolutely agree, and I'm doing my part to write the requisite Mermaid, sysem diagram, runbooks on my part, etc.
But my challenge is getting teammates on board. As an individual contributor, not a manager, I can set an example, but I don't have the authority to require others to adopt these tools. There really are just people who are brilliant coders but don't do this. I really don't want to stir the pot too much and honestly it is a waste of mental energy for me to start yapping on with other engineers to improve their documentation. So how?
bobs-yer-unkl@reddit
External documentation should not be owned by devs. Devs are way too expensive, and probably not as good as tech writers at preparing user-facing documentation.
Miserable_Double2432@reddit
Your manager doesn’t agree.
If they agreed then they would have already be talking about this problem, regularly, with the team. You, yourself, know that it’s not work that’s going to be valued at performance review time
jujuuzzz@reddit
Our team sells solutions to stakeholders. Solutions require design documents for detailed estimations of costs. While I really prefer the read the code approach, stakeholders often don’t share my point of view.
Competitive-Vast2510@reddit
It doesn't/shouldn't.
All we need to do is to stop making it an afterthought (myself included).
t0rt0ff@reddit
Despite all the fears around AI, this is actually the type of work AI may be very good at which no engineer likes to do...
FishWash@reddit
I’ve tried this but AI is terrible at maintaining this sort of thing
DeterminedQuokka@reddit
It’s possible I generated the api docs for an entire app using ChatGPT. I had to reprint it a bunch but it still saved me hours of work.
BidEvening2503@reddit
I think it’s not very different from writing good software. It’s only good if you know what you’re trying to communicate already.
t0rt0ff@reddit
It is all subjective, but in my experience AI makes a very good job summarizing. Of course, the more standard technologies and approaches you use, the better the summary/documentation will be. I find making AI to write good software (Cursor, Claude, and any other AI agent) to be much harder than generating docs for the existing code. It requires setting good product and technical requirements, deep understanding of the codebase sometimes, etc. Anecdotally, AI-generated documentation actually helps AI to write better software...
BidEvening2503@reddit
Sigh. This is going to be one of those problems that’s going to cause people to want to quit their jobs in 2-3 years. Mark my words. Good technical writing isn’t easily AI generated.
Potato-Engineer@reddit
Very true, but mediocre AI documentation that's been given a quick once-over for accuracy is still better than no documentation.
If it hasn't been given the once-over... then you're trusting to luck that the hallucinations aren't too bad.
t0rt0ff@reddit
Fair point. But I think in this case we are comparing bad or no documentation with AI-generated documentation. Not good technical write-up with AI documentation.
SolidRubrical@reddit
Generating documentation with AI is pointless, because the people after you who wants docs can just input the same (or even more recent code) and get AI generated docs from that (including future LLM model improvements)
BidEvening2503@reddit
No code is sometimes better than mountains of shitty code.
prescod@reddit
People are also starting to improve documentation with the explicit goal of making AI more effective.
t0rt0ff@reddit
And unsurprisingly a lot of times it is also done with the help of AI.
ninseicowboy@reddit
Great point — you put it really well. This is exactly the kind of behind-the-scenes work that’s critical but doesn’t get much love from engineers. AI really might be the perfect tool for it. Even just having a model generate a first pass or suggest docstrings from comments could make the whole process feel less daunting. It lowers the barrier just enough that people might finally start documenting things before someone gets burned.
petr31052018@reddit
It needs incentive and it is leadership's job to provide it.
thekwoka@reddit
I think incentive is mostly understood, but the bigger issue is time.
If you don't give devs the feeling they have time to touch the docs, it won't get done.
Now, part of that can be making it a requirement, which will necessitate making the time.
Middle_Ask_5716@reddit
I like writing stuff to myself so it becomes the documentation.
However I also see a lot of: Person X did this test fix in 2001 don’t remove.
0dev0100@reddit
The incentive should be it being a part of the job.
RefrigeratorNearby88@reddit
Reward the work you want done or you’ll end up with a culture where people feel unvalued or don’t do the glue work
knowitallz@reddit
Process. I work in govt.
We write functional specs and designs. They are reviewed by others. They are critiqued. We don't do development until the documentation is done. We update the documentation when we fix bugs. You need to make it part of the whole process.
When it comes to functionality we look at the functional spec to see what that module does. we look at it to reference the design details. We find the bug in the design / code / and update the documents to reflect the change. All changes are tagged with Jira tickets.
_mkd_@reddit
But muh aGiLe!!!
knowitallz@reddit
its not true but we make part of the mini project to complete the documentation
imagebiot@reddit
Having a job is a good reason to do your job
musty_mage@reddit
It really isn't. Unless you suck at your job
imagebiot@reddit
Ok. So… If you suck at your job then you should be doing your job?
Got it.
do a good job consistently no matter where you are and just go where you are compensated adequately with respect to your work.
Or listen to musty mange and just produce shit all the time I guessv
musty_mage@reddit
Yeah, no. If you are actually good at your job, you don't need to be afraid
imagebiot@reddit
Lol living in fear?
Bro, just write adequate fucking documentation. This was burned into our brains first year of university. And working with bad devs who don’t write any documentation really really brings it home.
Like you don’t know because ITS YOU lol
musty_mage@reddit
Your original argument was that you do your job because of the fear of not having a job if you don't. My argument is that that's a really shit way to live.
imagebiot@reddit
The point was it’s part of the job
tehfrod@reddit
On the contrary, only a cultural change will fix this.
HankScorpioMars@reddit
Documenting for a new team member to be able to pick the code up and work on it should be part of the acceptance criteria. Software that needs the person who wrote it to be around is not good code. Assuming that anyone using it should just read the code and understand it is overestimating your skill and wasting everyone else's time.
Bad docs are bad engineering, disrespectful to the rest of the team and will leave a poor image of your work when you are promoted to a more senior role and anyone after you can git-blame your past decisions without docs to justify them.
If people need incentives to be professional, they either need to be reminded what the actual job is (something that is frequently very badly communicated, so not all fault is on the people not documenting their code), or they need another job.
Helpjuice@reddit
If you want it done it needs to be apart of actual performance requirements of the job. Poor documentation = no raise, no bonus, no promotion. Set what is required to meet the expectation, fall below it you don't get the perks of meeting expectations. They create it, they document it, make this policy and move forward. Have the manager send it out to all the devs and let it take care of itself from there.
midasgoldentouch@reddit
Generally when writing tickets I include creating/updating documentation as part of the acceptance criteria. This can be tricky sometimes because, for me at least, it can be harder to conceptualize how the documentation will change over a project compared to the code. Overall, it does ensure that we jot down the most important bits while it’s still fresh in our minds.
Ciff_@reddit
To document is a cost. To maintain documentation keeping it up to date is a cost. You need to be able to weigh this cost against what you are loosing by not having propper docs. Make your case. When is the lack of documentation an issue? What are the real impacts of you lacking docs? What are the risks?
If you don't know what problems you are solving you will not make the right solution. The solution may be automated test cases documenting behaviour better. It may be automated sop procedures. It may be readmes in repos and comments in code. It may be confluence.
high_throughput@reddit
I'm guessing you give kudos for fixing bugs but not for writing documentation. Celebrate new features but not documentation overhauls. Have bug bashes but no doc fixits. Have unit test coverage goals but no doc review goals. Put features at P0 and docs at P3. Give people bonuses and promos for launching but not for documenting.
If true, your team would be fools for ever wasting their time writing documentation.
Abject_Parsley_4525@reddit
I just block the review if I feel the documentation is lacking in the exact same way I would block it if I feel the code is lacking. It's part of the job, far too many engineers think they are God's gift to code and those are especially the engineers that need to document stuff.
ninseicowboy@reddit
Everything needs incentive
Careful_Ad_9077@reddit
Agreed ; One team I worked for increased code review quality when time was allocated for it in the sprint.
ninseicowboy@reddit
Exactly. Incentives are directly correlated with quality of said thing. If documentation is not incentivized, no one has any reason to do it, since incentives are likely placed elsewhere (probably delivering cool new features).
bighappy1970@reddit
Documentation is a "lie waiting to happen". For the most part, documentation targeting developers is 100% waste. If the code needs documentation, you are better off refactoring to make the code self-documenting.
Minimal documentation, like Architectural Decision Records ADR's, are worth creating. Anyting else should be generated on-the-fly from the exiting code.
SSA22_HCM1@reddit
Why could it use serious improvement? That's your incentive. If you're spending hours dicking around because the documentation sucks, or if you're constantly breaking production because you have no defined specs, you should already be incentivized.
Documentation for documentation's sake is pointless. If your project is small enough and its codebase is neat and clear with well-defined tests, it may not even need extensive documentation.
But if team members (or you) simply don't have the discipline to maintain the documentation, make it part of code review and QA processes. And regularly allocate time to prune dead docs and flag outdated ones.
horizon_games@reddit
Documentation gets outdated fast which is what makes it annoying to keep up to date.
Now commenting code on the other hand - if your crew aren't writing comments about WHY a particular bug or strange decision was made from a business point of view - to give context to future generations (or even that dev in half a year) then that's a problem.
bluetrust@reddit
The only thing I've seen work is to create tickets to document specific things, and prioritize it like you would features or bugs in your ticket tracking system. If you just make it an assumed part of doing work, it'll get dropped anytime someone is in a rush, which effectively means it'll never get done.
BidEvening2503@reddit
Better documentation is written with empathy and a specific audience in mind. It's concise and each statement provides value. There's no incentive to do that except a desire to do the right thing.
-fallenCup-@reddit
Why not just do the right thing yourself?