I do agree with this in the end. I also think people often underestimate how challenging it is to create good docs.
I've seen this pattern often:
- Person doesn't know how to do something.
- They fumble around until they get it working.
- Once it's finally working, they write a doc about how they did it (because our "poor documentation" is a common pain point and therefore a popular problem to attack).
- If you actually search our internal docs, you find at least one other doc describing the same process.
I've seen this happen in many different contexts, even onboarding. I've seen multiple people join the company, and each one wrote down their own "onboarding painpoints" doc to hopefully help the next person, without even noticing the existence of the previous person's equivalent doc.
So again, I still agree with you. Even in these scenarios I described, I'm willing to believe that there is some way we could've structured our docs that couldn't prevented these issues. But I have no idea what it is, and seeing all the futile attempts at improving the situation makes me irk a little at armchair "poor docs"-style comments (not that that's even related. I've gone a little off topic here!)
This is exactly what I meant. Most companies don't care about providing good documentation, and so when new people join the company and don't know what's going on they blame the platform or the package manager or something else.
There aren't very many good alternatives to writing good documentation.
All this assumes one important thing: That people will read what you put in front of them.
I've been working in startups for several years now at companies of a variety of sizes, all of which were remote-first, and which (ostensibly) relied on writing to communicate.
People do not read what you write. I don't know if they can't actually read fluently or if they won't, but it does not matter if I submit a bug ticket that says exactly what is happening and lists the ten things I've already tried to resolve it. 100% of the time, the first reply is to ask if I've tried doing any of the first three things I said I already tried.
It's that kind of thing that makes me think documentation is hopeless. Nobody's going to read it anyway.
Thank you for saying that, I sometimes feel like I'm taking crazy pills when I hear some of the inane arguments against thorough documentation.
I was hoping this was going to be about the real "documentation fallacy:" 'Documentation tends to be of low quality, therefore it is best to avoid writing much documentation.' One common instantiation of this is "thorough documentation is bad because it will inevitably fall behind the code and be inaccurate."
People fall into the trap of assuming there is something inevitable about bad docs. Yet they never assume there is anything inevitable about bad code, even though most of the code in the world is, objectively, complete shit!
The frustrating thing about poor documentation is that the product actually works! It's just that the creator didn't go the last 5% of the way to explain to someone else how. The close-ness of the solution is what makes it frustrating by nature (it's not frustrating when you encounter a 2% complete solution to your problem).
My point is, the fact that poor documentation frustrates many people according to a survey does not mean that software developers can't or don't write documentation.
I think the simpler answer is that most people who complain about documentation cannot improve the docs because they don't know how. If they did understand what was being explained in the documentation, they wouldn't be complaining in the first place.
Oh you're right, I was thinking of another comment in this same thread. Mea culpa!
But my criticism of your attitude stands. If this is how you responded to developers on your team making obvious suggestions about how to make documentation useful to them, then it's no wonder you've had this problem of people not reading documentation.
Again, this just isn't a problem most teams have, because there are good solutions.
> Unless they are not reading it, or properly paying attention. [...] Sometimes it is on the user.
If they make no effort, sure. But looking for an answer to a question and finding something that seems to works is a perfectly reasonable way to use documentation. If there's a dangerous gotcha and it isn't documented right there, then the documentation is structured badly.
> Or following an unofficial document
That could be a very clear symptom of bad documentation.
Sometimes it's on the user, but if lots of users are failing to use your documentation, maybe consider that the documentation is bad.
I can definitely see this issue, Some people just tend to end up "shaping" the software shipped for better or worse. If the org didn't emphasize documentation/knowledge sharing with someoene equally knowledge it would turn out to be pretty horrible
I like your perspective in general. The reason I don’t mind getting a little bit worked up about it is because most documentation is terrible and that can make people frustrated and feel bad when it doesn’t have to. Which plays into your point, but spreading this over thousands, or millions of users seems like a terribly unproductive strategy. If you correct the documentation, once you will make many people's experience better over the life of the documentation.
Sadly the docs are error messages are not seen as part of the product and something that is needed to make something complete. Shipping fast and constantly adding new features has pushed good documentation to the backseat. It’s something that’s nice to have, but almost no one prioritizes, so it never gets done.
From what I’ve seen, it is also something that comes with a mature team, as some stability is needed before a team starts to talk about documentation and standards. The constant churn of teams hurts documentation and error messages a lot. Why bother documenting or writing good errors if you won’t be around in 2 years to deal with it? More people need to stick around long enough to feel the pain of their bad decisions and laziness.
Coming from the same perspective, I agree completely.
Software pushers all seem to give the same puzzled look when I ask to see their full docs before evaluating their product.
It's exactly as you describe, if the documentation isn't sufficient for me to learn everything I could possibly need and likely want to know about how things work - I can't confidently design, build, scale or support it.
Documentation in the "Enterprise" world seems almost intentionally bad, as if to force customers into professional services and support contracts for products which lack the proper design to be sold as full on SaaS.
It is crazy. We hear these stories all the time. We have clear examples of good and bad documentation. Yet in the same breath, we condemn loners who neither solve nor worsen the problem by default, and praise the social butterflies omnipresent in places with these symptoms present.
Nothing is going to substitute throwing a few individuals with zero domain knowledge at your code/docs and seeing if they grasp enough. Certainly not some talking which fades away in 10 minutes.
I don't agree. Bad documentation is worse than no documentation. At least with no documentation, I start with the expectation that I have to figure everything out on my own.
It's very true. I think in reality it tends to be a mix—sometimes documentation goes stale, and sometimes people don't even bother reading it regardless of whether or not it's stale.
Another large problem is developers not knowing what they're looking for. Documentation tends to solve the "how I do use this" question and not the "do we already have a solution for this" question.
I'm still not sure how to solve the problem of discovery outside of telling people, "read the docs and hope that someday you'll remember the relevant bits when you need to."
It would be helpful to understand why you found that to be the case.
We get off-hand comments like this about the docs on occasion, and without explanation, we can't do anything to improve the docs to resolve the complaints.
We put in a ton of effort on the docs, and we think they're great. What are you missing? Did you spend the time going through and reading the docs?
Lots of documentation is written by and for people writing it and not for someone who just arrived at the company.
And then you expect some junior dev to just understand everything without asking.
A culture where people are afraid of asking questions is worse than having the best possible documentation on everything
I've seen this pattern often:
- Person doesn't know how to do something.
- They fumble around until they get it working.
- Once it's finally working, they write a doc about how they did it (because our "poor documentation" is a common pain point and therefore a popular problem to attack).
- If you actually search our internal docs, you find at least one other doc describing the same process.
I've seen this happen in many different contexts, even onboarding. I've seen multiple people join the company, and each one wrote down their own "onboarding painpoints" doc to hopefully help the next person, without even noticing the existence of the previous person's equivalent doc.
So again, I still agree with you. Even in these scenarios I described, I'm willing to believe that there is some way we could've structured our docs that couldn't prevented these issues. But I have no idea what it is, and seeing all the futile attempts at improving the situation makes me irk a little at armchair "poor docs"-style comments (not that that's even related. I've gone a little off topic here!)
reply