Comment by kbolino | Hacker News Reader

Comment by kbolino | Hacker News Reader

Parent Full thread

First-party documentation quality varies wildly, and in general has fallen off a cliff from the days when everything had a comprehensive, multi-volume, doorstopper manual.

There's also a lot of tinkering and breaking things that is necessary to develop a deeper understanding of a piece of technology, without which the manual is far less useful. Knowing where to look in the official documentation is half or more of the battle. Modern attention spans, planning expectations, systems complexity, etc. are not geared towards developing this deep understanding.

Moreover, the number one tool developers who cut their teeth over the past ~20 years have relied on to help them find the right answers, Google Search, has degraded massively in quality lately. Stack Overflow arguably breathed new life into search engines for a while, until SEO-hacked junk overtook it. Who can forget the classic forum posts "I fixed the problem [no details]" or "Why don't you Google it [even though this is the only meaningful Google result]". Even Stack Overflow runs into those issues, sometimes, though.

For many large software projects there is great, searchable and comprehensive documentation. If you know where to look, te answer to your question is most likely already there.

Of course there are questions not answered in the documentation, which is where stack overflow can shine.

I think the real problem is google, if it was a great search engine it would give you the appropriate documentation page for your problem and many, many people would never visit stack overflow for the answer.

“Goddamnit, I forgot the syntax for doing a for…in and assigning both key and value in this language, yet again, and my first two guesses were wrong”

Searches, clicks docs page, greeted with 20,000 words about flow control in the language, only the eighth example of for loops has what I want

Searches, lands on SO, what I need is one screenful below the fold, done

The only strong counterexample to this pattern I can think of is everyone’s least favorite language, PHP, because of its combo of narrow-focused docs pages and community posts on each filling in any gaps and pointing out any weirdness or features that exist but should be avoided.

Very curious. To me the opposite happens, if I forget syntax all I want to look at is a simple example, which is often easily found in the official documentation

tried in one famous doc site: Python search "for key value"

We get a more generally worded result only at position #12 (vs. #1-2 in a search engine)

And then see the excessive verbiage (though admittedly not the exagerrated 20,000)

> The for statement in Python differs a bit from what you may be used to in C or Pascal. Rather than always iterating over an arithmetic progression of numbers (like in Pascal), or giving the user the ability to define both the iteration step and halting condition (as C), Python’s for statement iterates over the items of any sequence (a list or a string), in the order that they appear in the sequence. For example (no pun intended):

Indeed, the difference to Pascal is what people are looking for as well as pun clarifications obscuring a single short sequence of substance

Even when the quality of official documentation is high, there are other uses for an SO-like site, I think:

- Handling corner cases that the original software developers never thought of, or their technical writers never thought to document, at least.

- Contextualizing, summarizing, and rephrasing the official docs in ways that people at different levels of familiarity and from different backgrounds find easier to understand.

- Providing errata and implementation notes that have been discovered over time by the users, before the official source is able to add them, or especially if the official source refuses to add them.

I don't deny this. I even said this was the case.

But many, many questions on SO have a good answer in the official documentation.

All I see everywhere is autogenerated docs with function prototypes I could have just looked at in the code. Nobody is explaining the "why" anymore.

To be honest I don't. Of course documentation takes effort, which some projects won't spend, but most stuff I have to deal with has high effort docs.

Reply on news.ycombinator.com