Well, in their defense, most documentation is terrible. You get used to being able to find something in two Google searches that you couldn't find in five minutes looking through the docs.
Agreed! I am an engineer and have written documentation off and on throughout my career. I'm continuously dismayed at the incomprehensible documentation generated by most companies. Google's documentation is particularly bad though.
Documentation doesn't suck because companies aren't using wikis right.
Documentation sucks because it's hard/impossible to do well. Every change to the code can trigger cascading changes in documentation and there's no compiler to tell you which things need to change.
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 not their documentation that is bad, it's the architecture. Too many layers, and things glued together. Where you need to make additional abstractions just to make sense of it all, ending up with a million LOC just to copy something from A to B.
For example integrating support for Google Drive took months, where I ended up using a third party solution, and users are met with a big red warning about my app now being unknown. And the file system is laggy. Compared to integrating Dropbox which took three days and just works. Google Drive probably have thousands of pages of documentation. While Dropbox have one or two.
I suspect that documentation quality is likely part of "by veterans", people old enough to have a considerable part of their programming biography set in the days before Google driven development. Slightly ironic.
The official documentation is worse - everything seems to be a mess of contradictions and constantly changing ways of doing things, with the documentation never catching up.
Most companies either do too little documentation (they have a little page with the bare minimum high-level overview), or they do way too much (detailed change request forms for every change, which go into a file cabinet, and are never looked at again). Alas, it's really hard to get people to understand that documentation is good and necessary when they've only ever been exposed to one or both of those systems.
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.
To be fair, if the documentation isn't meeting the users' needs it is poor documentation.
One of my more tongue-in-cheek maxims is that too much documentation is worse than too little. With too much documentation the information might be there, but you aren't able to find it. The outcome is the same, but with too much documentation you've just wasted an hour failing.
It's slightly tongue-in-cheek because you can push the amount of documentation pretty far, but you have to think about how to organise it and how users will get the required information when and if they need it.
reply