26 ms·
Introducing Stack Overflow Documentation Beta
- simonswords82 10y agoSo this makes Stack Overflow a library of example code curated by people who already frequent their website. Am I reading that right?
- metakermit 10y agoI think this will be separate from Stack Overflow Q&A, if that's what you were aiming at. SO Q&A will still target specific examples. But yes, the new SO Documentation project will be code examples and explanations curated by presumably many existing SO users.
- JamesBaxter 10y agoIf this gains traction I don't think we'll feel the benefits till a little later down the line. I've contributed a little to the Swift tag but the real advantages come from technologies that don't already have good documentation. I'm considering starting a tag for the enreco HTML -> PDF generator I use quite a lot as the official documentation isn't great.
- Kiro 10y ago> enreco HTML -> PDF generator What is that? Googling it only brings up this comment thread.
- edgarvaldes 10y agoTop result for me: http://www.nrecosite.com/pdf_generator_net.aspx http://www.nrecosite.com/pdf_generator_net.aspx
- JamesBaxter 10y agoMy bad its Nreco
- jbrooksuk 10y agoOdd. Couldn't find blog.stackoverflow.com The Q&A site blog.stackoverflow.com doesn't seem to exist…yet. You can vote for it to be created through our democratic, community-driven process at area51.stackexchange.com, or see a complete directory of all our Q&A sites at stackexchange.com.
- lucb1e 10y agoWhen I click the link, I get the blog post. When I go to blog.stackoverflow.com I get an overview of blogposts. What are you talking about?
- df07 10y agoThe blog was down for a bit and falling through to the generic Stack Exchange network handler, which is what you saw. It should be working now.
- metakermit 10y agoCool new project – I think it might become very helpful one day. Documentation for a lot of open source projects is pretty bad and having to figure out a new contributing workflow every time just to hop in and help a bit is quite problematic. Hopefully, the unified interface SO users are used to will give docs writing a big boost. That said, I still hope they output some sort of GitHub repo of all the accepted changes to make it a bit less walled-gardeny. A CC license is nice and all, but having the content in a repo as well would put my mind at ease.
- aalear 10y agoWe have plans to eventually add Documentation to the data dump we already produce of the Q&A content (and hook it into the API, etc.) If for some reason Documentation doesn't really take off or work and we end up scrapping the project, we'll produce a final dump of all content at that point.
- mattip 10y agoThe CC license used for stack overflow content is horrible. I have asked multiple lawyers what it means for cut-and-pasted code, and have yet to recieve a clear a definitive answer - is it viral when compiled into a binary, or when used in scripts? - how to attribute?
- wool_gather 10y agoThe license for code changed earlier this year: http://meta.stackexchange.com/questions/271080/the-mit-license-clarity-on-using-code-on-stack-overflow-and-stack-exchange http://meta.stackexchange.com/questions/271080/the-mit-licen... to MIT. It's not retroactive, though.
- deleted 10y ago[deleted]
- deleted 10y ago[deleted]
- kyriakos 10y agoGreat idea I especially appreciate the fact that its done by example. A couple of things that bothered me are: 1. The UI needs some refinement. I was looking to find a topic to post about and from my 10 minute browse I realised that if I was meant to find information in this documentation it's really hard to find what you are looking for. After you drill down to a tag it feels "unstructured". Readthedocs layout feels more user-friendly. 2. To future proof the documentation examples should come with a version number they apply to. For example there is PayPal and DropBox API examples which in a few months might no longer be valid.
- alex_hitchins 10y agoRegards to no. 2 in your list, I was thinking something akin to MSDN, whereby one can change the version of the platform in question (Say MS SQL, .Net Framerwork)
- progval 10y agoRegarding #2: I noticed that in Python there are content blocks that can be marked specific to a version.
- donny5 10y ago#2 is actually implemented. Applicable versions are displayed on every page.
- lucb1e 10y agoThe UI needs some big improvements indeed. I toyed around with the site and although I could find my way around when just clicking through some topics, I am still confused as to what the structure of the site is (other than a list of topics, with a list of examples, not hierarchically structured or Q&A style or anything else that would make sense). I'm not sure I could find anything on here if I didn't get there via Google already.
- eric_h 10y agopersonally, google is how I always end up on stack overflow, so I'd imagine the same will be true for this product.
- IshKebab 10y agoThis is awesome. I can't count the number of times I've found an Android function that has almost no documentation. I usually post a question and answer on SO if I work out how it works. I only wish it were organised a bit more like normal documentation - i.e. into classes and methods. Might make it easier to find things.
- krat0sprakhar 10y agoIf anyone is wondering how this looks and is impatient to read the blog post, here's an example Documentation page for Java Streams - http://stackoverflow.com/documentation/java/88/streams#t=201607211226138669707 http://stackoverflow.com/documentation/java/88/streams#t=201...
- elygre 10y agoYep, examples with bugs.
- speps 10y agoWill there be an example of a bad regular expression that could take down a website?
- jstoiko 10y agoThis is cool. It would be nice to have an API for this so that my IDE can pull these examples.
- anotherevan 10y agoWill be interesting to see what the moderation guidelines will be like, and how zealously they are "interpreted".
- RyanHamilton 10y agoAwesome! I've actually been working on a java IDE that allows uploading examples together with the results to a website: http://jpad.io/example/1s/generating-random-int-array-within-range http://jpad.io/example/1s/generating-random-int-array-within... The idea is to build up libraries of examples in different areas, allow easy code sharing and to remove some of the cruft needed. It's good to see stackoverflow hit this "code examples" area better.
- RyanHamilton 10y agoAwesome! I've actually been working on a java IDE that allows uploading examples together with the results to a website: http://jpad.io/example/1s/generating-random-int-array-within.. http://jpad.io/example/1s/generating-random-int-array-within.... The idea is to build up libraries of examples in different areas, allow easy code sharing and to remove some of the cruft needed. It's good to see stackoverflow hit this "code examples" area better.
- lucaspottersky 10y agothere's gotta be an integrated way to copy&paste examples (i.e. via autocompletion/snippet) from SO to our favorite code editor/IDE :D
- grkvlt 10y ago[META] This is popular, but is there a way to notify the mods of duplicates so that conversation doesn't get fragmented? I flagged https://news.ycombinator.com/item?id=12135897 https://news.ycombinator.com/item?id=12135897 and https://news.ycombinator.com/item?id=12136086 https://news.ycombinator.com/item?id=12136086 but I don't know if that's the right thing to have done?
- detaro 10y agolinking to the more active discussion(!) and then flagging is the correct thing. If you do it before other comments have been added, this even flags the post as [dupe] automatically.
- deleted 10y ago[deleted]
- reitanqild 10y agoReally curious to see if this succeeds, fails like discourse or gets overrun by what I consider to be a major destructive faction of nitpicks and deletionists on SO.
- Const-me 10y agoIn my experience, those nitpicks and deletionists only agro at things they don’t understand, like any sufficiently complex question or topic. I think PHP is going to be documented really well, I anticipate hundreds of wonderful examples how to get a substring or format a date-time from MySQL query result. I doubt there will be much content outside of that.
- lucb1e 10y ago> a major destructive faction of nitpicks and deletionists on SO. I've had my experience with them so I get where you're coming from, but you can't say StackOverflow isn't a great resource and perhaps in part because of them. I'm sure and am glad they will have their share in the documentation part as well.
- morgante 10y agoHas Discourse failed?
- reitanqild 10y agoTell me about how it compares in usage to any of the solutions it set out to replace :-) Or tell me about where people are using it to discuss every question that is not fit for SOs questions/answer format.
- pietroalbini 10y agoWhat I'm most worried about is the duplication between the canonical documentation of a project and the StackOverflow one. As the author of an open-source project, I try my best to write a great documentation, and I would be a bit annoyed if people started to add examples to StackOverflow just to gain reputation there instead of contributing to the "official" one. Also, SO is ranked way higher than the smaller-projects' documentation on search engines, pointing developers there. This can be problematic, for example, if a big release comes out and the SO documentation is behind. The documentation for a lot of projects is really bad, I know, but I prefer a solution which doesn't disrupt the work of the mainteiners which writes good and extensive documentation.
- allendoerfer 10y agoI think they should link back to the official documentation wherever it makes sense. They could even automatically import official docs into their system if the license permits that and a standard tool is used.
- angry-hacker 10y agoThey would still outrank your official docs. Just like wikipedia, they add nofollow to their links, meaning the links mean nothing in the eyes of Google. Instead of having some innovation when it comes to spammers, wikipedia and stack overflow punish the original content creators.
- greglindahl 10y agoSearch engines make their own opinions about nofollow links.
- deleted 10y ago[deleted]
- caf 10y agoThey don't add nofollow on all links: http://meta.stackexchange.com/questions/111279/remove-nofollow-on-links-deemed-reputable http://meta.stackexchange.com/questions/111279/remove-nofoll... ("Starting today we will be removing nofollow on links within posts that hit a high enough threshold to be considered reputable. The details will remain somewhat vague at the moment to discourage gaming of this feature.")
- jackcarter 10y agoI hope they release a private enterprise version, like they have for StackOverflow[0]. I'd love to host this on-prem to document my company's codebase. Anyone know of a similar solution that's available now? [0] http://meta.stackexchange.com/questions/16054/is-the-stack-exchange-engine-available-for-use http://meta.stackexchange.com/questions/16054/is-the-stack-e...
- deleted 10y ago[deleted]
- evoltix 10y agoI would definitely be interested in this as well.
- deleted 10y ago[deleted]
- allendoerfer 10y agoI think a big problem is user motivation. On Q&A sites you get the reward to directly help someone and have a conversation. This is missing for documentation. I wonder if their gamification is enough to motivate people or whether they have to find a deeper human desire that they build into this and satisfy.
- senex 10y agoBesides karma, I wonder if users will be motivated by career opportunities? Contributing to documentation could be a good signal to recruiters that are looking for experts in a particular technology.
- deleted 10y ago[deleted]
- troymc 10y agoThis is awful, another trick site that fools people into doing work that they could be getting paid to do, all for the joy of getting some "karma." Well kids, karma ain't gonna pay the rent. If you want to get experience volunteering to write documentation for software, then find the existing official documentation and add to that (or start it, preferably in a repository close to the actual code). Any profits that get made off this "documentation" (i.e. incoherent bag of examples) will not flow to the community or company behind the software in question. It's a parasite, leeching off the success of other projects which it neither created nor cares about. How did they get corporate partners for their launch? That's easy. It looks to those companies like free labor.
- edgyswingset 10y agoYou're free to not use the site, I guess.
- fapjacks 10y agoRight. Until your documentation gets co-opted by this external, third-party, for-profit company. The Q&A site is fantastic. But this new documentation thing is going to be a nightmare.
- orf 10y agoThe same could be said about the general idea behind Stackoverflow, except it's wrong. Sure, it's "free labour for internet points" but so is posting a project to Github and wanting stars. You're forgetting that it genuinely helps other people in your industry. Stackoverflow is an amazing resource for programmers, pretty much every question I type into google relating to a library or some software comes up with 3 or 4 stack overflow links that actually help me. If they can take the masses of questions which basically form ad-hoc documentation for tonnes of projects and put them in a cohesive place then how is this a bad thing? Because people don't get paid $0.01 per post or something? Perhaps any advertising revenue from the docs site could go towards something good, would this be better?
- 10y ago
- akavel 10y agoIn the footnote of the post they wrote they considered naming it "SO Examples", but didn't. For me at least, using "SO Docs" to name the site is actually much more confusing. As a result, for the whole post I thought it is a dynamic manual, with per-function docs and examples. Only after browsing to the actual site I slowly realized it's not a manual: it's rather a "book" of examples. A list of HOWTOs, speaking in a language of yesteryear. As far as I see, it's impossible to build a MSDN in it. I couldn't add full documentation for one of Go packages here — borders cross vague, overlapping concepts, not clearly cut packages. To make it clear: I don't want to deny that it can be useful — suppose as examples for learning; but when looking for docs, I like being able to browse them systematically. So, two possibilities: either something revolutionary I didn't fully grasp yet — or Examples, not Documentation. For now, I much prefer the model of Go docs, MSDN, or PHP manual with user comments — if talking about docs.
- olivier1664 10y agoI agree with you, I was expecting a set of concurrent tutorials. I was hoping a coding version of http://www.mobafire.com/league-of-legends/champion/renekton-68 http://www.mobafire.com/league-of-legends/champion/renekton-... where author trying to answer their best on "How to start coding?" and user reading and voting for their favorites tuto.
- akavel 10y ago(replying to self) Ok, I see now one area where it actually seems to make much sense and looks like it can work very nicely: for stuff like git, vim/emacs, bash, etc. Generalizing, I'd say: for apps/services which happen to have abysmal, irregular UX/API, which often accrued/emerged instead of being designed. A classical reference manual just doesn't work good enough for them, because the "natural" edges/borders in the API are too random and accidental. "SO Docs" as it is now can then organize the chaos, while making it easier to categorize & improve than a typical wiki. http://stackoverflow.com/documentation/git/topics http://stackoverflow.com/documentation/git/topics http://stackoverflow.com/documentation/vim/topics http://stackoverflow.com/documentation/vim/topics
- rohanpai 10y agoThis is super cool! I am interning at Sourcegraph and we have heard devs want better usage examples too, so we automatically show all uses of any function check out: -https://sourcegraph.com/github.com/golang/go/-/info/GoPackage/net/http/-/NewRequest https://sourcegraph.com/github.com/golang/go/-/info/GoPackag... - https://sourcegraph.com/github.com/golang/go/-/info/GoPackage/encoding/json/-/Encoder https://sourcegraph.com/github.com/golang/go/-/info/GoPackag...
- newman314 10y agoI understand this is (for now) for devs. I would love to see an equivalent (including private offering) for infra. Getting people to document things on the infra side is deplorable in general and I would love to try anything that helps improve that.
- specialist 10y ago"infra"? Quick google search did not illuminate me.
- newman314 10y agoInfra as in infrastructure....
- michaeldwan 10y agoI like the concept (reminds me of gobyexample.com) but this really isn't documentation. Instead of more code snippets I want high quality annotations (like snippets!) atop official documentation. If more people were driven to canonical docs but with a guiding hand I think we'd see more people actually understanding the code they write.
- giancarlostoro 10y agoLike genius.com but for code documentation? :) Edit: Apparently they do it already: http://genius.com/web-annotator http://genius.com/web-annotator
- makecheck 10y agoI feel like this might be best used to document unexpected behavior or stupid things that maintainers may be too proud to acknowledge in their official manuals. It should not be used to add redundancy. And it should not be used to accumulate cruft that doesn’t belong in any manual or list of examples. People have already gone for low-hanging fruit; for instance, do we really need examples of how to initialize a list?
- iamrohitbanga 10y agoCan we use existing SO answers to curate documentation?
- rudedogg 10y agoStack Overflow's point system is really annoying. I've been programming for around 10 years, but because I don't participate much I can't even comment on an answer. A month or so ago I was stuck on a problem and thought I'd go through a tag for something I'm familiar with, and submit some answers to try and get enough points to be able to fully use the site. One answer had a new programmer following a tutorial and using an old method signature. I commented that the tutorial he was following is out of date, and listed the correct method to use. The person downvoted my answer, and then pasted (basically) the same code as the answer to his own question and accepted it. I know I just had bad luck in this case, but it's pretty frustrating. Not allowing a user with low points to do some functions makes sense, but let them submit content and allow other users to determine if it's useful. I could have (and wanted to) comment on dozens of answers, which would of helped out a lot of people and saved them time/frustration.
- jsmeaton 10y agoNot being able to comment at low karma is a cause of low quality answers from new users. They post answers that should be comments, and get down voted to hell. I think account age should also factor into a few of the low karma thresholds like being able to comment.
- Flimm 10y agoI remember that phase as well. It was frustrating, but it was worth it. Don't waste your time on the front page, just post questions and answers that are personally useful in your work, and eventually, you'll get the 5 upvotes needed to be able to comment everywhere.
- krick 10y agoI really don't want people to start using something like this instead of improving the official documentation. I hate the fact it probably cannot be helped. To "do the same thing for docs that we did for Q&A"? Yeah, except there just was no sane platform for Q&A before. And for docs there is, you know… the docs!
- 0xffff2 10y ago"The docs" are remarkably inconsistent between projects. "The docs" for C# really don't need any help, "the docs" (by which I mean the AFAIK unofficial cppreference.com) for C++ are fine. But even major languages like Python don't have the greatest documentation, never mind the thousands of libraries out there that have wildly disperate levels of official "docs".
- witty_username 10y agoEven then, often docs just cover the API and functions and fail to give an idea of "how can I use this?"
- krick 10y agoExactly, and this should be fixed individually per project. If this is open-sourced project, you can contribute to the docs. If not — well, if not protected by some license, there will be side-projects with documentation, or you can make your own. But there should never be competition between actual documentation and some fucking for-profit organization, exactly for this reason: the documentation often is bad, and this can, and should be fixed.
- jcastro 10y agoAnyone know if there are plans to roll this out to other stackexchanges? Would love to have this on askubuntu.com.
- d2ncal 10y agoWhile this sounds like a good idea and will probably do well, it also centralizes more critical information and access to one for-profit company and product. I really wish that we as a community would spend more effort towards better, decentralized systems.
- greggman 10y agoI'm actually very conflicted about Stack Overflow in general and of course the new documentation section as well. For whatever reason I answer many (most?) of the WebGL questions. At some point I felt I needed to make longer form answers with better working examples so I made http://webglfundamentals.org http://webglfundamentals.org But, now there's this huge conflict. I spent a couple hundred hours on making webfundamentals.org but when someone asks a question on stack overflow I'm not supposed to just link to whatever I wrote. I instead I'm supposed to effectively transfer all my content to SO. Something about that just feels wrong. SO is making money from the content I created which feels a little weird (yes I know I get other people's content back). Also, while I get that SO's gamification is part of what has made it so successful it's also feels like it turns many things into a competition. I try to tell myself don't worry about those points I'd be lying if I said they didn't affect me at all in various ways. Taking all that and adding to documentation, as an example, when I contribute to MDN I feel like I'm doing something purely positive. But if/when I contribute to SO Docs I already know I'm not going to feel the same. One reason is because SO Docs will be making money from my work. The only thing I get in exchange is some "score" on my name I can maybe use to get a job. Maybe that's a fair trade since I don't get a score on MDN? I'm not sure how to make my point. I love that I find answers on SO but something just doesn't feel right and I don't know how to express it.
- Flimm 10y agoLinks to what you wrote are welcome on SO and always have been, but link-only answers are not. Just summarise what you link to, and then recommend the link for the full answer.
- ofcapl_ 10y agolooking forward for some standarized integration with github's wikis
- bouh 10y agoI really hope that all open source documentation quality will increased by adopting such kind of tools. The fact that SO is used an informal documentation was a strong signal that there were much improvement to be done. I am just sad because I wanted to work on project like that :'(. Great job SO !
- tongcx 10y agoIt would be nice if there is SO for business. Lots of companies have terrible internal documentation, Q/A tools.
- pinky07 10y agoOdoo Q&A is an open source clone of stackoverflow: https://www.odoo.com/page/community-builder https://www.odoo.com/page/community-builder It has three mode: forum, Q&A (clone of SO), share links (like HN)
- tongcx 10y agoVery cool. Would be great if three functionality can be supported: transient chat, persistent Q/A and persistent documentation. The same for Stack Overflow. They may make a big profit if business start to use it.
- vorg 10y agoDidn't see the word "test" in the article (except once talking about beta testing S.O.'s new product). And the word "test" isn't in these comments either, so... Will updated examples be run through a program testing them in some way? If not a full run within a playground-style environment, then through a type checker? And will the examples be tagged with version numbers? Some programming languages are notorious for changing syntax and/or semantics between minor versions.