20

I added a self answered question on SO with the contents of documentation, this was mentioned as a possible solution on the Sunsetting Documentation .

Within minutes it was down-voted, received several more down votes and close votes. Then it was moved to Meta, received more downvotes on both the question and answers and eventually closed and locked by @Cody Gray. Cody stated: "so I can have this conversation here on Meta" but since the question is locked that is not possible. Thus this question to allow the conversation.

23
  • The conversation is stated in the question: How to save documentation from sunsetting. Consider there are links to the documentation in SO questions. If there is a place on SO to move the documntation the links can be updates.
    – zaph
    Aug 4, 2017 at 12:55
  • 20
    I think the problem is the same as it's ever been: we want self-answered questions to be be just as good questions as any other. And that's hard. The migration of the post to Meta was really silly and just made things more complicated.
    – jscs
    Aug 4, 2017 at 13:01
  • In general I don't like self-answered questions and am not happy with this possible solution. Unfortunately SO is not planning a solution to the loss of the documentation. This was a proposed solution so I decided to try it and it seems to have failed. I think I will move the documentation to my blog and point the links there, this is also a poor solution I also don't link off-site links to blogs. It seems the consensus is to toss all the documentation in the trash, that seems such a shame.
    – zaph
    Aug 4, 2017 at 13:13
  • 2
    Sorry to hear it. I was excited to see your post and wanted to try editing to help out, but I wouldn't be able to get to it until much later today at the earliest.
    – jscs
    Aug 4, 2017 at 13:17
  • 5
    @zaph: "This was a proposed solution so I decided to try it and it seems to have failed." I wouldn't say "it failed" so much as "you did it poorly". Your question was closed because it was a bad question, just like any other bad question. It's not easy writing self-answered questions, since you have to make sure it's not just an excuse to post a blog. But you might also want to ask about our attribution requirements for your blog, in light of the fact that the Doc page will be deleted. Aug 4, 2017 at 21:40
  • 3
    @NicolBolas You know what: it is not worth playing games with wording: maybe it will pass maybe some random SO uswer will downvote, SO just wants to trash all the contributed documentation, so be it but it sucks on SO's part. I guess I was stupid to trust the SO documwnation area, I'll move them to my blog. Oh, you can take your attribution requirements threat and stick it.
    – zaph
    Aug 4, 2017 at 22:27
  • 4
    @zaph: That's not a threat; it's a requirement of the site. You can't copy content from it without attribution. It's the CC-BY license that all content here is presented under. My point was merely that you ask how attribution would work with content that's going to be deleted. Aug 4, 2017 at 22:39
  • 1
    @zaph: "SO just wants to trash all the contributed documentation, so be it but it sucks on SO's part." Nonsense. Nobody said that we want to just throw it out. But we're not going to relax our Q&A standards so that people can save content they like. If you want to preserve it on SO, you have to do it within Q&A. Aug 4, 2017 at 22:40
  • 1
    @NicolBolas Non mi importa. I wrote the text, I will use what I wrote as I please.
    – zaph
    Aug 4, 2017 at 22:49
  • 1
    @NicolBolas But SO is not providing a solution! No solution == trashing. SO just comes out of the blue and states the documentation is going away and to bad all you suckers that produced documentation.
    – zaph
    Aug 4, 2017 at 22:51
  • 1
    @zaph: No, SO is not providing a straight copy-and-paste solution. You can in fact preserve examples from Docs.SO as self-answered Q&A. But you cannot do it by just copying an example into an answer and writing a one-line question for it. Furthermore, there will be an archive of Docs.SO available. I fail to see how archiving something is equivalent to trashing it. Aug 4, 2017 at 22:53
  • 4
    Dude, I screwed up. I already told you that. I became a moderator like a couple of days ago. It should not be surprising that there have been a couple of cases where I didn't know exactly how the tools worked and made the wrong assumption. I already apologized to you, and I've done everything I can to try and make it right. If there's something more you want me to do, please ask. But I would prefer that you didn't accuse me of not knowing what I'm doing as just a blanket statement. I'm sorry that left such a bad taste in your mouth. Aug 5, 2017 at 10:24
  • 6
    @zaph Posting self-answered Q/A will always triggers some negative reactions in people and I have no clue why (probably they see it as rep hunting, without realizing that the rep hunt you do posting FGITW answers to duplicate questions). I personally got very disappointment when I tried this in my low-traffic tag, immediately 1 down vote, however time has shown that it was useful others. My only final advice is, be sure to have a nice question (a bit more broad then usual to me personal is ok) and maybe even if not correct I always included a brief statement of the purpose of the Q/A. Aug 5, 2017 at 13:37
  • 1
    @PetterFriberg: "Posting self-answered Q/A will always triggers some negative reactions in people and I have no clue why" Nonsense. I've posted several self-answered questions, and I rarely got any downvotes. Aug 7, 2017 at 1:51
  • 2
    @NicolBolas the keyword was "some", I had times in chat people thinking that it is discouraged, the comment was intended as "Post a nice question also, and don't worry about 1-2 dv", if the Q/A is useful with time it will even out. Aug 7, 2017 at 10:11

2 Answers 2

27

I'm sorry. My intention was to make my objections clear enough that there wouldn't be a need for much discussion, and then if you had any follow-up questions, you could just reply to me there. What I didn't realize was that the migration-rejection snafu had resulted in the question being locked, and thus preventing you from replying to any comments. Again, I'm sorry for that, and the confusion.

I didn't consider suppressing discussion there to be a big issue because any larger concerns would be more appropriately addressed on the main question about Sunsetting Documentation.

At any rate, my initial thoughts still stand, so I'll just quote them here:

It's totally fine to self-answer a question, drawing from information found in Documentation, but you need to:

(A) ask it in the form of a question like you normally would (without all this meta-commentary), and
(B) give credit to the contributors of the information pulled from Documentation (as you would for anything else).

I have no problems with the idea of "migrating" useful content from Documentation onto Stack Overflow proper via self-answered questions. In fact, one of my initial objections to Documentation was that it was superfluous because self-answered questions already did the job better. So this seems to me like a perfect plan. You just need to do it following our regular guidelines for questions.

11
  • (A) I did that, the commentary was in response to down-votes to explain why the self-answered question was created. (B) I created the [documentation](0https://stackoverflow.com/documentation/swift/7053/pbkdf2-key-derivation#t=201708041304132140517) and am not aware of any other contributors but would be fine with providing attribution, I did not consider adding an attribution for myself.
    – zaph
    Aug 4, 2017 at 13:07
  • 4
    (A) Yes, some of the extraneous commentary was edited in later, but even the initial revision is not presented in the form of a question that would be acceptable for Stack Overflow. Self-answering is fine, but you need to ask a question that follows our guidelines, otherwise you are setting a bad precedent. I think this is possible, but sometimes it does take a bit of creativity. Aug 4, 2017 at 13:15
  • (B) I could not tell, because there was no link to the associated Documentation, that you were the sole author of it. That will not generally be the case, so again, if we're going to start doing this, we want to avoid setting a bad precedent by omitting attribution. It looks to me like you were trying to cite the source (Documentation) in the question instead of in the answer where it more properly belongs. Aug 4, 2017 at 13:16
  • I did not add a link because the link would go bad when the documentation was removed. SO, the suggestion is to add attribution and a link in the answer? Any bets on up vs down votes?
    – zaph
    Aug 4, 2017 at 13:20
  • 3
    Yeah, I can't guarantee anything about voting. The community reacts in strange way to self-answered questions sometimes. I don't really understand why. We have some advice on that here: meta.stackoverflow.com/questions/314165/… and meta.stackoverflow.com/a/347875/366904 Aug 4, 2017 at 13:22
  • 3
    In retrospect I am not happy with with (B) "give credit to the contributors of the information pulled from Documentation", there is an implication that I was posting someone else's documentation as mine, that was unfair and impunes my reputation. It is assumed that anything I post is mine, I should not need to self attribute: "This is mine".
    – zaph
    Aug 4, 2017 at 13:52
  • 2
    @CodyGray: My impression from the earliest days is that some people consider self-answering to be cheating since: a) it potentially earns reputation from both the question and the answer and b) the question is obviously not sincere since the asker knew the answer. In addition, too many self-answered questions are poorly asked. It's much harder than most people think it will be. Aug 4, 2017 at 16:21
  • @JonEricson I'm confused, on the main entry which you authored, in an answer to a question on "self answered questions" you wrote: "That sounds like a great idea! Having written my share of self-answered questions, my advice is to focus on the question and be sure there can be alternate answers." with 40+ likes and it that prompted me to try it.
    – zaph
    Aug 4, 2017 at 18:13
  • As for earning reputation, that is not the point, the point is not to lose the documentation. I know that in my case I put more work into them that I usually do answering a question.
    – zaph
    Aug 4, 2017 at 18:16
  • @zaph: I'm sorry for the confusion. I didn't put a lot of thought into that comment to warn of many possible pitfalls. I've added an answer that, I hope, will be of more help for you and others wanting to preserve their content. Aug 4, 2017 at 18:22
  • @JonEricson Thanks for the clarification, I will check the new answer.
    – zaph
    Aug 4, 2017 at 18:27
10

I haven't had a chance to speak with the rest of the team yet, but this taps into one of the things that our research turned up: technical writers use templates. I don't mean the (slightly insulting) function comment blocks. Instead they use templates from tools such as MadCap Flare, Confluence and even Microsoft Word. While Documentation has a template, it's very rigid. Judging from what we learned, Docs 2.0 would need simple and flexible ways to create templates for different types of documentation.

So what does this have to do with your question? Well, in my experience, the trick with self-answering questions is writing a question that other people can reasonably add answers to. It requires not only a technical understanding, but an understanding of what is and is not welcome by the community. Misjudging the nuances can result in your carefully crafted answer getting downvoted and deleted along with the question. It's certainly not something we can expect even experienced users to pull off with regularity.

The shame of it is honest self-answered questions all have the same form:

I discovered something obscure and useful to know in [tag]. I think other people ought to know it too. Rather than post this on a blog or something where nobody will ever see it and it can't be properly vetted, I'm posting it as an answer to this "question". If you have an alternate method, please add your "answer" too!

Instead, we ask people to write these questions Jeopardy-style without a lot of guidance to how to do that. It occurs to me that a template could really help people ask better questions they plan to answer.

So moving Examples from Documentation could be a good opportunity to try out an ad hoc template created and refined here on meta. Without putting too much thought into it, how about:

What are some examples of {task or feature you are trying to document}?

{Briefly describe the task or feature.}

{If there is documentation elsewhere (particularly in the official documentation), explain why it's not sufficient.}

{Describe any constraints that might apply. For instance, maybe you don't have root access or you can't upgrade to the latest version. You don't need to justify these restrictions, but doing so might avoid frivolous comments.}

Like I said, this is just a rough sketch of what might help askers produce good questions. Doing this right would probably require asking another question on meta. Really doing this right would require building templates into the ask page so that the prompts are right there while you post.

For answers, I'd suggest posting just one Example per question. Topics are supposed to be (and actually were) very broad, but many Examples are about the right scope for Stack Overflow answers. I'd recommend editing down longer, more meandering Examples, however.

Also, to preserve attribution, get the list of example contributors:

Example contributors link

Then add attribution at the end of the answer:

Originally posted on Documentation with contributions from: {insert profile links}.

It would probably be nicer to include display names too. Obviously, you don't need to include this line if you were the only contributor.

5
  • 4
    Docs 2.0? Please elaborate, as if there are plans for a 2.0, then we may more easily migrate from 1.0 to 2.0 than from 1.0 to Q/A to 2.0. [edit: from a comment from Servy, Doc 2.0 would be a site with distinct reputation system?]
    – Cœur
    Aug 6, 2017 at 11:38
  • I don't think this idea is the correct approach to moving over examples. This answer is sort of encouraging dumping all examples from a topic in a single QA answer. That would make a question extremely broad and not really searchable. It also wouldn't fit with the rest of the QA site. When I originally posted my idea, I was thinking more along the lines that each example worthy of keeping should be reformatted into it's own specific "How To" question.
    – Tot Zam
    Aug 7, 2017 at 16:40
  • @Cœur: There are no plans for Docs 2.0. We do have some sketches based on extensive research. But it'll be a long wait before anything can be moved. My guess is that many examples will be long out of date at that time. Aug 7, 2017 at 16:46
  • 1
    @TotZam: I agree. I've bolded the bit that got buried which addresses your point. Aug 7, 2017 at 16:48
  • @JonEricson Yes, I missed that paragraph. This suggestions sounds better now.
    – Tot Zam
    Aug 7, 2017 at 16:55

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