1286

Sunset in the west

We will stop accepting contributions to Documentation on August 8 2017

On behalf of everyone who worked on Documentation, I want to thank all 15,451 users who contributed. We particularly want to acknowledge the 294 people who tested the private beta and the 2,361 who pounded on the public beta in its first month. Your efforts taught us so much about how collaborative editing works and how it fails. We also appreciate the dozens of people we interviewed over the past year. These were eye-opening conversations and immeasurably useful for improving the product. (I also enjoyed being able to get to know some of you over a hangout.) Our top concern at this point is to honor the trust you put in us. We hope you will be willing to participate in future betas, but even if not, we remain in your debt for your efforts with this one.

While it might not seem obvious, we are deeply grateful for both the positive and negative feedback we’ve received on meta. Many people told us this project was too ambitious and that we hadn’t considered some of the deep challenges inherent in what we were attempting. You were, of course, correct. Most likely I wouldn’t be making this announcement if we’d aimed our sights a bit lower. On the other hand, we wouldn’t have learned nearly as much.

Why was this decision made and why now?

We were really excited about this project and I'm disappointed that this is the choice we had to make, but it's the right decision and something that we always knew was a possible outcome. Last December I wrote a series of contingency plans in case we needed to shut Documentation down. Some of the options I considered made it into the plan described after the linebreak. But the entirety of one plan was “Just succeed instead.” That is no longer a possibility.

We still think Stack Overflow Documentation is a good idea. Kevin Montrose’s initial research has mostly been proven correct. Not only did our own survey show that developers rely on official documentation to learn, GitHub's Open Source Survey showed "incomplete or confusing documentation" to be the top pain point. Unfortunately, we can't afford to work on the problem at the moment. While we have an exceptional team of engineers, there just aren't enough of them to support all the projects Stack Overflow is working on.

In order to hire more people, we need to make more money. That might mean helping more developers find a great job or selling more ads or signing up more businesses to use Enterprise. In the future, it might mean selling Channels to new teams. The business pitch for Documentation was that it'd bring in new users who might be in the market for a job. If the feature were particularly successful, it would create new opportunities to sell advertisements. At the end of 2016, we established a metric to aim for: substantially increase the number of Documentation users.

By May, it was clear we weren't on the right path. New users weren't coming to Documentation. So we went back to the drawing board and started another round of user interviews focused on Transact SQL. We brought on a user experience researcher to help us interview technical writers. The results were encouraging in the sense that we know a lot more about what makes for great documentation and how we might support that effort. But it was also clear fixing Documentation would require a significantly larger team.

In addition, it’ll be a very long time before that work will pay off in terms of bringing new users to Stack Overflow. Our interviews showed even very experienced users of T-SQL felt inadequate to contribute documentation. Users with less Stack Overflow experience tended to be intimidated by the prospect of making even trivial edits. So the programmers most likely to become Documentation contributors were already heavily engaged in using Stack Overflow.

Finally, our research showed that while a lot of developers were dissatisfied, the current state of programming documentation is not universally broken the way Q&A was when Stack Overflow started. In particular, we heard over and over that Stack Overflow has become de facto documentation for many technologies. As many of you pointed out, Stack Overflow is already good enough at providing documentation of obscure features. Even when considering just the company's mission of helping programmers “learn, share their knowledge and build their careers”, Documentation isn’t the most efficient use of resources.

Even though this outcome has been a disappointment, most of us agree it was the right decision. If so, I hope we'll be able to revisit documentation in the coming years. However, as the ancient Hebrew proverb says, “Hope deferred makes the heart sick; but desire fulfilled is a tree of life.” This was a mature and responsible decision, but that doesn’t cure the heartsickness.

Will anything come out of this experiment?

Yes! As Shog pointed out, we've already learned quite a bit from doing things we couldn’t do otherwise. It's too soon to know exactly what we'll be able to port over to Q&A, but I'm excited about the possibilities of CommonMark, technology versions support, shared drafts, better collaborative editing and dated links to previous revisions. Before we leave Documentation, the team will compile what we learned so that we can draw from the knowledge in the future. And, as I will describe below, we’ll publish all of the content generated in Documentation.

More importantly, we've changed our approach to product development across the company. When we started Documentation, our discovery phase was largely done without interviewing typical users. Up to that point, most new features on Stack Exchange were developed with input from Meta or entirely internally. If a feature got used, we'd refine it or just declare victory. If a feature wasn't used, we typically removed it only if was actively causing harm. However, after our experience with the Documentation Beta, we've learned to focus more of our efforts on pre-development research.

For instance, the Documentation team already decided the outline of the feature before coming to meta with the initial announcement. By contrast, our newly formed Developer Affinity & Growth team asked for help setting priorities based on themes and user stories. Documentation’s private beta fleshed out most of the functionality. By contrast, the new mentoring proposal is a minimal viable product that is arguably too minimal. We’re certain to have failed projects in the future, but we’re working to fail a lot earlier in the process.


How will the feature be phased out?

After August 8, 2017 at 1700 UTC, we’ll disable proposed changes and wait for pending changes to be reviewed. Once the review queue is cleared, it'll be removed from the review menu and page. We’re still working out the other details, which I will try to explain below. For some of this, we need your feedback in order to do right by the community. This probably won’t be the last time we discontinue a beta feature and now is a good time to set a healthy precedent.

What happens to content?

As with all content contributed by the community, you own it and we merely have a license. Since we want to make it as easy as possible for you to recover your work, we'll be listening for suggestions in the answers below. At a minimum, we'll provide a JSON archive similar to what we already provide for live content. Let us know what you'd prefer.

What happens to reputation?

Reputation earned on Documentation will be retained—probably in the form of a one-time grant shortly after Documentation ends. We have a longstanding policy of preserving reputation even after worthwhile content is removed. While not all of the content in Documentation is exceptional, that's mostly on us and not on users, who acted in good faith. We looked to see how many people earned privileges on Stack Overflow without participating much or at all in Q&A. As it turns out, we mostly failed to attract new users to the site with Documentation, so revoking reputation would only affect a thousand or so users in terms of privileges compared to nearly 20k people who would lose reputation.

What happens to badges?

We also have a longstanding policy against revoking badges. But we've never had a badge set for a discontinued beta feature either. While we could just retire them, it seems confusing to show expired Documentation features on the list of badges. In addition, we'd lose a lot of good names for potential future badges. As a compromise, anyone who earned a Documentation badge other than Educated (for reading the tour) will be issued a newly minted silver Documentation Beta badge. Does this seem fair?

What about links to Documentation?

Unfortunately, discontinuing Documentation will be breaking the internet just a bit. As of this writing, there are 3382 links from Q&A posts to an Example and 2199 links to some other Documentation page (usually an entire Topic). Ideally, we’d keep those links live, but because of the nature of the content, that would leave a lot of information that could easily become outdated without a mechanism to fix it. The next best thing would be a plan to automate the movement of content into the post itself. That might work for many examples, but probably not for entire topics.

One suggested approach: we automatically generate suggested edits from the Community user and submit them incrementally as there is space in the queue. For links to non-Examples, we think it will be sufficient to remove the sentence with the link. Many of these sentences start with phrases such as “You could read more about X at [Docs link]”.

Links to specific examples seem more likely to be integral to posts, so the team is looking at ways to bring them into answers in a new section. Doing this via suggested edits will allow the community to reject or improve automated edits. (And authors can always override the community if they prefer.) The key will be to find a workable template and make sure the suggested edits don’t waste too much community effort.

Until the suggested edit process is finished, Documentation pages will remain available on the site. After that, links will redirect to a landing page explaining what happened and where to get the data dump. There's not a whole lot more we can do for links external to the network, unfortunately. On the plus side, there probably aren’t that many anyway.

We’d like to hear what you think of this approach. It’s entirely possible there are better ideas we just haven’t considered. This plan is far from settled.

What about all the questions on Meta?

I’m going to be going through the ~1,500 unaddressed meta questions and either close or put a status tag on them. Our community produced many great conversations and suggestions, so I don’t plan to delete anything. I could probably slap on everything, but I’d rather take the opportunity to make sure we have the feedback incorporated in our retrospective.

What about . . . ?

The most important thing we're looking for in answers are feedback on the mechanics sunsetting, especially making the content available to contributors and repairing broken links. That said, if you have any additional questions or comments, feel free to post them as answers below. We also plan to write a retrospective on the blog and make this a topic of an upcoming Town Hall Chat. I’m planning a few posts for my personal blog as well. Documentation might be coming to an end, but we’re not close to done talking about it.

126
  • 245
    Amusing how this was announced at around the same time as the blog post on Flash.
    – BoltClock Mod
    Commented Aug 1, 2017 at 17:17
  • 17
    While we do preserve reputation we only do it when the content has been around for longer than 60 days and has a 3 score or more. You do lose edit suggestion rep if the post is deleted. Are you going to have the docs rep jive with that or is all rep being kept? Commented Aug 1, 2017 at 17:28
  • 22
    @NathanOliver We, in good faith, want to let users of Docs keep their earned rep. Few things about Docs makes it hard/unfair to do it any other way. With us not accepting any more contributions and sunsetting it, it does not give newer approved posts the 60 days window. We also do not have nearly enough activity on Docs to justify the votes criteria.
    – Vasudha Swaminathan StaffMod
    Commented Aug 1, 2017 at 17:40
  • 27
    @Servy: The argument here isn't that the content was useful, but that users acted in good faith. It's really the same concept as for Q&A posts deleted after they've been live several months. The difference is that the thing that changed was not community sentiment about the usefulness of the content, but the existence of the feature itself. (Also, not much point in arguing about reputation from examples without votes as they didn't earn much reputation at all. A rounding error in the grand scheme of things.)
    – Jon Ericson Staff
    Commented Aug 1, 2017 at 17:52
  • 50
    "[...] a newly minted silver Documentation Beta badge. Does this seem fair?" - How about a gold badge for users who were awarded with all Documentation badges? :p
    – honk
    Commented Aug 1, 2017 at 18:12
  • 41
    The silver badge sounds nice, but dang if it isn't replacing 3 silver badges and 8 bronze ones... as well as my first ever fully-achieved badge section. I like @honk's suggestion... a silver badge for those who participated and a gold badge for those who earned every single badge in the Docs section :-)
    – TylerH
    Commented Aug 1, 2017 at 18:36
  • 12
    @Zanon: It does. We kinda have a backlog of items in the Community Bulletin at the moment, however. The plan is to feature it after the election is over and announced. We're going to also have a banner on Docs pages explaining the situation soon.
    – Jon Ericson Staff
    Commented Aug 1, 2017 at 18:49
  • 87
    Ouch. This must have been difficult, but this is a courageous decision. My point for the retrospective: In the eagerness to encourage participation you've offered easy reputation, which tempted many users into editing and expanding popular 'examples' - this led to some terrible results. Reputation should be more difficult to get.
    – Kobi
    Commented Aug 1, 2017 at 19:57
  • 91
    Holy cow. Sorry the thing you were excited about didn't work out. But kudos for having perspective enough to let it go.
    – jscs
    Commented Aug 1, 2017 at 21:38
  • 27
    Why not create a gold, silver and bronze documentation-beta badge, and award each of them once each for each documentation badge you had? So if you had 2 silver and 5 bronze doco badges, you'd get 2 documentation-beta-silver and 5 documentation-beta-bronze badges. Solves every problem? Commented Aug 2, 2017 at 1:18
  • 13
    @ChristianDean: One note of caution: removing the link will also remove reputation in the event of a recalculation. You can always do it after the 8th when Docs reputation is locked.
    – Jon Ericson Staff
    Commented Aug 2, 2017 at 18:05
  • 69
    “While we have an exceptional team of engineers, there just aren't enough of them to support all the projects” – I don’t believe we can or should blame this on the developers. I believe they did a great job and don’t think just throwing more of them or “better” ones at Docs could have saved it. Docs’ original approach was already flawed, as the community attempted to point out repeatedly. This is not something that could be blamed on any of the developers working on it. – I’m sorry to see all the made effort into Docs go to waste, but I’m also glad that the correct decision was made now.
    – poke
    Commented Aug 3, 2017 at 7:03
  • 134
    It took me a while into the post to realise that "sunsetting" is pointless business speak for "cancelling" or "shutting down completely". I would have guessed it meant the beta was ending and it was rolling out into production, or something.
    – Pod
    Commented Aug 3, 2017 at 8:46
  • 18
    @poke: I agree. SImply throwing more developers at the problem would not have helped. Instead we threw more researchers at it. Our interviews with programmers who don't use Stack Overflow, technical writers and users heavily invested in Documentation helped us spec out a new design. Unfortunately, that new design did need more developers, designers and researchers to implement. I plan to share more of our findings in the next few weeks.
    – Jon Ericson Staff
    Commented Aug 3, 2017 at 16:19
  • 50
    I respect Stack Overflow a lot for this. Documentation was a well-meaning idea that always seemed slightly off to me because the goal of becoming a Stack Overflow-like presence for documentation would be in competition with, instead of a good complement to, a technology's official resources. In a world where companies, especially VC funded ones, are eager to move ahead with their own grand plans without considering whether they do any good or align with what their users want, this decision is a refreshing reminder that focus, listening and humility are good things.
    – Jesper
    Commented Aug 4, 2017 at 10:41

48 Answers 48

389

Instead of having Community do this why not organize the community to edit the links? We can treat it like a tag cleanup/burnination and get users with edit privileges to go through and edit them. This way we don't fill up the review queue and we can handle the cases where it is not trivial to edit the link out.

10
  • 22
    This seems like a great idea. Would you suggest that a new review queue gets generated temporarily for this? Or would it piggy back off of something else?
    – Frits
    Commented Aug 3, 2017 at 6:18
  • 30
    I agree, there are a lot of answers where simply removing the link will very much deteriorate the answer. Just compile a huge-ass list with all links (grouped by topic and maybe even doc example), and let the community have a go at this first.
    – poke
    Commented Aug 3, 2017 at 6:49
  • 2
    Base on number of views the answer with the link is getting Commented Aug 3, 2017 at 8:46
  • 2
    Agree with this Nathan, I'm sure we (as the community) could fairly quickly remove links that are not necessary and even re-point to more appropriate ones. There'll be a bunch of posts that are left at the end and we can decide what to do about them later. (e.g. adding some canonical QA on the main site)
    – DavidG
    Commented Aug 3, 2017 at 10:39
  • 4
    @Frits We could handle it with a meta post showing the status that we can edit and if we need to a chat room. Commented Aug 3, 2017 at 11:32
  • 4
    This is a fantastic idea. Like @poke said, just make a huge list and then release the hounds!
    – Clonkex
    Commented Aug 4, 2017 at 5:11
  • Here's the start of a list...currently waiting for it to run without a limit. data.stackexchange.com/stackoverflow/revision/709302/882839/…
    – Josiah
    Commented Aug 11, 2017 at 9:53
  • 2
    @Josiah This site search is unrestricted and has 4500 results. Might not be all of them but it is a good place to start Commented Aug 11, 2017 at 11:37
  • 8
    For all links from SO posts (main and meta) to any Doc entry, post a notice in the inbox of the SO post author. Let the owner of the link have first crack at fixing it. No review queue needed, no community effort involved, and the original author will know best how to "fix" the lost link.
    – Chindraba
    Commented Aug 14, 2017 at 4:59
  • The heading sounds like, accepting contributions will stop only on August 8th.
    – A user
    Commented Aug 15, 2017 at 14:19
342

A few of the documentation examples I wrote, I created because I previously had a hard time finding that particular information.

This is only a few examples that I'm talking about. Majority of my contributions were just part of testing out the site. I also am only referring to examples that I created and was the main contributor to.

Would there be anything wrong with turning these examples into self answered questions in the Q/A part of the site?

33
  • 128
    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.
    – Jon Ericson Staff
    Commented Aug 2, 2017 at 14:32
  • 5
    @JonEricson It seems silly, though, to include a link that very soon will not work.
    – Tot Zam
    Commented Aug 2, 2017 at 15:15
  • 36
    you might find this guidance useful: How to ask and self-answer a correct, high quality Q&A pair without attracting downvotes?
    – gnat
    Commented Aug 2, 2017 at 15:53
  • 5
    Also What subjects would be good for a self answered question?
    – jscs
    Commented Aug 2, 2017 at 23:49
  • 24
    @JonEricson so even better, why not convert all of documentation into community-wiki self-answered questions by Community? each example and remarks sections for teach topic automatically converted into their own Q&A entry with some auto-generated title. this will preserve the content a.o.t. destroying it (and letting users on data-dump content chase is just the same as destroying it).
    – Will Ness
    Commented Aug 3, 2017 at 12:22
  • 3
    (continuing) good entries will with time get up-voted more, bad ones will get downvoted, flagged into low-quality queue and deleted, with time. valuable content will be preserved, bad one deleted. a win-win.
    – Will Ness
    Commented Aug 3, 2017 at 12:48
  • 11
    @WillNess A lot (if not majority) of the current documentation already exists in QA. Just moving everything over will create many duplicate posts. I think the only way to do this is by users manually moving over the few item they feel don't yet exist. And this would be only after they do a thorough search to make sure the question really doesn't exist yet.
    – Tot Zam
    Commented Aug 3, 2017 at 13:42
  • 2
    @Servy what you're saying is, lot of it isn't that good, some is very good, and we will through away the good with the bad! and I'm saying, I don't think that's OK.
    – Will Ness
    Commented Aug 3, 2017 at 14:17
  • 6
    @WillNess I didn't say that at all. I said we shouldn't copy over all of it, because the vast majority of it is bad. Feel free to copy over the few bits that are actually useful. And of course it's never going away. The archive will always be available, if you later find out that there was something useful there that you want to re-host elsewhere.
    – Servy
    Commented Aug 3, 2017 at 14:19
  • 5
    @Servy it will be available as a JSON/XML/whatevs data dump. Not really that useful to me - and that's a colossal understatement. An answer here asking for a frozen Docs site is heavily downvoted right now. (? or was, when I last read it few minutes ago...)
    – Will Ness
    Commented Aug 3, 2017 at 14:24
  • 3
    @Servy and I already told you that it is not useful to me, and not having an HTML accessible means heaving a content completely removed - for me. this is what I am telling to you.
    – Will Ness
    Commented Aug 3, 2017 at 14:35
  • 3
    @Servy no, what I have right now, is of great value to me. Next, if accessing something right now costs me 0 effort, and will cost 100,000 on my relative scale of cost of effort, why do you think you have any right to tell me this or that. You don't know my relative effort scale. What's easy enough for you, might be very hard for me. But as I said, you don't want to hear me, and it's fine. just stop telling me I'm an idiot. it's like I have a ferrari, you take it away, give me a donkey instead, and laugh at me complaining, because you're a master donkey-rider. I'm not.
    – Will Ness
    Commented Aug 3, 2017 at 14:53
  • 5
    @WillNess Docs is flooded with plagiarized content, duplicated content, incorrect content, poorly written content, etc. Most of what's there isn't even original content to begin with, and is already accessible elsewhere. Of what's left, most is just worse versions of content already accessible elsewhere. Again, this is why it's being removed in the first place, it's full of bad and duplicate content, not original quality content. If you're actually using it (for some unknown reason) then you can just do a search and find the same content somewhere else.
    – Servy
    Commented Aug 3, 2017 at 14:59
  • 5
    @Jon Ericson I added a self answered question on SO with the contents of documentation I had created and requested feedback. Within minutes it was down-voted, received several more down votes and close votes. Then it was moved to Meta, received morre downvotes on both the question and answers and eventually closed and locked by Cody Gray♦. See the question here.
    – zaph
    Commented Aug 4, 2017 at 12:25
  • 6
    @zaph The morale of the story of course being that if you're going to post a new question on SO you need to ensure that your question is a quality question, that meets all of SO's standards for a good question, and that the answers also need to be good answers, per SO's standards for an answer. Just copy-pasting over something from Documentation that wasn't written to be a good SO question or a good SO answer isn't going to go over well.
    – Servy
    Commented Aug 4, 2017 at 18:02
119

Regarding Documentation badges, I really hope that the Documentation Beta and the Documentation Pioneer badges can be retained and be separated from the "newly minted silver Documentation Beta badge".

Both badges are awarded to recognise users' contributions in the different phases of Docs, i.e.:

  • Documentation Beta

    • For participating in the Docs.SE private beta
  • Documentation Pioneer

    • For participating in the 1st month of the Stack Overflow public beta
    • awarded from July 21, 2016 till August 20, 2016

These 2 badges are also awarded on a limited time basis and they can't be obtained now. So, it wouldn't be really fair to those who had obtained them. These users were one of the first users to help to shape and test out Documentation and I think retaining these badges will show some recognition to the early birds.

In addition, both badges have names unique to Documentation, so they can't be reused in the future.

As for the newly "newly minted silver Documentation Beta badge", I think another badge, e.g. "Documentation" (the name's just a suggestion) can be introduced and it would recognise users who participated in the "graduated" version of Documentation.

Image

  • a rough idea of how this'll look like

  • my other ideas for the name of the "newly minted silver Documentation Beta badge" are "Documentation Tester", "Documentation User" and "Docs Contributor", feel free to suggest more in the comments if you have any good ideas :)

In this way, there will be 3 badges, each awarded to users who participated in the different phases of Documentation, namely the private beta, the 1st month of the public beta and the graduated Docs (current phase).

6
  • 27
    I completely agree. I actually went out of my way to make contributions in the first month after the closed beta because of these badges
    – Zags
    Commented Aug 3, 2017 at 12:43
  • 11
    Documentation Pilgrim? Documentation Settler? Documentation Homesteader? lol
    – jpmc26
    Commented Aug 5, 2017 at 2:25
  • 13
    @jpmc26 On a similar Oregon trail-type of theme, Documentation You Have Died Of Dysentery, or Dysinterest, perhaps?
    – Ken Y-N
    Commented Aug 7, 2017 at 2:07
  • 5
    SE Staff seems to follow your suggestion: Documentation is read-only. What’s next?
    – Ferrybig
    Commented Aug 15, 2017 at 20:03
  • 2
    @Ferrybig Yup, just saw it, thanks! I'm didn't expect my suggestion to be taken, but I'm really glad :)
    – Panda
    Commented Aug 15, 2017 at 22:01
  • What about badges for those that contributed on the review Queues for documentation?
    – DarkCygnus
    Commented Aug 25, 2017 at 18:20
80

I'm not sure if automated suggested edits are a good idea, unless you're sure that most of these edits will be of good quality. Wouldn't want robo-reviewers to blindly approve these instead of improving them where necessary.

3
  • 13
    Might put the suggested edit queue back to 3 approves needed when this path is chosen ...
    – rene
    Commented Aug 1, 2017 at 17:32
  • 1
    Also create some submitted-by-Community audits... Commented Aug 1, 2017 at 17:34
  • 80
    If enough of Community's automated suggested errors get rejected by reviewers, will Community be given an edit ban? Commented Aug 1, 2017 at 19:12
70

Suggestion: export the Documentation dataset to GitHub

I read some of the downvoted comments about snapshotting the content, and noted how unused Stack Exchange sites are completely shut down, not archived. I can definitely agree with the idea of exporting/archiving the Documentation data via Stack Exchange's periodic data dumps, but that kind of locks it away.

GitHub could provide the perfect environment to foster continued development. The most straightforward way I could see this working is to create a purpose-specific organization for the task, and then export all content in either ReStructuredText or Markdown format.

Exactly how to structure the export makes for a good question though. Careful use of directory structure is obvious. I'm wondering whether to lump everything into one gigantic repository, or break things up. It may actually be a good idea to fragment everything, because cloning tiny repositories imposes less cost than cloning a gigantic one.

Moving everything to GitHub leverages existing collective knowledge, momentum and infrastructure. IMO it's the best place to dump everything and provides the best chance that it will survive and continue to grow.

The thing is, the Documentation experiment produced a bunch of data that is current right now. This shutdown is going to put a pretty big dent in the maintenance momentum that has been created. It would be a good idea to export the data in a way that minimizes that dent as much as possible, to create the best chances that the documentation will continue to be updated.

One technical note. Because GitHub is based on Git, that provides the perfect solution to version management - you can simply transcode the Stack Exchange document history into the Git repository history, perhaps even using edit reasons as commit messages. GitHub have been working with Git for quite some time, too, so this should be quite easy.

10
  • 6
    I like some aspects of this idea, but I don't think it makes sense to dump all of Documentation on Github. It might make sense for some topics where the Documentation trove really adds significant value over existing documentation; but even then, Github is merely a back end, and you really need a proper front end web site, Anyway, that can happen as soon as someone steps up and volunteers to code and host the thing, and is independent of Stack Overflow, after they fulfill the promise to release the data dump.
    – tripleee
    Commented Aug 3, 2017 at 11:45
  • 3
    @tripleee True, but having a versioned backend that people can easily fork could help everyone to work on it. Also, markdown shows on github as a website and getting an offline copy would be really easy with git pull. All in all this is not so daft. See my answer for a frontend idea, which doesn't exclude github as a backend at all. Submodules could be one way of letting people decide on which parts they would like to work/download/fork.
    – user1115652
    Commented Aug 3, 2017 at 12:38
  • Do you want this as a read-only dump there, or for people to work on it? In the latter case you need at least some maintainer. Commented Aug 3, 2017 at 20:48
  • @tripleee: You're right, GitHub is just a backend. I was thinking that the export would live in one or more semantically presented repository(s), with (a) matching *.github.io repository(s) to allow for easy presentation of the data. GitHub has allow-origin=* on their raw links, so you could serve some JS to pull in and format the data that way. A fair bit of work, but the result would be a fully self-contained platform (view via Pages site, edit via Pull Request) with zero hosting costs.
    – i336_
    Commented Aug 4, 2017 at 2:18
  • @PaŭloEbermann: This is an excellent point. Perhaps Stack Overflow could invite all Documentation moderators to the new organization. That would be one way to semantically transfer the ownership. SO would need to get a GitHub account from each moderator though.
    – i336_
    Commented Aug 4, 2017 at 2:19
  • @nus: I just checked devdocs out right now and I REALLY like it, thanks for the TIL! I would completely agree that periodic dumps (even near-realtime dumps) should be pushed to here. In the (hopeful) case that this GitHub idea eventuates, I would recommend pestering the new GitHub maintainers so they integrate this into the workflow from the start - figuring out how to make this work would take some thought, considering that devdocs already pulls from other canonical sources for information that Documentation would be covering. (Naming is tricky too - "CSS - Documentation" wouldn't work, etc.)
    – i336_
    Commented Aug 4, 2017 at 2:28
  • Dare I suggest a front end, something like Read the Docs, displayed on GitHub pages? Moving to such a system from the current data may require quite some work and tooling but the exercism project provides a good example of how they have managed to do something similar with managing and building programming examples over different topics (languages)
    – Toby
    Commented Aug 4, 2017 at 9:23
  • 2
    Meh. Someone else can do this with whatever snapshot the SO team provides.
    – Warren P
    Commented Aug 10, 2017 at 21:38
  • This would be helpful for moving the documentation to the actual products where it belongs.
    – endolith
    Commented Aug 30, 2017 at 18:40
  • This is a great idea! It would also keep content available, so any links to docs could just be redirected to the respective *.github.io repository page... Commented Sep 19, 2017 at 6:42
53

I am glad that you guys decided to take it out of Stack Overflow and was expecting this to happen some day.

Just a suggestion here to Stack Exchange team, if we stick to the current way, I am sure that users will start losing interest soon.

The reason I was asking to remove the rep is to get users who truly want to maintain a set of documentation without expecting any rewards. That's when we start getting legitimate people who really care. Throwing free rep is like compromising quality for quantity.


What I learnt from this?

  • Bad move to get new users, especially throwing free points, which leads to poor quality content and an overhead for high rep users to review

  • Hardly any community feedback was considered.

  • Not enough motivation or reason to edit docs.


I am happy that this is getting reverted. But I would like to appreciate the efforts put by the product managers, developers and users who were taking active part in the documentation and providing valuable feedback.

43

Collaborate with the Wikibooks community.

It would be nice to make it easy to import the content of SO Documentation on Wikibooks. Many wikibooks are concerned with programming language and the licence are compatible.

4
  • 4
    Agreed, it would be great to import everything as one giant Wikibooks book (just many subpages). Assuming the content respected copyright (e.g. by including only CC-BY and CC-BY-SA text and images), that is. Then pages can be easily moved or split into other Wikibooks books (many are probably overlapping with existing ones).
    – Nemo
    Commented Aug 4, 2017 at 9:58
  • 6
    I don't think SO docs would make an interesting book. It covers lots of a disperse set of languages/libraries and the content is unstructured.
    – aioobe
    Commented Aug 4, 2017 at 15:58
  • 8
    It could be several Wikibooks, not just one. Commented Aug 4, 2017 at 18:31
  • of course, this should be included in relevant existing wikibooks such as R programming for example.
    – PAC
    Commented Aug 16, 2017 at 9:34
38

The preservation of the reputation, as controversial as it may be, should be highly visible to us. In the past, when reputation has changed with Documentation, it's happened "suddenly", and those kinds of surprises should keenly be avoided moving away from the platform. This helps us Meta-hounds who want to explain what's going on, but can't due to a lack of information as to what actually happened.

Speaking of reputation, I didn't see this acutely clarified, but if someone has historical links to these pages, what's stopping them from upvoting them? Will they be locked so that users don't gain rep from a now discontinued part of the site?

6
  • 2
    Considering much of the question is talking about dealing with the consequences of the fact that the documentation content is being deleted and won't be hosted on the site anymore, I'd say it rather effectively renders the second paragraph moot. No, they're not being locked; they're being deleted (hard deleted, not soft deleted).
    – Servy
    Commented Aug 1, 2017 at 17:48
  • 12
    We'll be taking a snapshot of reputation shortly after we stop accepting contributions. The current plan is to award all Documentation reputation as a single grant. More details to come.
    – Jon Ericson Staff
    Commented Aug 1, 2017 at 17:48
  • 3
    @Servy: They had explicitly called out reputation as a thing they were going to address, and Jon's latest comment only reinforces that. Better to know than to assume in some cases...
    – Makoto
    Commented Aug 1, 2017 at 17:49
  • 9
    There's a specific section on what happens to the content, saying it's being deleted, there's a huge section on dealing with the fact that incoming links will be dead which wouldn't be a think if they weren't being deleted, and then also the reputation and badges sections both indicate that the content is being deleted. It was already called out, there's no assumptions needed here, the question was explicit.
    – Servy
    Commented Aug 1, 2017 at 17:51
  • 2
    The preservation of the reputation should be a primary goal. Users spent a lot of time on writing and editing documentation and you have to preserve all the rep. Commented Aug 3, 2017 at 6:56
  • I think a pinned Meta post when it happens (plus good display on the reputation page) should be sufficient.
    – jpmc26
    Commented Aug 5, 2017 at 2:27
34

I wanted to like documentation and did not like it and am happy to see it sunset. I am hopeful that a different way of searching/finding information on using APIs may be in the future, a venture worthy of Stack Overflow and its amazing community.

The fact that Documentation was shut down is a good sign to me for the long term health of the core Stack Overflow website/system, which I remain totally convinced of. It is a 100% fantastic thing that you tried, and if you "failed" (I don't think sunsetting this beta counts as failed), then it was worth the failure.

I think a discussion on why some users might not have wanted to use the Documentation feature as it stood, is worthwhile, and agree with the OP above who stated "we'll be talking about this for a while". I would like to suggest a blog post "post mortem" on this whole experience, with things you learned.

I would like to know "what we learned" with this whole thing.

1
  • I can learn a lot from here. Hope your successes... Thank you.
    – Crown716
    Commented Nov 9, 2021 at 9:05
31

We told you so?

Looking back at the "answers" to the original meta post is pretty revealing. Out of the top ten or so responses, there is a lot of hesitation, some outright hostility, and a little bit of guarded optimism with conditions attached.

Documentation always felt like something that SO really really wanted to do, and the community was lukewarm about at best.

I'm sorry so much effort has been spent on something that ultimately didn't deliver (haven't we all been there!) Better luck next time, I guess.

4
  • 7
    With hindsight it's of course easy to say "we told you so". ;) Commented Aug 13, 2017 at 11:55
  • 4
    I'd accept that criticism if the general response was positive, and I was drawing attention to a minority of naysayers. But the general response was negative, so ... Commented Aug 14, 2017 at 1:20
  • 6
    My initial response was negative too. But still the problem with hindsight is that you only pick the convenient cases. It's perfectly well possible for a majority of naysayer to condemn something and it nevertheless turning out to be a big success. Only if then you also post "Sorry, we were all wrong, please forgive us." only then "we told you so" posts in the opposite case make sense. Otherwise, with hindsight we are all so much wiser. We all know how it's guaranteed to not work now. Maybe it would have worked if approached only slightly differently and then your answer would be off again. Commented Aug 14, 2017 at 6:19
  • This reminds me of Captain Hindsight. Every (community) project always has a large group of skeptics.
    – JHBonarius
    Commented Oct 6, 2017 at 11:02
24

More notification is important, even if SO is better without documentation.

Despite warnings and meta discussion ever since I joined Stack Overflow that documentation was dying, dead, or diseased (seemed the end of documentation was always forecast, but yet it never happened), I created several examples in a very specific topic area to help address relatively common issues I was seeing in questions. I used these examples to help keep posts shorter, while still providing background information that was lacking elsewhere. Likewise, I have used, more than once, the example of another contributor.

These examples are rather verbose, but depending on the question, they may be fairly important or they may be supporting information. I could move all my examples to a third party site (skipping the contributions of others), but I feel a better solution may be to selectively include information from the examples in my answers. I feel that the answerer is generally the best suited for such a task.

Given that many users are cautious in editing others answers, the suggested approach:

we automatically generate suggested edits from the Community user and submit them incrementally as there is space in the queue.

may take some time to be completed. Also, it is likely that the ideal person (the answerer) to make many of those edits won't get much of a chance to make them once they hit the queues.

I'd appreciate a chance to edit documentation out of my answers before this automated process kicks in. Yes, I'm aware I could do this now, but I have limited time and connectivity for the next week (and what of the internet points if I remove documentation links prematurely?). Some examples, as another answer suggested, might better be reincarnated as self-answered questions, and it would be wise to give other answerers a chance to consider this too. Lastly, incorporating other contributors' examples into existing answers will require some thought so that the content is not merely plagiarized but still properly attributed of course.

There are also certainly some users with many more answers that reference documentation, or users that are unaware of this change (I accidentally stumbled into this question). And, no, I don't expect all answerers to actually make or want to make changes to their answers simply because of the demise of documentation.

Is it not possible to keep documentation around for two weeks to three weeks (possibly with diminished visibility and accessibility for documentation to allow it to start to dip below the horizon) to allow for proper notification, and to give answerers an opportunity to remove the documentation from their own answers while still having access to that documentation? At the moment, it appears that everything will be in motion within a week, potentially, with the documentation end date of August 8th.

With that timeline, I will likely just copy my examples, make a list of affected answers, and edit the answers simultaneously with those in the review queues trying to clean up for me. Others, if unaware of this question, decision and timeline, will have less time, or no time, if they wish to update their answers. They should at least have a chance and get proper notification (I realize the election reduced the number of featured meta links, but it would still be nice to be featured there).

Lastly, I'm sure someone can do it rather easily with a data explorer query, for those with an order of magnitude more answers than me, it could be advantageous to be able to find a user's answers that reference documentation easily.

9
  • 5
    Concerning the last point: site search with url:stackoverflow.com/d should do it. For example, you have 16 answers linking to Documentation.
    – user6655984
    Commented Aug 3, 2017 at 1:21
  • 2
    We aren't going to remove the content immediately. It'll probably be several weeks before we finish with the Q&A links, so the content will be on the site for at least that long. It's also still up in the air what we'll do. Our initial plan as presented in the question was crafted with significant time pressure. We certainly didn't decide (or even suspect) until recently that Documentation needed to end. Our final plan may very well look different. Stay tuned.
    – Jon Ericson Staff
    Commented Aug 3, 2017 at 1:23
  • @Alex, Ah, wasn't thinking, thanks for the easy solution to that point. Commented Aug 3, 2017 at 1:23
  • 1
    @JonEricson, my misunderstanding, I was thinking suggested edits for documentation, not suggested edits for questions with links to documentation. In any event, ensuring sufficient notification to users, prior to a queued approach, is still my main point. Commented Aug 3, 2017 at 1:27
  • As for the notice, we recently added a banner on the site and we'll be emailing Documentation users (who have elected to receive emails) tomorrow. I believe this question will be featured tomorrow. (It has been a busy couple of weeks on Meta.SO!)
    – Jon Ericson Staff
    Commented Aug 3, 2017 at 1:28
  • 1
    @JonEricson, just noticed the banner, though it is only on the documentation site (understandable given how few people use and/or contribute to documentation, spamming the main site might be unwanted; however, many of those contributors might not visit the documentation pages very often), but all those steps are steps in the right direction. Commented Aug 3, 2017 at 1:32
  • Yeah. The banner is intended to notify people who might be considering starting a draft or have some drafts in the works. The emails will notify many more people, I expect. But there will still be people on vacation or just not paying attention who will miss the notices. I can pull their drafts from the database if needed, but the content won't make the data dump.
    – Jon Ericson Staff
    Commented Aug 3, 2017 at 1:38
  • Can't reach/please everyone, it would require unreasonable means. But a reasonable attempt to give folks a heads up with a bit of lead time is always appreciated. Commented Aug 3, 2017 at 1:44
  • 4
    An approximate timeline might help the discussion. For example, freeze Aug 8, next step (whatever it is) Sep 8?
    – tripleee
    Commented Aug 3, 2017 at 8:03
22

Sad to hear this, but I understand the decision.

For me documentation was not necessarily solely about documenting things that had little to no existing documentation but also about making existing documentation more helpful.

A prime example is the .NET languages documentation. Admirably MSDN has reams of documentation on this, including example code - but very few of the pages offer any information as to why a programmer might choose one method or class over another. So many SO questions that arise from this can be answered by "Read the source code" which, while it would provide an answer of sorts, it does not help someone that doesn't already know what they are doing or fully understand what they need (and thus would not really need to ask a question).

An example of the problem this solved can be seen in the following outline of a forum thread that was typical when I was learning VB.NET on the job:

Me: I need my FooJubber to work asynchronously, how can I do this?

A1: You need to use a TaskGlobberb, here's the MSDN link to that class.

Me: OK, thanks. I've started adding it to my program but I'm not sure how to cover X case though. explains more detail - maybe some code

A2: Hey, you shouldn't be using a TaskGlobber at all!

A1: Do X case like this some code

A2: You should use a ThreadFlibber really, here's the MSDN page, you will need to rewrite what you have so far to fit it.

Me: Hey A2, why is a ThreadFlibberNub better than a TaskGlobber? What's the difference? That MSDN page doesn't really explain the pros/cons

.... rinse and repeat

Of course this is not an SO type question, so I was excited to think that Documentation would make the whole process faster, less frustrating and most importantly, require less rewrites, by adding something more than the dry simple description on official documentation pages such as MSDN (and others).

That said, the result is not always what transpired on Documentation. Even so I am quite proud of my and others contribution to the project, some tags became quite helpful, even those with which I already had a lot of knowledge on.

WRT lessons learned I think you hit the nail on the head with "fail faster". Although it only gets minimal mention in the OP, the problem seems to be that it took until May (10 months in I think?) to see that the business case wasn't being filled. I'm unsure if this time-frame is typical for such projects, but it allowed a lot of effort and work by both contributors and staff to be invested in a product that is now being essentially thrown in the bin.

3
  • 8
    The question was already getting long, so I didn't go into all the twists and turns. We really didn't get clear metrics to aim for until the beginning of the year. At launch, the business goals were very broad and not explicitly measured. We felt the feature was too incomplete to start evaluating from a business standpoint until we had the discussion feature. I expect we'll be able to talk about this in more detail soon.
    – Jon Ericson Staff
    Commented Aug 2, 2017 at 15:11
  • Thanks for the added info @JonEricson
    – Toby
    Commented Aug 2, 2017 at 20:30
  • 1
    "...but very few of the pages offer any information as to why a programmer might choose one method or class over another." I guess in the end it's always a matter of convention/good practice and design guidelines/philosophy. This is surely something good programming resources should contain.I fully agree there is a market for this but creating it is not a small effort. Maybe StackOverflow overengineered the feature, did not clearly communicate what they wanted, enforced the rules not enough and had not enough stamina to stay with it until it's really finished. The basic idea sounds still okay. Commented Aug 13, 2017 at 12:03
21

A huge part to why this failed was described in this post itself.

"programming documentation is not universally broken"

We have documentation already for many technologies, (yes they can be pretty terrible or limited) but we have that starting point. So to the other issue was:

"New users weren't coming to Documentation."

I would not think new users would come to community created docs that are incomplete. They will also not go searching for it on Stack Overflow first. They will find it from the docs page of that technology.

What I would love to see happen:

Documentation should not be community created but instead community maintained.

We need the official documentation on technologies to be in the same place as community edits, faqs, and tutorials. The tooling that was provided by Stack Overflow to create and maintain documentation was great for anyone to easily give back. We would need support from bigger open source projects to host all of their documentation on Stack Overflow. This will make us more focused as a community and keeping our documentation DRY just like our code should be.

2
  • 1
    Nice idea. SO team should keep this in mind. They have the Q&A system as enterprise product, so maybe they can make a hybrid Wiki/Q&A/Voting thing as Enterprise documentation product. Just extend the current thing. Commented Aug 6, 2017 at 20:40
  • 1
    Agree. No new users (beginners) will dive into documentation. The advanced ones look for this. Commented Oct 2, 2017 at 6:32
20

I'd like to say a few things as one of the 294 privileged users who participated in the early stages of Docs.

First and foremost, I'd like to thank Kevin M. (whom as I recall got engaged during, and maybe thanks to, Documentation private beta) and Adam L. for the direct and verbose communication channel they've given us through chat. I can't stress enough how beneficial, welcoming, and important it is for users who are closely involved to have the option for a direct daily free-form chat with the developers. Iv'e been in a similar situation as a contributing user where the chat facility with the developers was largely unused to detrimental effects.

You said you've learned a lot of lessons about the development process of new features, I hope this is one of the positive lessons. That, and also

We’re certain to have failed projects in the future, but we’re working to fail a lot earlier in the process.

the re-discovery of the fail-fast approach.

Secondly, my (lack of) thoughts about reputation and badges. Personally, I don't care much for badges and non-gold tags (of which I "proudly" have none). I can't imagine anyone, including myself, digging in my profile to see what activities I participated in and I can't display them anywhere for "bragging rights". As much as I'm proud of the private beta badge and would like to keep it... take them... take them all... I can live with... OK, maybe leave us this particular one?

I personally wouldn't care much for the reputation or other internet points, but many users spent a lot of time in Docs so I guess it's only fair if they retain their gains. As others suggested, it would be preferable if the reputation tab detailed the actions for reputation changes and not just a one-time event "this is for all you did in Docs".

Lastly, I'd like to share my personal experience with Docs. I was very excited for getting in the private beta and I wanted to start working on the Java topics. Fortunately to Java developers, and perhaps unfortunately for Docs, Java is already a very well documented language. Between the API, official tutorials and many long-standing bloggers (some of whom are SO users), example sites, and even my friend the dreaded JLS, there wasn't much to add. This already came up in the chat discussions and I wasn't the only user aware of this. Turns out Java wasn't the greatest target for Docs.

What eventually happened is a lot of duplication of material from outside sources, not to talk about a decent amount of plagiarism which was removed quickly, and a lot of trivial examples (convert int <-> char anyone?), all of which wasn't in the spirit of supplementing existing knowledge. The more "advanced" topics I created didn't seem to gain much traction, unlike the basic language topics which were very popular for some reason but also redundant. I quickly found myself flagging to remove content more than adding to it, which led me to stop (un)contributing. Even as of 2 months ago, most of the content on Java is redundant and I have no qualms about seeing it disappear.

I am glad, however, that for those tags with poor documentation the SO Docs made a difference. GitHub's conclusion about "incomplete or confusing documentation" is no surprise in a programmer's world where new options arise so often. For developers to use a language or a library they must be shown how to as there's not time to figure so much yourself, and if they don't, their ship will sink. Docs might have been the tow boat, but maybe because of the timing or the platform itself, it didn't live up to its promise.

I can only hope that Kevin's next attempt will not cave in (I'll show myself out when I finish this sentence) and I'll be glad to be given an opportunity to pioneer the effort yet again.

0
18

I'm saddened by the news, I contributed quite a few bits and pieces over the months, and seeing it all go away isn't a good feeling.

I enjoyed Documentation, if I'm looking for a more complex answer, or a better explanation on a feature, Docs were my go to, I felt the system was abused a little bit. A lot of edits especially at the start due to the rep being so high. But you fixed that.

I would like to take this opportunity to thank for team for building Docs. Personally I loved it and wish it could stay, despite what your post depicts, I also felt it quite welcoming, when it first started is was like a huge blank book ready to get written.

Also thank you for all the contributors, whether you fixed a typo, added an example or simply reviewed changes, thank you too!

14

What happens to reputation?

Would it make any sense that on days where a user gained 200 points including some from documentation and got some 'dropped rep' because of extra votes (the reputation cap), that the documentation reputation is replaced with the 'dropped rep' instead of a one-time boost.

It might distort how much effort some people put into Docs, but if Docs had been missing, those people would have got the reputation the other way. Where their non-Docs rep excess doesn't compensate for their Docs-rep on a given day, then the Docs-rep compensation scheme would come into play. (I know I've had a few days where I've had some Docs-rep and some surplus non-Docs-rep and the one could play off against the other.)

OTOH, this is more complicated. And there's an element of 'simply aggregating Docs-rep into a one-off grant' better shows how much different people contributed to Docs. But then people might seem to have earned less than the rep cap on days when they were capped because they had some rep from Docs.

I don't have strong views on this; I'm merely raising the possibility as something that should perhaps be considered before choosing the simpler scheme.

11
  • 2
    What you desire is probably already going to happen. If they are going to remove Docs rep, as they say they are, and instead apply a bulk rep grant, my expectation is that a complete recalc would automatically occur resulting in what you desire throughout the time when Docs rep was earned. Such action would cause any up-votes which did not previously provide you with reputation to be able to fill in the rep (up to the 200/day limit) on the days where Docs rep was no longer earned.
    – Makyen Mod
    Commented Aug 2, 2017 at 4:10
  • But if a user had a large Docs rep day with a small "normal" rep day and rep-capped, he may not rep-cap with the recalc and that could effect badges.
    – FreeMan
    Commented Aug 2, 2017 at 11:54
  • 6
    Bit of a miscommunication here - I talked about rep with the team. It should stay exactly as-is (not a one-time grant, that'd throw chronological math off in all sorts of ways). Just no links on the items after sunset. The plan is to basically freeze the rep currently there in a grandfather historical table that's used when re-calculating rep in the future. Luckily we now have a RepHistory table with every single rep entry in there, and we can save the Documentation types off (rather than deriving them them from the Docs tables during a recalc going forward).
    – Nick Craver Mod
    Commented Aug 3, 2017 at 10:20
  • @NickCraver What is "In all sorts of ways"? People would gain a bit extra rep if they overcapped due to docs, and maybe lose badge progress if they capped from docs a lot. Nothing substantial. Any reason why it'll not just be done as a block besides that?
    – Magisch
    Commented Aug 3, 2017 at 10:55
  • 5
    @Magisch picture for example the 1 rep user, they got 500 from documentation, then they issued a bounty. They had the rep to do so, now what do we do if they didn't get that rep until after the bounty? They'd have been at -499, it'd make no sense. So we have to inject rep into the system as an offset grant to make that bounty make any sense. This was an issue back when rep wasn't realtime and skewed greatly between recalcs. In short: you can't just change a timeline, things literally don't add up :)
    – Nick Craver Mod
    Commented Aug 3, 2017 at 11:05
  • @NickCraver Won't the recalc then just still sum it all up. Like yes he would've been at -499 for a while but would the system care about that sides from a graph? They should still have their proper rep at the end, no?
    – Magisch
    Commented Aug 3, 2017 at 11:17
  • @Magisch I don't think they would- If the grant is after the bounty, and you logically can't go below 1 rep, I would think that this would put that user up to 501 rep instead of the 1 they should be at.
    – Kendra
    Commented Aug 3, 2017 at 16:16
  • @Magisch Kendra is correct, they'd have received a net 500 rep they otherwise wouldn't have. The timeline would be corrupted and we'd have injected rep maintain the integrity of the history, unfairly. The solution we're going with isn't complicated, and will have no side-effects like a grant does.
    – Nick Craver Mod
    Commented Aug 3, 2017 at 19:57
  • @NickCraver: Not making a 'one-time grant' and just leaving the doc-sourced reputation in place is certainly easier. Would you have the link identifying it as 'reputation from docs' go somewhere to explain to the curious, or just have an anodyne "reputation from Documentation Beta" with no active link, or some sort of hybrid (active link to neutral explanation, but the link text is from the documentation topic, possibly prefixed with Documentation or something similar to classify it). But my concern is being taken care of (thank you). As you're aware, rep is a touchy subject on SO. Commented Aug 3, 2017 at 20:09
  • @JonathanLeffler Having a link to somewhere makes sense to me, how about pitching that as an idea in an answer here? That wouldn't be hard to do if we have a landing site.
    – Nick Craver Mod
    Commented Aug 3, 2017 at 20:11
  • Geez you have a lot of rep.
    – Clonkex
    Commented Aug 4, 2017 at 5:18
13

I'm sorry to learn about your decision to stop the Documentation project, though I understand limited personnel resources and the need to focus on areas that will make money for your company.

I hope you will seriously consider tackling this project again in the future. The following points are nothing new but illustrate that there is still a void waiting to be filled:

  • Official documentation pages, while helpful and not completely broken, are often very terse and difficult to understand. They frequently lack adequate examples and explanation. Where there are mistakes or when they become outdated, there is no easy way for the average user to get them updated.
  • Random tutorials across the internet have tried to pick up the slack but are not systematic.
  • Stack Overflow Q&A does serve as a form of documentation. However, in its current state it does not readily accept requests for very general explanations (howto tutorials) or very specific questions ("Can you show me an example of this obscure API?"). There is also not much linking related topics together besides the tags, so it is not practical to explore a topic by browsing through a hierarchy.

The sun sets, but it rises again the next morning.

4
  • 16
    Within the company I've heard a lot of estimates for when we might be able to get back to Documentation. All are at least a year (which is too optimistic in my view), but none are never. If someone else doesn't beat us to it, I'm confident we'll try again with what we learned this time around.
    – Jon Ericson Staff
    Commented Aug 2, 2017 at 2:11
  • 3
    "very specific questions ("Can you show me an example of this obscure API?")" It should be noted that such questions are not forbidden because they're "specific". They're forbidden because they are very general and open-ended in their answers. Commented Aug 3, 2017 at 5:26
  • 1
    However there are several competitors to such a documentation hub, including Wikibooks as mentioned in meta.stackoverflow.com/a/354416/1333493
    – Nemo
    Commented Aug 4, 2017 at 10:01
  • An alternative phrasing of the API question is, "What's the purpose of this API function?", which is perfectly valid, and usually answered with an example. Commented Aug 7, 2017 at 8:14
12

I personally was always torn between whether I should just blog something, or help out Documentation. I ended up posting some Examples on Docs. I'll probably just transfer the Examples to my blog. Would it be possible to get an email from SO with a list of all the Q&A posts that link to my Examples. That way I can just change the links to my blog instead?

2
  • 8
    I suppose that would be a possibility, but I'm not sure how many people would move content to their own blog. You can find the links you added to Q&A posts by searching user:me url:stackoverflow.com/documentation. Your contributions can be found on your profile in case you want to search other people's posts.
    – Jon Ericson Staff
    Commented Aug 3, 2017 at 21:23
  • @JonEricson Ahhh! That's a neat trick. Thanks! Commented Aug 3, 2017 at 22:25
7

Most Community user mass-edits have been pretty straightforward tasks like link migration that don't need contextual awareness or the approval of a human to be done properly.

I don't think automating something on the order of what's being described in this post is a good idea considering the lack of uniformity in how the links are used. In my experience, these types of loosely-defined editing schema can get you into trouble, particularly where review queues are involved.

I don't have an alternative to offer outside of archiving the content with some kind of disclaimer that it may be outdated (which obviously comes with its own set of issues discussed in the post). However, I don't think this is the type of thing you want to automate given the wide variety of use cases for links to Documentation that you mention; perhaps a -style effort is in order?

2
  • "perhaps a burninate-request-style effort is in order?" -- like Nathan's suggestion in the top answer?
    – Frank
    Commented Aug 2, 2017 at 14:49
  • 1
    @Frank Yes, I hadn't read the other answers yet when I wrote this, but I agree with his suggestion. The main thing I wanted to stress here is why it's not a good idea for the Community user to perform these edits.
    – AstroCB
    Commented Aug 2, 2017 at 14:53
7

A second 'answer' (suggestion) from me. In a previous 'answer' (question, suggestion) with the general topic 'What happens to reputation?', I asked about the 'block grant' system mooted in the main announcement ('question'). It seems that this will be handled differently from the way originally outlined, and my concerns are effectively dealt with.

In the comment chain after that answer, I commented:

Would you have the link identifying it as 'reputation from docs' go somewhere to explain to the curious, or just have an anodyne "reputation from Documentation Beta" with no active link, or some sort of hybrid (active link to neutral explanation, but the link text is from the documentation topic, possibly prefixed with Documentation or something similar to classify it).

Nick Craver suggested:

Having a link to somewhere makes sense to me; how about pitching that as an idea in an answer here? That wouldn't be hard to do if we have a landing site.

So, I'm pitching my suggestion as an answer for debate.

My general idea is that where an entry in the reputation pages currently shows something like:

enter image description here

(where you have to know that Hello World is (currently) a link to the C Documentation), it might show the text Documentation: Hello World instead — to identify the reputation as coming from Documentation — and the text might be a link to a general explanation of what Documentation was, noting that it is a withdrawn experiment, etc.

1
  • 1
    Or "retired documentation: [c] Hello World" -- with the tag as well as noting that it's an old Docs project (in case a later version also makes an appearance in the rep table).
    – Frank
    Commented Aug 3, 2017 at 21:49
6

Another badge question: Will the private beta badge be merged with the others, too? I'm absolutely fine with the silver badge for documentation public beta, but I feel like the private one should be separated from this.
I didn't really participate since the documentation went public because it was a huge mess at the beginning and I lost interest...

6

This is a minor issue but it is something to think about:

Community likes to randomly bump unanswered posts to get them more attention. Normally this is not an issue but with docs being removed is Community still going to bump docs meta posts like it did to this one? If it is can we tweak it to ignore the documentation tag as I can't see any benefit of it doing so.

1
  • 2
    Community only bumps posts which have an answer but the answer's score is 0 (more precisely: at least one answer scoring 0 and none with positive score). This isn't a common thing on Meta, where votes are in rich supply. Community does not bump questions without an answer.
    – user6655984
    Commented Aug 3, 2017 at 15:03
6

Why not set up a bare-bones wiki as it was initial inspiration of documentation as said in The dawn of Documentation: a solstice update?

After the why, I explain a simpler model that might have worked and why this modern one did not.

My experience comes from being an old contributor to Wikipedia.

I found the experience of a technical writer of other wiki documentation cited in comments irrelevant because if I understand well why the scope of such a wiki is different: It is usually a single project wiki, and it does not have the critical mass of contributors.

The second point is that it seems that instead of start of the simplest model which can work (a bare-bones wiki) and develop around it according to the needs which arised from here, you have developed an overengineered model in the hope it will fit. From my experience, the way that the documentation is single centered around example fit to some of the subjects, but not all.

The third point of failure comparing to Wikipedia is that by wanting the contribution systematically peer reviewed and moreover by several peers you lost immediate feedback for new users.

The fourth point is that you had absolutely wanted to set a reputation system which overconstrained your system. As much it reasonably works together with single contribution document authors such as Q&A it is hard to work with multiple authors. It leads you to have a confirmation system to be sure that people will not game the system. The motivation behind Wikipedia contributors is as long as I can analyze it is mainly to act for the general good.

12
  • 5
    One of the findings from our interviews with technical writers is that wikis are commonly suggested, but rarely useful. Not to say they can't work for documentation, but rather that it's a long shot. One key would be to develop a comprehensive set of templates to cover all sorts of documentation. But that's exactly the challenge we face pressing forward with this pass at Documentation. It wouldn't save much, if any, effort.
    – Jon Ericson Staff
    Commented Aug 3, 2017 at 21:11
  • I think a wiki is exactly the way to go. Yes, there are challenges, but the experiment you are now terminating points to even more severe challenges with solutions which look like wikis reimplemented poorly.
    – tripleee
    Commented Aug 5, 2017 at 9:03
  • @tripleee It probably depends a bit on how one defines a wiki. It could be almost anything. Challenges were not only organization, also voting, solving edit conflicts and of course reputation. While gamification helps a bit it should never be the main driver. Commented Aug 6, 2017 at 20:44
  • @trilarion solving conflicts would be made via discussion as in wikipedia. There would no reputation neither voting Commented Aug 6, 2017 at 20:48
  • Voting on Q&A SO is very efficient to tell you which content is actually useful. The biggest difference between Wikipedia and Stackoverflow Q&A IMHO is that Wikipedia is collaborative editing and Q&A isn't. Not sure how Wikipedia copes with different opinions about topics, but SO Q&A handles that very efficiently. My main problem with Documentation was that a) the structure was totally inflexible and b) the reputation attracted lots and lots of crap. If without these two things, my motivation to make Documentation great would have been much higher. Commented Aug 6, 2017 at 21:01
  • 2
    Basically wikipedia copes with different opinion via discussion. It is far less efficient than voting for single author document as so qa. But for multi author document, the documentation model show that voting just don't work. Commented Aug 6, 2017 at 21:07
  • @trilarion moreover, they are rarely conflict on wikipedia on technical subject such as the ones which would be concerned by a language documentation site. On wikipedia the man conflict are political, religious, ... Commented Aug 6, 2017 at 21:11
  • I see. So the main competing concept to Q&A like SO is some kind of Wiki approach with collaborative editing and lots of discussions. It might be more work but the result might be a more coherent, authoritative form of knowledge. Maybe Q&A will become/remain the debugging helpdesk and the future of example based documentation will be based on a Wikipedia like framework. Commented Aug 6, 2017 at 21:33
  • The standard definition of a wiki will do. The crucial difference to tag descriptions on SO main is the ability to create and name new content pages freely, so you can restructure and refactor content organically. Still a lot of work, but in the words of Einstein, "the simplest thing that will work, and no simpler".
    – tripleee
    Commented Aug 7, 2017 at 3:35
  • Except I don't think it will fly; you will get the poorer parts of wikipedia, lots of stale discussion beginnings, and still lots of plagiarism because if the parts you want to be there when you start to write something original are missing, that's the the quick and dirty fix.
    – tripleee
    Commented Aug 7, 2017 at 3:38
  • the plagiarism is a very little problem in wikipedia, usually a simple google search get the plagiarist so quick. And about discussion, I would expect a very smaller amount because in technical things, the amount of subjectivity is usually a lot smaller than in wikipedia in general. Commented Aug 7, 2017 at 16:24
  • In Wikipedia, the motivation is seeing your work being actively used on a high-profile site - basically, vanity publishing. There also do exist medals awarded to distinguished contributors and privileges conferred upon those who showed they can be trusted with them. Remember, Wikipedia pioneered mainstream wiki use - before it demonstrated the viability of its model, few believed the general public can be trusted with directly editing a site's content. Commented Aug 27, 2017 at 14:44
5

Why not make a community effort to port the content over to MDN? I've seen GitHub and the Wayback Machine mentioned in the comments, and while I agree with using either/or, porting to MDN would benefit both communities and the web in general. I always felt that documentation was reaching too far here, and wondered why there wasn't a community push to create/edit more documentation on MDN. As fate would have it, I feel like this opportunity has presented itself again, and we should take advantage.

I'll be porting over the very limited additions that I made to Documentation, as well as certain technologies that I am interested in. Would love to see like minded individuals do the same.

2
  • 1
    Please keep us updated on your progress. For people who want to build off of Documentation content (and not just archive it), MDN and similar platforms seem like good destinations. As always, please observe the target community's guidelines. (For MDN, Working in community seems like a good starting point.)
    – Jon Ericson Staff
    Commented Sep 9, 2017 at 20:21
  • lol. i'm one of the contributors to that page. but i appreciate that, and hope others will find this comment and the link useful! what other similar platforms are you aware of?
    – albert
    Commented Sep 9, 2017 at 22:23
4

I am also sad to hear this. I think a collection of examples and tips on all these technologies is definitely a useful resource.

One way I would appreciate being able to still have access to the content is if it were included in devdocs.io and its offline desktop application.

I don't know how big the dataset is, but if it's reasonable that would be an awesome way to share it.

For developers like me who are offline most of the time, this allows us to have a ton of examples and tips for our favorite languages offline, completing the official documentation.

2
  • 1
    Is that just for API docs? As mentioned above, there is Kiwix (with ZIM) for offline consumption meta.stackoverflow.com/a/354412/1333493
    – Nemo
    Commented Aug 4, 2017 at 10:06
  • 1
    @Nemo Thanks for the tip. I didn't know kiwix. It's quite amazing that one can have all of wikipedia and SO offline. Unfortunately I don't have the bandwidth to download that, and their desktop app is far not as pleasant as devdocs. I don't know if it's only for api docs, I think it's for docs that someone is willing to port over to the right format. Their is a trello board with suggestions for new documentation sets.
    – user1115652
    Commented Aug 4, 2017 at 10:53
4

Wayback Machine can be a great way to maintain data and will provide a solution to broken links originating out of the Stack Exchange network. I feel it to be easier to use than a data dump.

4
  • 2
    I found one problem with the Wayback Machine for Documentation: it strips off %23 and anything following it in URLs. That makes it impossible to archive C# topics.
    – Jon Ericson Staff
    Commented Aug 28, 2017 at 15:26
  • 2
    @JonEricson That's unfortunate. Thank you for taking time to go through the documentation.
    – Kolappan N
    Commented Aug 29, 2017 at 3:08
  • 1
    @JonEricson can you show me an example URL that this occurs on please?
    – albert
    Commented Sep 9, 2017 at 22:20
  • 1
    When I try to save stackoverflow.com/documentation/c%23/topics, it returns web.archive.org/web/20170908120532/https://stackoverflow.com/… . It seems something truncates the URL somewhere along the way.
    – Jon Ericson Staff
    Commented Sep 9, 2017 at 22:24
3

The main problem in my opinion is, there was no difference between Q&A and "Documention" except the running software.

What was "Documentation"? That was never been clearly defined.

From the latest meta update (I have read), it should have been a set of examples for real programming tasks. Voting is based on how much helpfull it is.

How does this differes from Q&A? What is Q&A? It is a set of answers for a real programming tasks. Voting is also based on how much helpfull it is.

So, where was the difference? I don't see any (Except rep farming was easier on Documentation and some badges).

So if you by chance want to start anytime a similar project, please answer this questions:

  • How is it different to the current product?
  • Why should people contribute?
  • Why people want to use it?

I am still a fan of the idea, that documentation is written by programmers (that actualy need to use it) instead of other persons, that have no idea about the real world programmers need. Especialy if we have one quality standard, where I can say, go to Stackoverflow Documention, it is the best place to get some information. But that's all, what "Documentation" was not. In fact, I never get a result on google that has redirected to "Documentation".

I am not realy sure, what a perfect product would be, but please make sure it improves something. Maybe it is better to work on some top voted and ignored Feature-Requests. Especialy on Triage/H&I, since crap is flooding the Q&A product.

7
  • 3
    "It is a set of answers for a real programming tasks." No, it's not. "tasks" are generally bigger things than the specific questions we allow on SO. "How do I load a shader in OpenGL" is too broad a question for SO, but it would be an adequate task for Docs.SO. My post here outlines what I would felt would work better for what they were trying to do. Commented Aug 6, 2017 at 1:32
  • Agree. But I think this is more a scope issue, than a software issue that the Q&A software can't handle. This could be a perfectly valid question, if we have a SE community that supports broad tutorial questions. I am in favor of improving one product then creating duplicate products. @NicolBolas Commented Aug 6, 2017 at 1:40
  • 2
    I disagree that the Q&A format really can allow such things to work. SO prioritizes new questions over old ones, by design. Such broad tutorial-like questions don't work well in that environment, since it's easy for such questions to get lost in the shuffle and never get answers. Such answers take much longer than answers to other questions. Also, remember that SO's current rules exist because we've tried being more loose in what we allow, and it just doesn't work. Commented Aug 6, 2017 at 1:50
  • Mh, I never has seen a question get losts on Stack Overflow, exception on a low traffic tag. Same problem in Documentation. The scope for Stack Overflow is perfectly fine for me. A bigger problem is to me, less people apply it correctly! But on the other hand, we even have very highliy opinion based communities like hardwarerecs.SE. If we need tutorials, maye we can propose a site for it. Just saying, I see no difference. The more I think about it, How do I load a shader in OpenGL, sound even not to broad for SO. tbc. Commented Aug 6, 2017 at 2:18
  • Even how to check if a file exist is upovoted in any language I know of. As for your Meta Question, where the answer is basicly: Teach a poor man to fish, and he never asked for something to eat. That's classical documentation. SO Documentation should have been primarly example based, that is the opposite. That's where I feeling that there is no difference. Commented Aug 6, 2017 at 2:18
  • "So, where was the difference?" Oh, there was a difference. Q&A is much more localized while Documentation was supposed to contain larger examples for general topics. Something that would have been closed as too broad on the Q&A site. I agree that there was not enough guidance on that but in principle it was clear what was meant even though people didn't follow the idea. Commented Aug 13, 2017 at 11:57
  • I totally disagree. 'How do I load a shader in OpenGL?' is a great question for StackOverflow.
    – mrr
    Commented Aug 31, 2017 at 22:53
2

I wrote off Documentation in my book as soon as I heard it bring forth loads upon loads of easy rep that carries on to SO, without even looking into anything else in detail.

(I did get the general picture - that it intended to contain docs and code examples and stuff or something, and that's it, what was the bigger idea, they couldn't express themselves, apparently. That was enough to convince me it wasn't worth the time.)

I've seen enough rep whoring on this site and its consequences (both direct inflow of junk stuff and indirect as poor contributors gain privileges and start to have an ever bigger negative impact on the content and community, without any incentive to improve whatsoever) to support anyone who condones (even more so, encourages) this kind of behavior. That was the biggest breach of trust from the site's management I've ever seen.

Since protesting was useless - the relevant posts' authors really sounded much excited and eager to get it going at any cost - I did the best I could do - protest silently.

-1

I would like to suggest an extension to the JSON archive:

Downloadable mark up files of parts of the documentation.

A nice way of structuring those files would be:

  • A tag is a file (the title would be like <tagname> -- from Stack Overflow Documentation)
  • A topic is a chapter
  • An example is a section

Possible mark up languages could be

  • Markdown
  • HTML
  • reStructuredText
  • LaTeX

Rendered output from those files would make it possible to have a nice eBook containing all the knowledge for, let's say Vim or JavaScript.

6
  • 1
    Everything on SO was already written in Markdown. I'm not really sure what you're suggesting here. Is it a reorganization/collation of the content somehow?
    – jscs
    Commented Aug 3, 2017 at 17:44
  • 3
    I think the JSON archive will be a good place to start. As @JoshCaswell mentioned, Markdown (technically CommonMark, in this case) is how we store posts. It's fairly easy to convert that to HTML and certainly possible to convert to LaTeX with existing libraries and tools. Making a book sounds like a fun project as long as you don't botch it. ;-)
    – Jon Ericson Staff
    Commented Aug 3, 2017 at 18:22
  • If the goal is to have an ebook, then I suggest producing a ZIM (nicely packaged HTML) which can then be read with Kiwix: kiwix.org
    – Nemo
    Commented Aug 4, 2017 at 10:03
  • 2
    Sounds like you are reinventing ... Markdown exported to JSON. Transforming to an XML or LaTeX form of your liking will not be entirely trivial, but in any event probably something you can (and likely should) do yourself if you have a clear use case in mind.
    – tripleee
    Commented Aug 5, 2017 at 9:24
  • Well the idea was to create something that everybody could use easily without any big conversion effort. I know that converting JSON to markup is possible (and easy, this is actually a part of pandoc), but It would be easier to use if the content is already bundled. I proposed non-markdown formats, because they usually provide nicer layout and intra-link features. Commented Aug 5, 2017 at 18:56
  • @JoshCaswell reorganization/collation are the right words. Commented Aug 5, 2017 at 18:57
-1

I spotted this topic only today and only today I was actually using Documentation for the first time. Particularly reading "New C# 7.0" features. Documentation is the best page on the Internet to read about it: clearly to the point, with examples, up to date, covering nearly everything. Simply put: not a single guy (nor John Skeet, nor Chuck Norris) is capable to think, plan and publish it as good as an engaged community can.

How is Documentation different from Q&A? It's categorized and filtered. It is way better to learn by reading Documentation, than from dozens of tagged questions and answers. Q&A learning require more time, many questions are too specific to the OP's problem, many answers are too specific to the OP's problem, and the readers often have issues to apply the solution to their own case. Another possibilities to learn are reading books or follow a tutorial. I believe Documentation is a very good way to learn something.

What were the problems with documentation?

New users weren't coming to Documentation

Because they want to ask the question and receive the answer, and I haven't seen many answers what were using documentation. The mechanism to link Q&A with documentation is missing, it is simpler to close the question as off-topic for asking off-site resource, than to go and search documentation and answer with the link to it.

Another problem is discovery. Google rather gives links to Stack Overflow, than to documentation. Documentation is a black box for the stranger. Its existence is well hidden. It is possible to use Stack Overflow without even knowing about it.

I haven't participated myself in Documentation, because I didn't feel its potential and haven't seen its connection to Q&A. I was waiting and waiting, but it just didn't happen. And now it's down...

So what now?

We can move Documentation into Q&A. Every topic is an answer and it simply needs correct tags and question "What is ...?" or similar. I believe this can be automated, reviewed once, done. The questions and answers will be updated later auto-magically with new answers and links to duplicated and related questions by community.

2
  • 7
    I was thinking about upvoting this until the last paragraph. You have some good points, but I don't agree with your conclusion.
    – tripleee
    Commented Aug 5, 2017 at 9:06
  • 2
    I think a Q&A style layout to Documentation would've made sense. "What is StringBuilder?" or "How do I read from a text document in Java?" could've worked as a question body, followed by responses by the community just like any other question would. Voting would work in the same style and it would feel at home with the rest of the Stack Overflow/Exchange community. Commented Aug 14, 2017 at 16:27

You must log in to answer this question.

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