Timeline for answer to Warlords of Documentation: A Proposed Expansion of Stack Overflow by user247702
Current License: CC BY-SA 3.0
Post Revisions
38 events
| when toggle format | what | by | license | comment | |
|---|---|---|---|---|---|
| Sep 8, 2015 at 19:31 | comment | added | R.M. | @KevinMontrose Rep farmers mean you'll get duplicates, even if it isn't copy/paste. On deleting, "the community" isn't monolithic. What will happen is part of "the community" will think the external docs are better (and "leave"), but part will always think the SO version is better - even if it's for arbitrary reasons like formatting. Since they're the active users, their opinion will likely carry the day. Thus the SO version will duplicate external docs and then won't ever get deleted. That's fine if you're aiming for "all the things", but please don't send mixed messages on your intent. | |
| Sep 8, 2015 at 15:10 | comment | added | Καrτhικ | Consider how a framework becomes popular. A developer creates it, hosts it on github or elsewhere, provides some documentation and people discover it and find it is useful. As more and more people discover it, it grows in popularity. One factor for popularity is that the framework solves an existing issue, is simple and is well documented. But that necessarily means the documentation is created first by the author. Do you expect authors to now come to SO and start creating documentation for all kinds of frameworks? I think the issue of organic creation will mean necessary duplication. | |
| Sep 7, 2015 at 18:30 | comment | added | Troyseph | What happens when lazy developers don't document because they know someone else will do it for free on StackOverflow???? | |
| Sep 7, 2015 at 15:33 | comment | added | FelipeAls | @poke You already cited the 2 sites I was thinking of. I'll add caniuse.com with its information about Resources (and prefixes and support obviously) | |
| Sep 7, 2015 at 0:07 | comment | added | Seldom 'Where's Monica' Needy | See my answer about how to address duplication and fragmentation problems. | |
| Sep 5, 2015 at 12:57 | comment | added | O. Jones | WoD team: May I suggest you hustle to get a design win for this idea? Get a commitment from some significant project that they'll use WoD as their primary documentation outlet. It doesn't have to be a hugely adopted project like php or bootstrap, but it should be significant enough that the team has worked out the editing, distribution, translation, and intellectual-property issues. Alternatively, get Tim O'Reilly on board. You'll learn a lot. | |
| Sep 4, 2015 at 18:34 | comment | added | Bryan Rayner | As well, if an open source library has a release that doesn't start out having any docs, and these are required to be added over time, it seems like a Stack Overflow version of the docs might be more accessible to edit than a GitHub version, since the control is out of the hands of the maintainers. Sometimes, open source project maintainers are not very responsive to needs from the community. | |
| Sep 4, 2015 at 18:32 | comment | added | Bryan Rayner | I think that if the version of the API/library were able to be specified, fragmentation wouldn't be a bad problem. Angular Docs provide a dropdown, and the entire documentation can be viewed at any version number. jQuery does things differently, and simply specifies which verson of the API the method applies to. I think a combination of both methods would allow any fragmentation that were to happen, to be fairly small in impact. | |
| Sep 4, 2015 at 15:22 | comment | added | Matthew Read | "We want to control all documentation so we get more ad revenue, but in the meantime let's make a mess and fragment everything." No thanks. Not to mention the massive quality issues that are bound to happen, even if you somehow manage to convince people to do far more reviewing and editing than happens on SO currently. | |
| Sep 3, 2015 at 14:06 | comment | added | Jossi | Is it bad to have duplicates of documentation and examples?. I would rather have multiple of same example because they can differ a little bit and I can be the judge to decide which example helped me most. | |
| Sep 2, 2015 at 1:16 | comment | added | Chris K | As long as it can be downloaded offline, I think that this project is a plus. I thank @Jacque Goupil above for pointing me to devdocs.io, this is awesome. I use Dash on Mac and iPad to do much the same. I REALLY loved MSDN on CD/DVD when I was doing Windows development. But with everything being online now, and you can't even run the AngularJS documentation without a webserver, it's a little irritating the state of things. I can't go into the mountains and code at night disconnected from the Internet anymore. In 1999 I could do that. We've taken a GIANT leap backward in that regard. | |
| Sep 1, 2015 at 23:20 | comment | added | Bennett McElwee | @KevinMontrose: "I expect that if there's no demand for documentation for X (because X's docs are good) nobody will ask for them, and nobody will create them." I worry that rep miners would simply copy the official docs; lots of people will search on the Docs site and find and upvote the copies. I guess the community would flag this and moderators would delete the copy, but it will be confusing to users, and will happen continually. | |
| Sep 1, 2015 at 18:44 | comment | added | Kyle Strand | Agreed. I would be much more enthusiastic about this proposal if the goal were to encourage/facilitate collaboration with maintainers of existing documentation (especially--though not limited to--"official" documentation). This would have the dual benefit of improving official documentation and providing SO Documentation a lot of initial content. "Usurping" should be considered a tactic of last resort, or an unfortunate accident. Also, this strikes me as related: xkcd.com/927 | |
| Sep 1, 2015 at 18:10 | comment | added | rici | I'm very divided about this proposal, and particularly the issue identified here. Frankly, I don't think that cppreference is "the enemy", nor that links to it are any more fragile than links to SO, and I would really resist anything which might weaken that project. Undoubtedly there are other examples of good community-maintained documentation, and there are certainly open source projects with excellent documentation (Python, IMHO). The idea of creating "one true repository" strikes me as hubris. | |
| Sep 1, 2015 at 7:32 | comment | added | NoDataDumpNoContribution | @NickLarsen "In the long run, we would like to be the official source of documentation for all the things." I think this is overly ambitious and will fail. The reasons are that the producer of code is the official source of documentation and that SO has a nice plattform but maybe not the best suited for all ways of documentation. Also it would require an awful lot of effort and commitment which is difficult to imagine with volunteers. I think that smaller goals are more realistic and helpful. | |
| Sep 1, 2015 at 2:54 | comment | added | BoltClock Mod | @NickLarsen: Soon you'll have libraries that export API docs as stub Q&As... | |
| Aug 31, 2015 at 21:07 | comment | added | poke | I’m also not completely convinced that having another prominent contender will not split up the documentation-willing userbase. For example for web stuff, we already have Wikis like WebPlatform and MDN, and other strong platforms like MSDN or even devdocs competing with each other; and neither platform is really exhaustive on most stuff. | |
| Aug 31, 2015 at 20:15 | comment | added | user247702 | @Kevin I agree. I'm not against the idea, just not convinced yet. | |
| Aug 31, 2015 at 20:12 | comment | added | Kevin Montrose StaffMod | So, most of the concerns voiced have been around "where are the lines". I think one thing this answer demonstrates is that we need a follow up post that lays down some more of the "rules and guidelines" we've imagined exist. Would you agree @Stijn? | |
| Aug 31, 2015 at 19:35 | comment | added | mirabilos | @NickLarsen your CC licence is rather difficult to upstream; suggest using a more BSD/MIT-style licence. (I already dual-licence all my content and document that on my network profile.) Even CC-BY is more copyleft-ish than the BSD/MIT-style ones. | |
| Aug 31, 2015 at 18:01 | comment | added | duplode | @KevinMontrose Indeed, and for that matter I do think the default stance at Wikibooks is sensible. The point is just that I don't expect such decisions to be smooth and uncontroversial. A somewhat related concern would be drama arising from open source politics, as highlighted by this comment. | |
| Aug 31, 2015 at 17:51 | comment | added | Kevin Montrose StaffMod | @duplode if the community cannot be convinced the alternative is better, why should the community delete it? And vice versa, if the community is convinced to shutdown a section how (and why) would we stop them? I know we're discussing hypothetical cases, but I have trouble imagining a scenario where a strictly superior alternative is presented and it fails to convince a majority of contributors to move. Put another way: we already delete sites, tags, users, and questions. I'm not too concerned about documentation being somehow (and uniquely) un-delete-able if merited. | |
| Aug 31, 2015 at 17:44 | comment | added | duplode | @KevinMontrose "[If] documentation everywhere else on the internet [becomes] better than we could ever provide then Mission Accomplished. I'll delete the code myself." -- That might not be so simple. A regular occurrence at Wikibooks are deletion requests along the lines of "we moved the book to a more appropriate platform, can you delete the obsolete copy here?", with the default reply by the community being "The CC license is irrevocable, we might develop the text in a different direction, there is no reason to delete it". How would we handle such scenarios here? | |
| Aug 31, 2015 at 17:02 | comment | added | Kevin Montrose StaffMod | If the end result of SO documentation is "documentation everywhere else on the internet is better than we could ever provide" then Mission Accomplished. I'll delete the code myself. More practically, I expect that if there's no demand for documentation for X (because X's docs are good) nobody will ask for them, and nobody will create them. | |
| Aug 31, 2015 at 17:02 | comment | added | Nick Larsen StaffMod | @Bergi All of the documentation written on SO will be licensed the same as all of our other content, CCWiki, we won't even own it, and anyone can reuse basically however they want to as long as they provide attribution to the people who wrote it. I don't think control is a real issue here. | |
| Aug 31, 2015 at 16:48 | comment | added | Bergi | @NickLarsen: "In the long run, we would like to be the official source of documentation for all the things." - that's exactly what I'm concerned about. It would become a single point of failure, and a single point of control. Diverse and decentralised systems are safer and fairer. I'd love if you help to provide 21st-century-adequate documentation tools to the developer community, but I wouldn't like if they're hosted by a single company. Even if it's one that is not turning evil. | |
| Aug 31, 2015 at 16:22 | comment | added | enderland | @JonEricson in my experience, the reason Stack Overflow is useful is because it is a practical answer to a practical problem. Examples/documentation do not provide that almost universally - what is useful is, "I want to do X" or "I have a problem with X" where X is specific enough to be what I want. When it's, "here's a lot of information about X" and I just want a single piece of it, I have to read through a lot of useful-but-not-what-I-need information. | |
| Aug 31, 2015 at 16:18 | comment | added | Jon Ericson StaffMod | One of the problems I have with even really great documentation is that it tends to lack real-world examples. Lately, I've been using Google to find out how to use language features that I haven't fully grasped. Often one of the results is a Stack Overflow question. I'm biased, but the answers to a real world question tend to provide better help than the often abstract official documentation. Examples are the overlooked (and I think revolutionary) key to this proposal. | |
| Aug 31, 2015 at 16:02 | comment | added | Nick Larsen StaffMod | @Stijn No. We looked at the open source aspects of it and frankly it's still a lot of work to edit documentation via that route. Of course if a project owner wants to maintain the control of their documentation, then there won't be anything we can do about that, but our intuition is that it will prove to be a negative over time. Any content on SO will be new content, in whatever format we end up landing on with the possible exception of a project owner blessing the content on us, in which case it will still have to be converted to our format. | |
| Aug 31, 2015 at 16:00 | comment | added | Vogel612 | @JacqueGoupil this site looks interesting, but only to *.js users. all other programming languages seem severly underrepresented there.. | |
| Aug 31, 2015 at 15:59 | comment | added | user247702 | @NickLarsen Some documentation, e.g. the official D Programming Language documentation, is completely open source. Do you also plan on hosting that content on SO? | |
| Aug 31, 2015 at 15:57 | comment | added | Shog9 StaffMod | These all seem like really good problems to have. In that any problem that arises due to having too much good documentation is, in some sense, worth having. | |
| Aug 31, 2015 at 15:56 | comment | added | Nick Larsen StaffMod | In the long run, we would like to be the official source of documentation for all the things. That's a very long term goal. We think that the changes we're making to documentation's unit of work, making it community editable, and the training aspects it brings to the rest of Stack Overflow are keys to its success. So, frankly, all the things should eventually be documented here, but for the beginning we want to fix the worst parts. | |
| Aug 31, 2015 at 15:54 | comment | added | Martin Smith | But won't it be survival of the fittest? If people find the vendor docs are better they will link to that instead. | |
| Aug 31, 2015 at 15:53 | comment | added | Domino | This is why I'd rather go to devdocs.io then having a wiki on SO. | |
| Aug 31, 2015 at 15:52 | comment | added | Michael Doye | It could end up being something similar to the sponsored tags - companies may opt to have their docs on SO | |
| Aug 31, 2015 at 15:50 | comment | added | user3373470 | I did not think about this... I think you brought up a great point. I think, maybe, we should group questions most likely asked in a single place. It is similar to the original idea, but I still think links to official documentation is better. Links are always updated (for version changes), and like you said -- you can't CC something that was already created by someone else. | |
| Aug 31, 2015 at 15:46 | history | answered | user247702 | CC BY-SA 3.0 |