undefined | Better HN

0 pointsconstantcrying2y ago0 comments

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.

0 comments

7 comments · 3 top-level

vundercind2y ago· 2 in thread

“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.

constantcryingOP2y ago

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

eviks2y ago

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

kbolino2y ago· 1 in thread

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.

constantcryingOP2y ago

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.

jdsully2y ago· 1 in thread

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.

constantcryingOP2y ago

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.

j / k navigate · click thread line to collapse

0 comments

7 comments · 3 top-level

vundercind2y ago· 2 in thread

“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

constantcryingOP2y ago

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

eviks2y ago

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)

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

kbolino2y ago· 1 in thread

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.

constantcryingOP2y ago

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.

jdsully2y ago· 1 in thread

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.

constantcryingOP2y ago

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.

j / k navigate · click thread line to collapse