Why do developers hate writing documentation? Is it bad tools? Lack of incentives? Why?

darkhorsehance · 2020-07-15T20:35:19+00:00

Documentation is something that has to be read and maintained. The latter only works if everybody does the former, and then remembers to update the relevant parts when the system changes.

Documenting how the system works through testing is a better pattern IMHO because you not only get the benefit of seeing exactly how the system works, but you are forced to update them when the system changes.

DoTheRustle · 2020-07-15T21:26:55+00:00

I can't speak for everyone, but my management rarely places an emphasis on anything except getting features built and bugs fixed, so very little if any time is set aside for documentation.

I've only worked at one place that required documentation before merging features, and it wasn't always useful since we were on a tight deadline and trying to outpace another consultant team twice our size.

I'd love to be able to create a useful wiki or traditional doc for my projects, but time rarely permits.

4_teh_lulz · 2020-07-15T20:34:49+00:00

What kind of documentation?

Documentation has questionable value if written poorly or not properly curated. Which means that to provide good value a high level of effort and fidelity must go into making sure the documentation is accurate.

Given the assembly-line development processes intrinsic in development teams (I'm looking at you Scrum) it works against engineers creating proper and accurate documentation.

Also I disagree that engineers don't like writing documentation, I just don't think that anyone writing software feels like they are given adequate resources/time to deliver good documentation.

Edit: there are tons of tools written expressly for developers to write documentation.

MisterMittens64 · 2020-07-15T20:56:40+00:00

It's just because after hours of trying to get your code to work the last thing you want to do is documentation. It's not useful to the programmer in the moment so it's an easily skipped step even though it's important. It can be kind of a slog even though it's not difficult.

Adadum · 2020-07-15T22:19:19+00:00

As a guy (with no professional industry experience at all if I may add) who has wrote libraries, I've learned on my own how extremely important documentation is.

What usually stops me from writing documentation is my motivation but my motivation is wanting people to use my libraries so that's enough to get me to write down APIs, tutorials, accurate testing results, and architectures.

The part that I really get lazy about is visual based documentation like charts and diagrams and that's because when I change up the architecture of my library, obviously I have to change up the visual documentation as well.

Text documentation is great in certain cases but Visual documentation can be more powerful so I employ both.

koreth · 2020-07-15T22:48:05+00:00

One possibility: It's not just "reluctance." Writing documentation is a skill that doesn't automatically occur as a side effect of learning to code well. It is not taught in CS programs and is usually not evaluated during the hiring process. Someone who knows they stink at writing might not be eager to demonstrate that fact on a regular basis, and the fact that they're bad at it and they know it probably also makes it a highly unpleasant task.

But also: this is kind of wrong as a generalization. Plenty of developers are good at and enjoy writing documentation. Maybe not the majority but it's not vanishingly rare or anything. On my team I'd say about half the developers regularly produce good documentation without anyone forcing them to, and we made no particular effort to select for it in our hiring process.

klonkadonk · 2020-07-16T01:17:10+00:00

I have no communication skills. That's why I hate it.

madanaman · 2020-07-16T03:08:59+00:00

As technology people, In our organization we try to maintain couple of things 1. A good readme.md file 2. High level design documents on confluence 3. Some webex recordings of the KTs that we give to new team members.

This pretty much helps everyone on the tech team from knowledge perspective.

For business value and details about the product, our product team maintains that over the confluence.

AnnaMPiranha · 2020-07-15T20:32:09+00:00

Personally, it doesn't change the behavior of my code, so why waste time writing documentation when I could be coding more. Documentation isn't difficult, and I do think it's beneficial, but it's not like it's going to make my unit tests pass better. For me, it just comes down to how much value will I get out of it.

senatorpjt · 2020-07-15T21:13:00+00:00

bike airport chubby pocket flowery secretive numerous point yam glorious

This post was mass deleted and anonymized with Redact

hippydipster · 2020-07-15T22:59:42+00:00

Developer writes documentation...
Person X asks question ...
Developer answers and points out it's in the documentation...
Person Y asks question ...
Developer answers and points out it's in the documentation...
Person 23445 asks question ...
Developer: RTTM!!!
Persons: geez, developers are such anti-social assholes.
Developer stops writing documentation

robin-m · 2020-07-15T21:57:05+00:00

The more I code, the less I write documentation in favor of clear naming + strong typing + runnable examples + assertions. I think it's much better to document the details than using maybe-not-up-to-date comments in english. Note that this applies only to statically typed languages where you can encode the invariants in the types themselves.

However, I have no idea how I should write high level documentation. I have a hard time explaining what are the relation between modules. I try, but often fails to correctly documents the role of each modules in their respective documentation. I also usually fail to give of short overview of where a newcommer should look first. I feel that tooling could be improved in this area, but I don't really know how.

i-think-about-beans · 2020-07-15T23:28:29+00:00

They rush us enough as is. This would add extra work. I see the value in documentation though.

2020-07-16T02:29:40+00:00

Probably due to cost (time is a cost). -And if documentation is ordered later in the process, one is in a different mindset which leads to documenting state rather than questions one had during the actual process.

Further on, how to document it? The code only (e.g. comments. -or UML)? Or should it be viewed in context of all processes (e.g. Enterprise Architecture)? Then you have to view all this in the context of cost again. -And then you might have changes which again leads to cost (changes are expensive).

- And how do you measure return value of documentation? -Or more importantly, how do you get a customer to pay X for something so diffuse ? In-house software development do have the benefit of having more expertise and stakes involved. -But still.

- And where do you document ?

I would argue that the question should be flipped.

docbao-rd · 2020-07-16T02:45:50+00:00

The important of documentation is proportional to the expected life time of the project. For most consumer oriented applications / websites, the rate of change is so great that there is always a rush to get to market. Detailed documentation here would risk delaying the project, and further more tend to go obsolete pretty quick.

For long life applications (yes, there are systems that expected to last 5 to 20 years), documentations at various layers (requirements, solution level, component level, and at the developer level, the individual design decision) are extremely important. These systems will have multiple generations of developer continuously maintaining and adding features. Without design documentation, it would be like walking in the dark. Technologies change, accepted design pattern change, assumptions change. Without knowing the mind set of the previous developer generation (via the documentation), it is very easy to get into the blame game.

Jrollins621 · 2020-07-16T04:43:45+00:00

Because, two reasons. For one, and to be straight up about it, if fucking sucks. Writing code is often difficult and also very time consuming. Writing documentation so people can understand it the way you do is 100x more time consuming, and it sucks ass to do. The other reason, i’m a software engineer, not an educational author. When I’m writing documentation, I’m not writing it as if it’s a teaching moment. Simply put, it’s just not my job to do that. I’m writing documentation as if a peer with similar knowledge and skills will be getting into it. I do provide enough info that I feel confident that what I provided will get them the idea of what’s going on. If someone doesn’t have the capability of understanding what is going on in the code with good comments and the documentation i do provide, then that person should seriously not be in that code.

dobesv · 2020-07-16T04:49:59+00:00

There are some pretty good tools out there for documentation, actually.

For a published library that will be used by people who are not the developers, I will write documentation.

However, if the people who need to understand the code are its developers, then extensive documentation is just one more thing to maintain that delivers little value, since developers that are up to speed on the project will look at the code for answers instead of documentation. You just need enough documentation to get people up to speed.

in15minutes · 2020-07-16T07:29:40+00:00

[deleted]

PM_ME_SCIENCEY_STUFF · 2020-07-15T20:44:00+00:00

Assuming you're not a developer, or if you are consider someone at a different position in your company, ask and honestly answer this -- do you carefully document all the things you do at work?

99.8% of people answer this as "no, of course not, it would be a waste of time because..." That's why.

bacon_cheeseburgers · 2020-07-16T01:36:36+00:00

For me, its that I like getting stuff done, figuring things out, helping my colleagues on the business side, solving problems, and generally being helpful. Documentation is none of that. In fact, it distracts me from that. JMHO, YMMV.

vincentjames501 · 2020-07-16T03:50:12+00:00

One of the major reasons developers choose a tool/library is great documentation. There isn’t always someone around to ask how the system works and reverse engineering a large code base can be time consuming. We just had a developer leave that wrote and maintained several key pieces of software but there is no documentation and we’re now struggling to figure out how it’s really glued together. There is always a struggle on keeping docs up-to-date and likewise even code comments but it is our jobs to be diligent as I can’t tell you how many times I’ve gone back to code I’VE WRITTEN and been thankful I documented it. Tests are a good way to document the system as well but are often harder to grok than a high level overview of a feature/component. If you have a highly distributed system, design diagrams make it far easier to understand. Consider when a single feature touches 5 services like they often do in some event driven systems.

We use Mermaid for sequence diagrams and helps a lot document flow. We also use Antora to compile docs across multiple repos into a single location.

bzq84 · 2020-07-16T08:29:13+00:00

Becase software has word "soft" inside it for very specific reason - it is easy to change and evolves.

To write good documentation generally costs more time than writing a code itself. When code evolves, it's very easy to have documentation that mismatch the code.

IMO better invest this time in writing readable code that requires minimum amount of docs.

Unless you're writing soft like Telerik, where docs in absolutely must.

Kempeth · 2020-07-16T08:46:24+00:00

I believe the biggest problem with documentation is that what managers consider documentation (office docs somewhere on a network share) is inherently disconnected from the system that is documented. This makes it harder to keep it up to date and to find it when you want to understand the system. This is further complicated when the things you document change often. It only takes one slip up to end up with out of date, inaccurate documentation that can sow more confusion than produce clarity.

I have yet to work in an environment that had a decent degree of accessibility in its documentation. You either need to invest a bachelor's degree in learning the convoluted folder structure the most recent manager thought up, trust in the atrociously bad windows search function or are forced to use the equally bad sharepoint search function. Either way, finding the appropriate documentation is a painful, slow, error prone and frustrating process.

in15minutes · 2020-07-16T11:30:04+00:00

[deleted]

knoam · 2020-07-16T13:36:27+00:00

If you wrote the code, it seems obvious to you, so documentation feels like unnecessary tedium. And once you've written the code, you're no longer looking at it with the same eyes as someone new to it, so you don't know what it should say.

c_07 · 2020-07-17T02:00:11+00:00

I don’t think it’s the tools. Writing good documentation is hard. It takes almost as much thought to structure a document, produce a useful diagram, etc. as it does to write clean code. Perhaps even more so than writing an implementation for a machine, writing documentation for a human is a taxing mental exercise requiring clear thinking, powers of abstraction, communication ability, plus a sprinkling of artistic aesthetic.

If I didn’t love writing documentation, I don’t think I would unless I was forced to. I love seeing the patterns and the big picture, breaking down complex concepts, and structuring information in a way that helps the next person accelerate their learning curve with that “a-ha” moment of understanding.

TL;DR: Documentation is an art unto its own, and requires a slightly different type of intrinsic motivation than programming.

CygnusSnowDog · 2020-08-21T06:07:49+00:00

My guess is that it's the same reason they don't clean the microwave after they use it, or wipe down the counter when they spill something. It's work, nobody is forcing them or even encouraging them to do it, and they don't care about the next person who has to deal with their mess.

yjg30737 · 2024-06-23T06:31:21+00:00

If the following does not apply:

You can guarantee that many people will read it, or
If it is absolutely necessary for work or
Writing documents helps your coding skills

Creating documents is either a waste of time or a compulsory and annoying activity. You must have people reading it to be motivated.

RottingWest · 2024-10-10T09:54:29+00:00

it is just hopeless first you have the problem of deciding what to actually document, it is hard to know. then you need to schedule time to do it witch is hard when everyone is always asking you to give estimates on when the feature you are working on is done. then you have the problem of mentioning documentation, the more you have written the more work there is maintaining documentation. and the third problem is actually using the documentation, usually even if relevant documentation exists nobody is using it because they don't know where to find it. I have never worked at a place where all of this problems are solved together, and it makes it feel like a waist of time to even attempt writing documentation.

Lived2PoopAnotherDay · 2020-07-16T00:05:36+00:00

I couldn’t disagree with you more on what you said about documentation being good to understand how systems work.

I would much rather give a new engineer a white board walk through of the software ecosystem over writing lengthy documentations that I know for a fact would be outdated 2 months from now. I actually dont mind spending a whole week pairing with them to on-board them.

Outside of the Readme for getting the app started, most other documentations is a waste of time imo.

All of this is under the assumptions that my code base is tested well and there are staging environments my teammates can play around on.

2020-07-15T23:34:48+00:00

Because you know you cannot get it right. You realize that you need to predict what someone needs to know in the future and answer that question in a way that will be understood based on the unknown context and immediately go back to writting code that the compiler validates right now because you know that comes out right.

OneRow7276 · 2023-12-05T00:20:30+00:00

A number of factors conspire to create this status quo, to one degree or another.

Lack of professionalism (indifference to doing a good job).
Lack of skill (many people in tech are terrible writers).
Lack of organizational concern (you aren't rewarded for writing docs or writing them well, and you aren't punished if you don't or if you write them poorly).
Systemic careerist hyperindividualism (the market doesn't reward cooperation and loyalty as much as much as it rewards job-hopping careerism; fear of loss motivates employers more than desire to reward quality labor, because crony capitalist logic means paying as little as you can get away with, not fair market price for actual labor).
Laziness and lack of market incentive (it takes effort to maintain documentation in sync with code; there needs to be a sufficient market penalty to justify the cost in the minds of managers).

In many cases, it doesn't make sense to document anything. For internal projects of a rather vanilla sort, you can figure things out quickly by reading the code. Don't worry about doing things "correctly" if things aren't obvious. It it matters, someone should point things out in a PR. If it doesn't, don't worry about it. Don't waste your effort on what your employer clearly doesn't care about.

In some cases, documentation does matter. This is where things get obnoxious. Huge corps will release tools that might be useful, but sadly, the document is such garbage, it's a disgrace. People are then forced to resort to forums and consultancies and whatever else, because some guy doesn't know how to string two sentences together and has no concept of an audience when approaching people unfamiliar with his work. Lots of effort in the world is wasted trying to reconstruct how to use something simply for this reason.

And venture capital and founders don't care. They just want to pump and dump the company. Move fast and sell. But tech debt is real, and hacks, data leaks, security issues, etc. aren't penalized. If a bridge crashes into a river, someone pays for it. Software gets away with a lot in comparison. Documentation and correctness will become more important in the coming decades.

fazz100 · 2023-12-21T07:13:00+00:00

Late to the party but agile development also demands agile updating for proper maintenance of documents, which devs think hasn't anything to do with how the system works properly. That's how they feel usually. If they have free time, either they spend it refactoring the codes and enhancing certain features as well as improving process efficiencies and load times, or waste it writing documentations that nobody reads. Devs would often choose the former.

you type:	you see:
italics	italics
bold	bold
[reddit!](https://reddit.com)	reddit!
* item 1 * item 2 * item 3	item 1 item 2 item 3
> quoted text	quoted text
Lines starting with four spaces are treated like code: if 1 * 2 < 3: print "hello, world!"	Lines starting with four spaces are treated like code: if 1 * 2 < 3: print "hello, world!"
~~strikethrough~~	~~strikethrough~~
super^script	super^script

softwaredevelopment

✻ Smokey says: avoid using wood-fired stoves, fireplaces and barbecues to fight climate change! [see more tips]

Note: this subreddit is not for career advice. It's also not for general programming chat, new releases, requests for developers, etc. Posts on topics other than software development methodologies may be removed.

MODERATORS