8

As we are preferred to give examples in documentation, would the answers in these questions be suitable?

This question had been closed (as too broad - which is actually quite true), re-opened (on request by me), and edited by a moderator as it's not strictly the right format for SO, but may be a better fit for Documentation.

So this leads us to another point, if we find a poor question that has good answers with examples, would it be beneficial to move it to documentation?

5

1 Answer 1

11

The answer is yes and no.

It's yes because the official announcement states:

Topics are broader in scope than Questions. In fact, we're expecting that if you "asked" most requests, they’d be closed as Too Broad.

However, it's also important to consider the next bit of information:

Is importing existing documentation encouraged?

  • No. We're hoping we can improve documentation, not just move it under the stackoverflow.com domain.

In terms of copying existing answers, the answer is no, not really. And more so if the answer is not yours. There are a number of users (including myself) that are specifically testing Documentation suggestions for plagiarism. Expect your contribution to be rejected, especially if you have failed to properly attribute.

The fact is, the Documentation format doesn't completely line up with the Q&A format. And it's only specific types of "too broad" that fit the bill for Documentation.

Remember, "Too Broad" also covers:

  • "Too localized" problems that would require a huge amount of work and code to solve
    • This is definitely a poor fit for Docs. Or most anywhere, really.
  • Questions that lack critical details, like what language/technology should be used
    • Again, this is a poor fit. What would your Examples be?

Note: I have also added the content below to my Community Wiki answer here (which hopefully will become at some point). It provides a more general overview, so it's worth looking at in addition.

The right type of "too broad" question here applies to a broad audience. Obviously, this covers the material typically found in a tutorial.

But it applies beyond that, to entire classes of problems. The best way that I can think of to explain this is a metaphor:

These problems are headaches.

If you go to Health.SE, and ask "how to fix my headache", you will get closed as too broad, since there are a lot of things that cause headaches. And there are different types of headaches, too.

But "Fixing Headaches" would be a good topic for Documentation. Headaches affect almost 50% of the population, so it's certainly not too localized of a problem.

The broad nature also means that organization must dictate the structure of the Documentation. (And understanding the organization is important to understanding why this type of problem can be effectively covered in Docs.)

I would start out with a section that explains the different types of headaches, and how one can go about troubleshooting to figure out which one they have (Where does it hurt?). That section would include links to sections that help narrow the source of the headache to its source. Did you get wasted last night? You likely have a hangover. That, in turn, can be linked to another page on Docs that explains how to fix headaches caused by that particular source.

4
  • It looks like you excluded the examples of people you planned on including as plagiarism testers. ;-) (But overall, a helpful answer.) Jul 29, 2016 at 19:52
  • @JonEricson Thanks, it's hard to proofread that much text. I'm just listing myself (unless anyone wants mention :)).
    – Laurel
    Jul 29, 2016 at 19:55
  • Very good. To be honest, the credit for finding that goes to another employee in our internal chat. I missed it too. And good hunting. I hope you help make plagiarism extinct. Jul 29, 2016 at 19:57
  • FWIW, I pinged Jon about the error rather than editing or commenting here because at first glance I thought he was the author. Which, given my high regard for Jon's answers around these parts, hopefully speaks well for my opinion of your answer here! (And poorly of my ability to read small text on a Friday afternoon.)
    – hairboat
    Jul 29, 2016 at 21:14

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