3 ms·

I suspect when quality docs exist, no one _complains_ about them. Having poorly-written docs can sometimes be as bad as no docs at all. I just experienced thi

I suspect when quality docs exist, no one _complains_ about them. Having poorly-written docs can sometimes be as bad as no docs at all. I just experienced this a few hours ago where I integrated a new library, tested in CI and locally. We see errors in production. Why? A connection configuration that I thought would merge with the defaults _replaced_ the defaults. The docs don’t mention this at all, but it’s pretty crucial for going to production.

P_I_Staker 3y ago
This isn't the greatest example. You're talking about an omission to the docs, so what you really wanted was MORE documentation. I can't really see how the docs lead you astray there, just that you "thought" it was different. This is illustrative of the problem with docs. It's shockingly hard for developers to predict when enough information is enough. Assuming it were wrong information, now the docs can't be trusted! In my experience, there's something else going on. Understanding software is hard. Often times, you have to roll up your sleeves and do some work to get the hang of it. This makes documentation an easy scapegoat. I can't count the number of times, I've had people complain about not finding something that was clearly explained in the docs. It's not that they aren't reading either! They actually read the text, don't understand, maybe don't even recognize that they don't understand and keep reading. I've also seen where very good documentation exists, but it contains some irrelevant information. So, I'm expected to write a smaller, almost certainly worse document, by telepathically figuring out what parts "matter for our project". I've just seen so much bullshit in complaints about documentation. After a while, it just looks like people don't who understand (reasonable), getting upset and looking for an out. After all others understand, what are you bad at engineering? This mindset is often driven by cultures and personalities. It's one of my pet peeves about engineering.

P_I_Staker 3y ago

This isn't the greatest example. You're talking about an omission to the docs, so what you really wanted was MORE documentation. I can't really see how the docs lead you astray there, just that you "thought" it was different. This is illustrative of the problem with docs. It's shockingly hard for developers to predict when enough information is enough. Assuming it were wrong information, now the docs can't be trusted! In my experience, there's something else going on. Understanding software is hard. Often times, you have to roll up your sleeves and do some work to get the hang of it. This makes documentation an easy scapegoat. I can't count the number of times, I've had people complain about not finding something that was clearly explained in the docs. It's not that they aren't reading either! They actually read the text, don't understand, maybe don't even recognize that they don't understand and keep reading. I've also seen where very good documentation exists, but it contains some irrelevant information. So, I'm expected to write a smaller, almost certainly worse document, by telepathically figuring out what parts "matter for our project". I've just seen so much bullshit in complaints about documentation. After a while, it just looks like people don't who understand (reasonable), getting upset and looking for an out. After all others understand, what are you bad at engineering? This mindset is often driven by cultures and personalities. It's one of my pet peeves about engineering.