43

Where do Documentation & regular Q&A fit in Stack Overflow's hierarchy?

Assume a Stack Overflow question can be fully and acceptably answered by a specific Documentation Example.

Which (any/all) of these ways are good ways to answer the question.

Is any of the options “best”?

Option#1: Answer the question in your own words – ignoring the Example completely.

This implies Docs and Q&A are completely different entities in the heirarchy – not to be mixed in any way.

Option#2: Paste the Example into the answer and add a citation link to the Example.

This implies Docs are an “external” reference to Q&A. It implies that the Q&A must still be able to stand on it’s own as a complete entity.

Option#3: Leave a link-only answer – linking to the Example.

This implies Docs are equal to Q&A in the heirarchy and that link-only-to-Example Answers form a complete Q&A.

Option#4: Close the question as a duplicate of the Example.

This implies that the questioner should use Docs first to seek answers and only ask a question if the Docs fail to supply an answer.

5
  • 4
    I'd do option 1 but with a prominent link to the example, rather than "ignoring" it.
    – Frank
    Aug 3, 2016 at 17:06
  • 2
    I disagree that Option #4 implies that Docs are "superior" to Q&A. That term has a lot of potential baggage associated. It does imply that OPs should search first, here and elsewhere, and uh... don't we already want that? Aug 3, 2016 at 18:08
  • 1
    @Two-BitAlchemist. Agreed, "superior" has negative connotations -- I've removed that part. Yep, the point of Option#4 is that questioners should begin (or even be channeled) into Docs first and only progress to Q&A if Docs fails to enlighten. As to "don't we already want that?". I would say yes, but I don't know what the powers-that-be are intending. :-)
    – markE
    Aug 3, 2016 at 19:42
  • I'd settle for #4, with #3 as an acceptible work-around until #4 is implemented.
    – GolezTrol
    Aug 4, 2016 at 13:41
  • 1
    "This implies that the questioner should [...] only ask a question if the Docs fail to supply an answer". Well, yes, ideally. But this was true before Stack Overflow Documentation was a thing...
    – TylerH
    Aug 4, 2016 at 13:48

3 Answers 3

21

I'll address 3 and 4 first:

Option#3: Leave a link-only answer – linking to the Example.

No, don't leave link only answers. It's bad practice, and the link may change. Also said here.

Option#4: Close the question as a duplicate of the Example.

This is impossible currently. If this gets implemented (it's currently ), then it's a pretty good idea to use the feature. But that's far enough off right now that we don't need to worry about it.


Option#1: Answer the question in your own words – ignoring the Example completely.

Option#2: Paste the Example into the answer and add a citation link to the Example.

I think some combination of these two options is the best. I would answer the question with your own words, but link to the Documentation (as long as it's high quality Documentation). If you feel that the Docs explain something well, quote it with proper attribution.

13
  • 7
    "No, don't leave link only answers. It's bad practice, and the link may change." I believe this prohibition has to do with link-rot off-site. One of the big promises with the new docs feature is "no more broken links". Can we not hold the bar a little higher for internal links? Aug 3, 2016 at 18:00
  • 14
    @Two-BitAlchemist Curating well-structured docs will probably involve splitting or merging examples. Until that's in place with some redirects or backlink lists or something, yeah, I would not trust these internal links' immortality.
    – Frank
    Aug 3, 2016 at 18:04
  • 1
    @Frank Well I don't trust them either in Beta until we get the features right. The point is what behavior we should expect, not how things currently function 1 week in. Aug 3, 2016 at 18:06
  • 2
    @Two Okay, but I think we're a long way from there. For starters, when I delete an example, I need to see a warning popup like "But look at all these links you'll break!"
    – Frank
    Aug 3, 2016 at 18:08
  • @Frank We should handle that however we handle deleting Q&A that are the target of dupes. Aug 3, 2016 at 18:09
  • 1
    @Two For reference, dupe-linking prevents deletion: meta.stackexchange.com/a/239597 With docs, that might be more annoying than anything else, but I guess that's a separate discussion.
    – Frank
    Aug 3, 2016 at 18:12
  • 2
    Deleting examples will not break links to docs. See stackoverflow.com/tour/documentation: "Every topic link contains a timestamp, so if you need an older version you can always get to it."
    – Ajedi32
    Aug 3, 2016 at 18:26
  • @Laurel. Documents are evolving, so if it becomes possible to "dup-link" to an Example, would you favor dup-linking?
    – markE
    Aug 3, 2016 at 19:47
  • 1
    @markE Yes, since they will have the data supporting its usefulness at the point where they decide to implement it. (See edit.)
    – Laurel
    Aug 3, 2016 at 19:58
  • 3
    Regardless of whether the link changes, the content of the documentation might change, so better to copy out the relevant part and use it in the answer
    – rdans
    Aug 4, 2016 at 13:03
  • @rdans That's exactly what I meant when I said that :). And that's exactly the solution I recommend later on in my answer, as long as proper attribution is used.
    – Laurel
    Aug 4, 2016 at 15:33
  • Yep. my comment was more of a response to the other comments about whether the links will break in the future
    – rdans
    Aug 4, 2016 at 15:47
  • 3
    @Two-BitAlchemist: Link only answers that link to other SO answers are not cool either. It's not just about link-rot, but about providing actual added value rather than just an extra click. Aug 6, 2016 at 12:30
3

While I realize, as the other answer points out, this is not currently possible, I'd vote for Option #4.

  • Option 1: Doesn't leverage documentation.
  • Option 2: Introduces "bad fragmentation" and isn't DRY.
  • Option 3: Is the same as #4 to me, except without the veneer of official support.

This also allows us to use Docs as another source of a single canonical answer, without the need to produce awkward self-answered questions or to decipher which is the best of fields of similar questions on SO which may form large chains of dupes of dupes of dupes. It also allows us to have a single, clear answer/example without any pollution caused by discussing particular problems of a single OP that won't be relevant to future readers.

-2

I suspect option #2 will become the most valued answers.

Questions on Stack Overflow are often asked by people looking for specific, personalized assistance, and then later googled for by people looking for general information, e.g. missing documentation. If a question is completely answered by some example in documentation, a link to said documentation should serve as the meat of an answer, but responding with nothing besides a link (or, especially so, leaving a link plus a derisive comment) feels dismissive, even to a beginner, who may be unaware of the docs that they should be reading.

Option #1 feels backwards - if a question can have a solid, generalized answer, it may be good to create documentation and link to it as your answer.

Option #3 I mentioned earlier. "I wrote this doc to answer this question" is reasonable and constructive, but Stack Overflow is not exclusively a place to record knowledge in Q&A format, it is also a place where people are asking questions to get them answered by other people. If a link would suffice to answer a question, then they may need to specify their question.

Option #4 This seems like the kinder version of #3. See Laurel's 'impossible currently' link for discussion of adding this feature. What this would do, hopefully, is deflect redundant questions, either to proper documentation, or make it clear that their question is different from or more specific than the common-knowledge answer available in the documentation, and would push them to rewrite their question to be closer to what they actually need to ask.

As for the described implications - in a perfect world, #4 would be the correct implication, that docs can give answers and that Q&A is a backup for edge cases. However, docs require up-front, generative work whether hosted by Stack Overflow or not, which is why so much of the world's documentation is lacking in the first place. Q&A became the resource it did because randomized reactive answers produced a kind of decentralized documentation as a side-effect. We'll see as time progresses whether Stack Overflow's documentation become a formidable enough resource that people can expect to search through them first, but for the moment we should still ask and answer knowing that ours may be the first words found by people trying to investigate.

Not the answer you're looking for? Browse other questions tagged .