I have often seen people complain about auto generated documentation being worse than useless when that is not the case. It's not that the documentation is poor, it's that there is a complete lack of the other 3 kinds of documentation.
It seems like an example of how automatic documentation generation spews out garbage unless you work to create comments specifically for documentation.
There are links that go places, but nothing anywhere actually shows working code examples, or even non-working fragments.
One of the reasons actual civilians were able to write their own programs back in the 1980s was that Turbo Pascal, and Visual Basic had decent manuals, and there were plenty of "dummies" guides as supplements.
Documentation should include working example code for each and every library, function and property supplied.
> The only thing worse than no documentation is incorrect documentation," he said. "Because no documentation means I go somewhere else to look for it. Incorrect documentation wastes my time."
Basically: yes. Some here on HN will disagree, but they are IMO wrong. Another big time-waster for users is failing to write a document intro that identifies the target audience and the document's target information goals; it sucks to get 30 pages into the document before you finally manage to figure out that it's not the document you want/need.
The documentation does _not_ suck. It it literally the most well documented software in existence, a reason for which it has been used for many different things outside its original purpose of text editing.
Yes, it may not be for everyone. But just say that, that it uses certain conventions that are likely outdated for a reasonable set of the population. But you can't say the documentation sucks when you have the below:
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.
Oh, no doubt that (or just a single webpage view of all the documentation) _should_ be something that all documentation should provide, but I don't think it's any surprise that not everything has good/ideal documentation.
Now if you clearly understand the tradeoffs of such tools and still decide to use it, that's fine. What I see in practice is that many decide to use such tool and are not really aware of the tradeoffs they make.
I personally believe being accessible is a mandatory feature for any documentation website framework. But maybe you'll publish the docs just for yourself or a very limited set of persons, in which case you might care less.
There's a lot that is mistakenly conflated as "documentation".
Sometimes I would know enough about a topic except for one little thing and would look to the documentation. I only needed information on that one little thing to be productive, but I'd get stuck reading someone's entire backstory, trying to skim and find the one useful line in a random example to help me.
Other times, I would find documentation and struggle to follow it in practice until I came to the conclusion that I would need to read the whole thing in its entirety to become productive. I would either have to block out some time to learn it all or go with a completely different solution.
I used to think projects that claimed to be documented either fit into two groups:
1. Good documentation: I can find what I'm looking for
2. Bad documentation: I can't find what I'm looking for
There isn't just good documentation and bad documentation, there are 4 different kinds of documentation for distinct types of information delivery: Tutorials, How-To Guides, Explanations, and finally Reference.
Now I consider documentation good or bad based on if it contains all 4 kinds of documentation.
The docs are soooooo bad. This is the same story with any exciting / new product.
Honestly, I'm beginning to think that we need some kind of documentation-first style development. Like TDD, but DDD....
I have integrated Facebook APIs, Instagram (well, same thing), Google APIs, Stripe APIs, Mailchimp APIs, etc. etc.
And the only thing common among all of them? The documentation is _terrible_..., like, _terrible_.
I also run a few products online and I spend so, so much time trying to get the documentation right. It's incredibly boring and tedious, but I really feel that if you want to set yourself apart from the big players, make good documentation. It can't be that hard.
Is website documentation not good enough? It looks very thorough. Actually I’d say that it’s rare to encounter so verbose and full documentation nowadays. May be it’s even too deep, but I enjoyed reading it.
Documentation was a bad idea. The only problem Documentation might solve is that Stack Exchange Inc has a bunch of developers and they have to keep them busy doing something. All the thrashing and weird incentives and bullshit flows from this truth: the users and community don't need anything like this Documentation.
In several organizations, I have been the person who writes high-quality documentation. I enjoy writing (and reading) good technical documentation, so this is a self-appointed responsibility. I agree that people aren't interested in documentation for something they either probably-know or probably-don't-need-to-know, so a vacuous thumbs-up emoji is all I expect when creating documentation.
However, the "you can hand out a link" part is what really grinds my gears. The expectation of my former coworkers that it is <someone else>'s job to find the proper documentation pages for them was quite exasperating. '@anatnom can get you the docs for this' and similar messages is...disheartening. My workflow was always to go to <internal docs page> and search for <relevant term>.
Perhaps there are organizations where the documentation-writers are not also encumbered with being the link genie, but I've not had that experience. I wish I could teach a dev to fish, but instead I have to hand out fish all day.
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.
It generates auto-docs, which are useful. It's just a ridiculously verbose way to do it, and it would be preferable if the documentation could be generated without the repetitive comment.
Note that it's a contentious issue. Lots of people think there's plenty of documentation. I'm one of them. The people who think documentation is lacking seem to be people who need worked examples of things to understand them. I'm of the opinion that worked examples are often worse than no documentation.
https://news.ycombinator.com/item?id=21289832
I have often seen people complain about auto generated documentation being worse than useless when that is not the case. It's not that the documentation is poor, it's that there is a complete lack of the other 3 kinds of documentation.
reply