Why programmers don’t write documentation
kislayverma.com
Why programmers don’t write documentation
1–10 of 153 posts
Re: Why programmers don’t write documentation
#2Documentation is a feature, the rest of my comment is anecdotal but in many shops, it’s tracked as part of the task of coding. I’ve started making separate JIRA tasks to explicitly create or update the documentation and have told my team to do the same. So far, the results are good.
Re: Why programmers don’t write documentation
#3Documentation can be implicitly managed thorough writing clear, slightly verbose code with good comments, as well as clearly described test cases. It can also live in the project management tools if used effectively. With a good software development process you can have a historical record of the background, requirements, discussions around that feature/component, and how it was developed
Re: Why programmers don’t write documentation
#4the real reason is that, no incentives.
your manager will never give you a raise because you wrote nice documentations, in fact, he/she might think you're wasting time for not doing bugfixes or features development.
as long as documentation of code becomes one factor to evaluate the developers, with rewards somehow, things will change immediately.
I never felt doc is a technical problem, it's purely management for this one, it has been neglected for too long.
Re: Why programmers don’t write documentation
#5Diataxis[1] (mentioned on here recently) and ADR[2] massively helped me to create clearer docs. The Diataxis framework really helps you create something that could bring a new developer on board quickly, and ADR helps ensure the thinking behind architecture decisions is easy to understand.
Re: Why programmers don’t write documentation
#6I’m in games so the visual element often forces this, but I’ve moved our team to making a lot of video content, both for PRs and for much of our “documentation”.
I’ve always preferred reading, and the trend to everything being on YouTube has driven me nuts, but I’m a convert to this method for a few reasons.
First, it’s fast. I can sit down and make a deep dive video in 30 minutes and not have to sit around writing and polishing documentation for hours. When the code inevitably changes, I can throw away the old video and spend another thirty minutes making a new one.
Second, I can demonstrate what the code does while offering instruction around it. If I likened it to anything, it’s like having a series of lectures to your code base rather than a textbook.
And lastly, it’s proven GREAT for on boarding a new engineer in the more complex aspects of the project. Because they can go and view thousands of PRs, 90% of which have video demonstrations or explanations, they can do a lot of self directed learning and not require nearly as much over the shoulder time with other engineers. When your team is spread across 12 hours of time zones, this is very useful.
This method isn’t a panacea, and we still keep written documentation when we need to provide a concise set of “how to’s” to other teams. But for the dev team, it’s been great.
Re: Why programmers don’t write documentation
#7I like tools like flake8-docstrings and setting the expectation that documentation should be reviewed during the code review process.
Re: Why programmers don’t write documentation
#8> Writing is a tough, demanding task. It requires organizing our thoughts clearly, examining them critically, and expressing them clearly. While the expressing part can be simplified to some extent (depending on the quality of writing required), all three steps are taxing when done properly.
Wow, almost sounds like some other aspect of a job a software engineer is required to do...
> If a developer doesn’t write documentation, their work still gets done.
If documentation is part of their job, it literally does not.
> Not writing doesn’t block shipping (at least not right away).
It should.
Re: Why programmers don’t write documentation
#9Everywhere I’ve been except for IBM in the 90s, documentation is not given priority (time) as would be needed to both write the first round adequately and then maintain it as realities change.
Tools are much less a problem.
I suspect also that modern “agile” approaches work against building and maintaining documentation because developers are hyper focused on ticket level changes in short sprints.
Same goes to a lesser degree in writing tests. And when it comes to tests, devoting an entire sprint to increasing coverage seems to compensate, so perhaps a documentation sprint every few months might work.
Actually, the agile sprint approach also works against clean code based and discourages refactoring. So refactor sprints need to happen periodically.
I think I see a pattern here: current agile methodologies trade one set of problems for a new set.
Re: Why programmers don’t write documentation
#10> Writing is a tough, demanding task. It requires organizing our thoughts clearly, examining them critically, and expressing them clearly. While the expressing part can be simplified to some extent (depending on the quality of writing required), all three steps are taxing when done properly. Wow, almost sounds like some other aspect of a job a software engineer is required to do... > If a developer doesn’t write docu…
the last is bs. if you dont ship you wont make money, the compaby dies. if you dont write docs, you might incur tech debt but the company keeps on living.
ofc if there is enough time and manpower: write docs, write unit tests, discuss architecture. no prob.
but for a lot of companies speed is king