182

We are no longer accepting contributions.

As previously announced, Stack Overflow Documentation is now in read-only mode in preparation for its sunset permanent removal from the site. Before we move on, I want to update you all on some responses to your feedback.

I’m enormously encouraged by the thoughtful comments and answers to the announcement. The “We-told-you-so’s” were well earned and the expressions of disappointment were respectful. Writing that announcement was the most challenging thing I’ve done on this job. It’s a mark of this community’s maturity that reading the replies was enjoyable rather than stressful. Thank you all.

Content

Nothing has changed in our plans so far. We still plan to release a JSON archive, but the exact structure and what will be included hasn’t been nailed down. We’ll let you know when we have more details.

Reputation

Nothing has changed about our goals with reputation, but we’ve been working out the implementation details. Our initial thought was that a single Documentation reputation entry would be most efficient. But Nick Craver reminded us that we need to be able to do reputation recalculations from time to time. Doing reputation right means we’ll need to keep Documentation reputation events in an archive table so that we can account for things like people hitting their rep cap for the day.

Badges

Forget our original plan. We’re planning on implementing Panda’s suggestion:

Documentation Badges (retired)

We might tweak the name and description of the final badge, but the idea is to preserve the two existing participation badges and award a third one.

Links

We were overwhelmed with the voting on the generous offer to help clean up the links. I was reluctant to ask this of the community since it violated the fix-what-you-break principle. But it really will be best to treat this like a tag cleanup. Our primary responsibility will be to provide you all with a list of links to posts that need fixing. (More on that soon.) But there’s still one more issue we need to consider first:

Attribution

Nicol Bolas pointed out there’s a potential difficulty using content from Documentation: How can we provide attribution once the content is removed from the site? At a minimum, linking to the data dump when content from Docs is copied into Q&A provides a path to identifying the authors which satisfies the attribution requirements of the license. However, we feel this approach isn’t the best experience and I’m guessing you will agree. Since the earliest days of Stack Overflow, we’ve valued giving credit directly to the individuals who created the work. Ideally, author’s names (and links to their profiles) would be included right next the content. To honor this spirit of attribution, please consider adding links to the primary authors of the content, when possible.

We realize that in the case of Docs, there are quite a few examples that have many authors. The Java Creating and Initializing Arrays example had 80 active contributors and 163 total editors. Listing each name would make a post unwieldy. But then again, that example is probably too large to be part of a good answer. It’s entirely possible we’d just want to remove the link entirely for most examples touched by many contributors.

In summary, here’s what we’d like to suggest when editing Q&A posts with links to Docs:

  1. If an example link doesn’t add much to the post, feel free to just remove the link.

  2. If the author wrote both the Documentation content and the post (especially if you are the author), edit in the relevant parts of the content and mention in the revision history that the additions came from Documentation. Since the author already has their user card under the post, there’s no need for more attribution in this particular case.

  3. If the content has multiple contributors, consider linking to the top few major contributors.

  4. As a ground rule—always link to the Documentation archive so that attribution is traceable if copying content.

We'll publish a link to the data dump and a list of posts that will need attention as soon as we have them ready.

16
  • Will you be able to link to the part of the dump you copied from or will it be a link to the entire dump? Aug 15, 2017 at 19:30
  • 2
    @NathanOliver: We're still working out how the archive will work, but it's looking like you'll have to link to the entire data dump. :-( Aug 15, 2017 at 19:32
  • 2
    Bummer. Well, if you have to you have to. As long as there is a title or id or something easily identifiable it shouldn't be to hard to do a find on it. Aug 15, 2017 at 19:35
  • 8
    will web.archive.org links to docs still work after you remove the docs from your servers? please don't do anything that would break it, if possible.
    – Will Ness
    Aug 15, 2017 at 20:16
  • 7
    @WillNess: We don't have any plans to mess with the Wayback Machine. On the contrary, I've been looking to submit pages that are currently missing there. Aug 15, 2017 at 20:24
  • 3
    @JonEricson that's good to hear. maybe you could just push them all somehow programmatically (not just the missing - even those that are present may be severely outdated). Doing it by hand sucks, there's big delays and trying to save more than a few at once usually results in "no available servers to handle request" error. one thing though. it seems some JS is served from your servers for each page as well. If you stop doing that, it might prevent pages from loading? (I don't understand much about these things).
    – Will Ness
    Aug 15, 2017 at 20:34
  • 2
    @WillNess: Yes, scripting that rather than doing it by hand is the way to go. I'm trying out the Ruby I learned participating on Docs, but it doesn't have to be me. Aug 15, 2017 at 20:38
  • (contd.) there's also a problem with TOC pages which get chopped into several pages, when there are many topics. each such page gets its own URL and must be saved separately. One long page with all the topics in one screen would be nice to have. without the TOC pages the topics will be inaccessible.
    – Will Ness
    Aug 15, 2017 at 20:40
  • 23
    I'd just like to express my thanks to the Docs team for implementing my suggestion regarding Docs badges, really glad to hear that!
    – Panda
    Aug 16, 2017 at 2:48
  • @Panda Thank you for suggesting that (I have a reason for a great appreciation). Aug 16, 2017 at 13:29
  • 3
    Why not a link to the wayback machine as attribution? At a first step, you could even auto converts all links to documentation into wayback machine links before putting the posts in the spacal review queue. Aug 18, 2017 at 14:04
  • 2
    Why not use Community to replace Docs links with Wayback Machine links? Aug 19, 2017 at 15:05
  • @NathanOliver if it is a JSON, can't we just link to the dump and then provide the index that you need to get to the relevant part (object["ID here"]["other ID here"])?
    – NH.
    Aug 28, 2017 at 21:30
  • 2
    Why do you remove the content? An archive accessible via browser would be much better. For me, a JSON archive is useless.
    – Matt
    Aug 31, 2017 at 13:26
  • I have a question regarding consider linking to the top few major contributors. How do we determine who the top contibutors are? Consider this example, which people should we explicitly cite? Should we just go by date and take to top few since they were the first and thus laid the foundation? Sep 8, 2017 at 19:17

5 Answers 5

57

For the "Documentation" badge, your current text reads:

Earned at least 1 documentation badge other than Educated during the beta.

I think this text should make sure that the reader understands that the "documentation badge" part is referring to badges that don't exist anymore. That is, not "Documentation Pioneer" and "Documentation Beta".

2
  • 39
    Correct. Badge descriptions are always difficult, but we still have some time to work that out. My current thought is that "meaningfully contributed" or some such will be better than trying to explain which badges the person earned. Basically, we're using badges as a proxy for doing something more than just reading the tour. Aug 15, 2017 at 20:21
  • 7
    @JonEricson "active engagement" may be a good wording. Aug 18, 2017 at 14:05
18

You should consider removing the "Insert Link to Documentation" tab from the answer editor's link modal. Also, remove the link to "Documentation" from the top level nav.

Insert Link Dialog

Top level nav

3
  • 6
    I removed the tab in the link insert dialog. We're keeping the top nav button around for a while still, though, as folks may be interested in grabbing their content. I imagine it'll be going away in the next couple of weeks.
    – Adam Lear StaffMod
    Aug 18, 2017 at 18:35
  • 3
    @AdamLear What about hiding the Documentation tab from users who are not logged in?
    – Adam
    Aug 18, 2017 at 22:49
  • That's adding a special case for the sake of doing so, IMO.
    – Adam Lear StaffMod
    Aug 18, 2017 at 22:50
13

One more item for the 'to do' list. When editing a tag wiki entry, there's a request for a short name for use in Documentation.

enter image description here

The 'friendly name' isn't really needed any longer — or, at least, it isn't needed for Documentation.

2
  • It's on the list for removal, or at least a copy change. We might keep it around for other uses... Shog9 had some ideas for it, although nothing super concrete at this point.
    – Adam Lear StaffMod
    Aug 23, 2017 at 3:49
8

We'll publish a link to the data dump and a list of posts that will need attention as soon as we have them ready.

I don't know how much effort is worth investing in that, but make sure the list is searchable at least by author and tags. It doesn't need to be anything fancy, even something as simple as a CSV would work too, but don't provide just a flat list of links.

  • I'm willing to update my answers but I need the author field to quickly find all my posts that contain a documentation link and need attention
  • Then I assume most people who want to help would want to focus on their area of expertise first, and that's why the tags are needed as well
3
  • 7
    Why not use Community to replace Docs links with Wayback Machine links? Aug 19, 2017 at 15:06
  • 2
    SO answers shouldn't depend on external sites, though. The Wayback Machine is out of SO's control
    – Cerbrus
    Aug 29, 2017 at 7:51
  • @Cerbrus Right, but if SO is not keeping the Documentation links up, using the Wayback Machine is a suitable alternative. Sep 4, 2017 at 3:56
3

Remove the documentation privilege: https://stackoverflow.com/help/privileges/docs-voting

1
  • Aye, privileges (and the help center articles for Docs in general) are on the list for removal.
    – Adam Lear StaffMod
    Sep 8, 2017 at 4:50

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