Technical documentation can be unhelpful as it sometimes leaves out a lot of surrounding context. So even if you’ve got the docs it can be unclear how to apply what they say as so much other knowledge is assumed by the authors.
This is understandable as they tend to be written by people who know the thing inside out and backwards, but there can be a gulf between the beginner getting started guides (if any) and the proper docs, that only reading/asking questions can properly fill.
Plus, reading manuals is a skillset all of its own. It might seem easy to you, but so is reading novels - but you couldn't do that right at birth. Some junior devs just haven't developed that skillset.
After spending years learning on the job, I started reading the documentation books cover to cover, and I have never looked back. Colleagues are often amazed at my "deep knowledge" of the technologies I use, however I mostly know what is written in the manual. It baffles me that people can't be bothered to read the documentation and at the same time complain that "X is too hard! Let's use Y instead!"
That's my feeling exactly. Too often the manuals and documentation people read are a chore to get through because they're so boring. They're also passive aggressive because they're obviously saying their technology is better in some way, but they're trying to be nice. You read through and there's little lame attempts at being the next Oscar Wilde when really it'd be much better if they just came out and started a fight.
When I write my docs I want it to teach people how to use it, and not put them to sleep at the same time.
That's a poor reason. Learning how to write effective technical documentation is a great skill for anyone in our field. Even a team lead should be able to edit/review technical documentation.
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!)
Often people complaining about Technology X simply haven't read the docs. They're not always written, not always easy to find, and not always complete, but whatever is there, is there for a reason: it's something the developer thought you ought to know.
Being the one person who read the docs is the difference between being considered just another tech worker, and the "genius" people rely on for answers. It makes you invaluable, boosts your career, and leads to better outcomes.
Documentation shouldn't be difficult if your engineers are competent either. It only needs to be done once, and saves a bunch of time.
This is in line with the "suckless" philosophy too, they forgo documentation because they'd like their user base "small and elitist" with "no novices asking stupid questions".
Technical documentation isn't the place for a joke full stop. Documentation is for people who are typically busy, uncertain and potentially dealing with something that is going wrong.
They want clear, concise and accessible help. They don't want or need tasteless jokes. It is disrespectful to their time to include random garbage.
This is supposed to be read by people who need it, not people who know what is going on and want to enjoy a good laugh.
Bad documentation covers obvious things very well, and doesn't cover tricky parts at all. This is especially what you get if the writer of the documentation is paid by the amount of written text: there is no incentive to spend time investigating the hard parts, but a lot of incentive to explain the easy parts in too much detail.
My suspicion is that it's documentation written by people who don't use, don't know how to use, and do not understand the product.
Fundamentally, technology is means and method, and both point to ends or goal.
Technology is the study of means. (John Stuart Mill's definition. He also gives science as "the study of causes".)
Which means that documentation should point you at what you might want to do and how the tool(s) available to you serve that end. Referencing only the internal state of the system itself (and worse, at the most trivial level, as in the example give, which is by no means unusual in the field) is ... perfectly useless.
It's actually worse than useless, because you've got to wade through so much goddamned mud soup trying to find information that's actually useful. I've long had this problem with various "documentation by the pound" publishers -- Que and "Learn Foo in 24 hours" type series -- where the books are so padded with cute comments and junk statements that you cannot find the real meat.
O'Reilly's "Nutshell" series often go too far in the other direction, but at least the information is (usually) there.
The O'Reilly UNIX Power Tools book, a cookbook of recipes and methods with specific ends and goals explicitly stated is, pound for pound, probably the most valuable reference book I've ever bought. It doesn't cover everything (though it touches on a lot of material), but it covers a vast range of useful information and best of all gives you the tools to find out more.
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!
People who try to make something easy by force of "magic words" is pretty common in the tech industry.
People who write the docs likely do not want the reader to feel stupid.
This is low hanging fruit and good advice. No one is screaming or fragile here.
reply