Skip to main content
50 events
when toggle format what by license comment
Mar 20, 2017 at 9:15 history edited CommunityBot
replaced http://meta.stackoverflow.com/ with https://meta.stackoverflow.com/
Jan 3, 2017 at 19:34 comment added Raphael @Gordon My point is that the PHP doc seems to suggest that user-provided examples are useful in principle. Other projects don't have them yet and may therefore profit from SO.docs. "SO.docs for PHP will never reach the level." -- bold claim. Time will tell.
Jan 3, 2017 at 12:55 comment added Gordon @Raphael the PHP Manual is probably the best example why we don't need any SO.docs for PHP. The PHP Manual is comprehensive, explains all the language features and documents the API with examples. It's one of the best manuals out there imo. SO.docs for PHP will never reach the level.
Dec 29, 2016 at 10:29 comment added Raphael Reading this, I remember that the PHP standard API doc has (or used to have) dozens of example on every page; probably because the API (and its documentation) were so poor. So the approach may have merit. But maybe it should be decouple from SO and stand on its own. An example repository is as different from Q&A as discussion is (maybe more) and we religiously push out the latter as far as possible.
Dec 23, 2016 at 0:49 comment added Nicol Bolas @Trilarion: "Actually we could start pointing out all the flaws in Q&A..." The difference is that people actually believe in Q&A as a concept, even if some elements of its implementation are imperfect or leave something to be desired. By contrast, has anyone actually defended the idea of example-first as being an effective means of creating "documentation"? As being a means to create a nice cookbook, maybe. As a means to create something that most people would recognize as "documentation"? No.
Dec 22, 2016 at 22:38 comment added NoDataDumpNoContribution "...instead of creating one[a design] that best fits the content being documented" I actually wonder how one would do that without knowing too much about what people really like to do. I guess it would have to be extremely flexible in order to let people play around with it.
Dec 22, 2016 at 22:13 comment added NoDataDumpNoContribution @NicolBolas "...nobody believes in Docs.SO..." Actually we could start pointing out all the flaws in Q&A (rep, rep whores, homework Qs, redundant anwsers, unordered (just by score), tons of closed questions, missing examples (maybe), ..) and then ask if Q&A is failing (in the long run). I guess in the end there is only one hard criterion: number of users.
Dec 22, 2016 at 22:08 comment added NoDataDumpNoContribution @JeffreyBosboom "...Telling us to build whatever we want within Docs feels like saying we can have any color we like, so long as it's black." I guess this is the gist of it. They invested about a year work of three persons and they are convinced examples centered Documentation is the hit and the structure they have is about right, but they hope the users will provide the content and they trust that the users will find the best way of providing the content within the given framework. In your analogy this means; they bet on black but hope we will choose the most sexiest shade of black for them.
Dec 22, 2016 at 0:07 comment added LinkBerest - SO sold our work I was going to post something but this covers most of why I gave up on Documentation - particularly the huge amount of plagiarization that just ate up most of my time editing/deleting and the fact that I disagree with the "cookbook" format. Examples is not needed and covered by Q&A anyway (which lends itself to examples well anyway IMHO).
Dec 21, 2016 at 13:52 comment added Walfrat If averages/bad users can reviews, they will approve average/bad content and add their own waiting for approbation of their "pairs". This need to be more strict, by definition of the concept of Documentation.
Dec 21, 2016 at 13:51 comment added Walfrat The problem between documentation and Q/A is that even with an average level, you can provide an adequate answer to a question. This is because there are quite a lot of question around the same subject of interest yet they're different and don't always require an expert (excluding the homework & lazy ones still). However with documentation you're supposed to have one single post into one specific topic into one specific tag. By design the only post that the community want to keep can only be the most precise one which can only be redacted/reviewed by experts in their fields.
Dec 21, 2016 at 13:23 comment added Benjol A long long time ago, somewhere on meta, I (or someone else, it was a long time ago) suggested a system which would help facilitate expanding long SO answers into full 'blog posts'. I still think this would create more user engagement and added value.
Dec 21, 2016 at 11:47 comment added user692942 @FrédéricHamidi I wasn't expecting a grammar lesson this morning (even though I use grammarly ). I said it will succeed, doesn't mean I have to agree with it.
Dec 21, 2016 at 11:27 comment added Frédéric Hamidi @Lankymart, I see, I didn't realize you used quotes for... well, quoting, so I thought you were using them as "scare quotes", and I wondered why you wrote success verbatim despite becoming another muck show clearly not being success.
Dec 21, 2016 at 11:24 comment added user692942 @FrédéricHamidi why is that strange? "Experts" was a quote from the answer, succeed wasn't, is this some in-joke I'm not aware of?
Dec 21, 2016 at 11:20 comment added Frédéric Hamidi @Lankymart, you put quotes around experts, but not around succeed? Strange.
Dec 21, 2016 at 11:11 comment added user692942 @JonEricson I have no doubt docs will succeed, but it won't be because of the so-called "experts", they will be long gone. It will because of random uninformed individuals (the kind we have to deal with in SO on a regular basis) writing poor, low quality and in some cases damn right wrong examples. Docs is destined to become another muck show.
Dec 21, 2016 at 9:46 comment added Benjol @JonEricson, accumulating the work of many users into a single long-form article is not a problem (works for Wikis). Seems it's attribution (i.e. rep) which is your problem here. Difficult.
Dec 21, 2016 at 9:06 comment added Tensibai @SGR see this comment above.
Dec 21, 2016 at 8:43 comment added Lundin (Take for example the most classic, canonical example ever written, the "hello world" from the K&R C programming book. It is incorrect and contains severe bugs, for any version of the C language (invokes undefined behavior in C90, won't even compile in other versions). This was written by two supposed experts. Now imagine if someone who's not an expert starts writing canonical examples - it will end badly.)
Dec 21, 2016 at 8:41 comment added Lundin @BoltClock "Examples" is probably part of the quality problem. It takes less technical skill to explain a concept in text than through examples. Because when you write an example, you often have to use various other things that are not directly related to the thing you are trying to explain. But those other things must still be correct when you are writing a canonical example, it requires a whole different level of expertise.
Dec 21, 2016 at 8:23 comment added SGR Do you have a solution @NicolBolas, or are you simply taking your ball and going home? If so, you may as well not post on these updates and I don't know why you bother.
Dec 21, 2016 at 7:16 comment added Jon Ericson Staff @Benjol: That's a fine question. The main reason we rejected longform topics is that it's not really in our wheelhouse. We depend much more on accumulating the contributions of many users rather than asking for big investments. (We do get and appreciate big investments on Q&A. Asking for more seems like robbing Peter to pay Paul.)
Dec 21, 2016 at 6:04 comment added Benjol Dawn or dusk? :) I'm definitely in the "lost interest" category myself, so not sure whether I'm qualified to comment. A bit like Nicol, I'm not even sure I'm onboard with the "mission statement", even though I did play a bit at the beginning. Personally, I'd see much more use in long-form, structured treatment of topics: fsharpforfunandprofit.com is the gold standard.
Dec 21, 2016 at 5:11 comment added BoltClock Mod @Nicol Bolas: Indeed. Even if I get behind it as a concept, it's still poorly implemented.
Dec 21, 2016 at 4:50 comment added Nicol Bolas @BoltClock: "but for as long as it's still called Documentation, ... not contributing to a repository of self-contained examples" The fact that the examples are considered sub-sections of the topic as a whole doesn't help promote the idea that the examples are "self-contained". Nor does the fact that we order examples based on voting patterns.
Dec 21, 2016 at 4:25 comment added BoltClock Mod I'm willing to give example-based documentation a chance, but for as long as it's still called Documentation, people are going to continue treating it like they're writing their own manuals, not contributing to a repository of self-contained examples. And this is a separate issue from experts not wanting to deal with terrible contributions from people who have no idea what they're talking about - we already have enough of a problem with people spreading misinformation in Q&A.
Dec 21, 2016 at 4:08 comment added Jon Ericson Staff @NicolBolas: Q&A was launched in September, 2008 with a little over 50k posts in the first week. The next time we hit 50k+ posts in a week was the week of July 11, 2010. I wouldn't say the drop off was as severe looking as for Docs, but (as I said in the question) it's a pattern we see again and again.
Dec 21, 2016 at 3:40 comment added JonH Because its really not ready. It isnt prime time. It has potential but the UI and terminology lacks. Someone on the team should at least define the terminology and believe it or not actually use the system for a make up example showing precisely how it works. Maybe they can show us the way.
Dec 21, 2016 at 3:38 comment added Nicol Bolas @TigerhawkT3: Personally, I think the difference between what SO faced then and what Docs.SO faces now is really simple: nobody believes in Docs.SO. You see very few posts that are wholly in support of the current direction of Docs.SO. By contrast, while SO had its critics in the beginning, it also had evangelists. People who weren't Joel&Jeff, but ordinary users who still believed in its mission of using Q&A to build a knowledgebase. Where are the true believers in Docs.SO? If Docs.SO is such a good idea, why is nobody defending it who isn't on the staff?
Dec 21, 2016 at 3:38 comment added JonH Shog et all - even if it does fail it was a learning experience. There are some stuff ui ux side you may be able to use in the future. Unless there is a huge change, which i dont see coming or hear coming, it is RIP. These things happen but to be quite honest what got me the most is the ui interactions and the confusion. Even pooking at it today something that would seem so easy is just mind numbing. The number of ways you can minimize or maximize topics or examples. The number of key words being used. The initial inability to comment. The bugs that actually deleted or lost content.
Dec 21, 2016 at 3:33 comment added TigerhawkT3 I was referring only to the initial disinterest, skepticism, or criticism which JonEricson claims SO faced in its early days.
Dec 21, 2016 at 3:28 comment added Nicol Bolas @TigerhawkT3: "SO QA succeeded despite the apparent disinterest, not because of it." Was there actually some "apparent disinterest" in SO? I'm sure there were many who were skeptical, but what we got on Docs.SO was not skepticism. It was 2 weeks of high activity, followed by months of essentially nothing, leading only to a few unskilled people writing garbage or the occasional bit of cleanup. Did Q&A have that, with a flurry of activity, followed by a sharp drop-off, then slowly rebuild itself?
Dec 21, 2016 at 3:25 comment added TigerhawkT3 @JonEricson - Unfortunately, I do not understand why you're not terribly worried about the apparent disinterest. SO QA succeeded despite the apparent disinterest, not because of it. en.wikipedia.org/wiki/Post_hoc_ergo_propter_hoc
Dec 21, 2016 at 3:23 comment added TigerhawkT3 @JonEricson - The introduction of Docs doesn't ease "the difficulty people have transitioning from consumer to producer" any more than you turn a moviegoer into a filmmaker by putting an NLE app on their smartphone, or turn a homeowner into an architect by throwing a pencil at them, or turn a murderer into a judge by hauling them into a courtroom. Producing good documentation requires actual skills in language, writing, organization, and more, not to mention experience, proper tools, and so on, none of which Docs provides.
Dec 21, 2016 at 1:47 comment added Marco Scabbiolo @NicolBolas I agree with you. It is ironic the fact that discussion is the word that stands out from the OP, when the lack of it was what made documentation fail. And I'm not just talking about discussions in examples, the questions SO staff should have asked in meta are: We want to add something like Documentation what do you think?, Is Tag/Topic/Example ok?, How should a topic page look like, etc. etc. Seems to me the business need for more and more users was more important. I've seen Doc fail right after it was rushed into public beta. It went from bad to empty really fast.
Dec 21, 2016 at 0:43 comment added Nicol Bolas @JonEricson: "So I hope you understand why I'm not terribly worried about the apparent disinterest." Your experience with SO and mine are quite different. Yes, I joined up some time past beta, but my experience with forums and other things were very much not "good to me". And my preference for SO was not due to its content, but due to its structure, the way it focused interaction in a productive way. The way it actively fought against discussion and dithering. It was attractive by design, not because of what people did with it. Docs.SO is not that.
Dec 21, 2016 at 0:15 comment added Nicol Bolas @JonEricson: "Your question about what a topic means is common and I think best answered by other creators. I fully expect the topic space of Java will be much different than the topic space of R." And yet, what makes a good Java question is no different from what makes a good R question. Oh, the content of the question will be different, but the structure of it will be the same. If keywords are a good topic, then any language that has such a concept could have a keywords topic. Whereas if it's not a good topic, then no language should have one.
Dec 21, 2016 at 0:11 comment added Shog9 That last comment is key, @Jon - with the caveat that this could still fail of course. Thus far we've been aiming at a somewhat under-served niche in terms of functionality, but whether that's under-served because folks have overlooked it or under-served because it's simply far less important than other features remains to be seen; this is yet another attempt at adding structure to a wiki, something folks have been stabbing at from various angles for 20 years (including 8 years of Stack Overflow); a few have succeeded, a lot have not.
Dec 20, 2016 at 23:54 comment added Jon Ericson Staff @TinyGiant: As a beta user, I can tell you Usenet seemed plenty good to me at the time. I mostly joined because I was curious about this little project Joel was starting. When it became clear that there wasn't going to be proper threading, I was pretty sure the project would fail. The rigid Q&A format simply did not seem worthwhile. Reputation seemed counter-productive at best. So I hope you understand why I'm not terribly worried about the apparent disinterest. ;-)
Dec 20, 2016 at 23:48 comment added Jeffrey Bosboom @JonEricson for the people who know those technologies to decide - if Docs was a free-format wiki, I'd agree with your laissez-faire approach. But you built a system that (to me) strongly embodies cookbooks, with the focus on small code snippets, the lack of high-level organization, and sorting by voting rather than by logical order. Telling us to build whatever we want within Docs feels like saying we can have any color we like, so long as it's black.
Dec 20, 2016 at 23:44 comment added user4639281 @JonEricson Re: drawing comparisons between Q&A and Docs. When Stack Overflow Q&A became a thing, people wanted programming Q&A. It was something that was seriously lacking from the internet. A hole worth filling, if you will. No one is going around saying "We need a place for examples first user contributed documentation!" It is not a hole that is in desperate need of filling.
Dec 20, 2016 at 23:27 comment added JonH I still think rep should be removed ive been against it for quite some time.
Dec 20, 2016 at 23:17 comment added Jon Ericson Staff @NicolBolas: I think you are looking at it backwards. People generally don't care about producing content before they have experienced it as a consumer. The block we are trying to clear away with the discussion tab is the difficulty people have transitioning from consumer to creator. Your question about what a topic means is common and I think best answered by other creators. I fully expect the topic space of Java will be much different than the topic space of R. It's not up to use to enforce, but for the people who know those technologies to decide. This meta can't manage that scale.
Dec 20, 2016 at 23:08 comment added Nicol Bolas @JonH: I've posted many suggestions for how Docs.SO could be better made to achieve what it sets out to achieve. An organizational form that makes sense. Or failing that, provide a consistent and enforced idea of what "topic" means. Others have added ideas of their own, like ditching reputation and/or example voting. But so long as it's trying to be example-focused, I don't believe that it's ever going to actually be as good or as comprehensive as real documentation can be.
Dec 20, 2016 at 23:05 comment added Nicol Bolas @JonEricson: "As I explain in the opening paragraph, I don't think we can know for sure what direction the community is going to take from observing the reaction to launch." You may not be able to say for certain which way things will go. But do you have a basis for saying that things are moving in a positive direction? Because I don't see any evidence that people are out there salivating at the thought of contributing to Docs.SO if it only had a discussion system.
Dec 20, 2016 at 22:43 comment added JonH Nicol i have been through a lot of the beta listening to you. I agree with most of the things you say but what gets me is you dont offer any further resolution or do you even have a resolution? Im not knocking you, I think your posts show you care and you are a smart person. My question is how about stating what changes youd like to see rather than the criticism you have right now?
Dec 20, 2016 at 22:25 comment added Jon Ericson Staff Obviously, I respectfully disagree. I think the point we depart ways is in our disagreement over whether a community will form around it as a community formed around Q&A. As I explain in the opening paragraph, I don't think we can know for sure what direction the community is going to take from observing the reaction to launch. People will give up on even successful communities during the early days. Unfortunately, if you don't believe in example-first documentation, there's really nothing I can do to change your mind. We'll just have to see what happens next.
Dec 20, 2016 at 21:47 comment added Kevin B Maybe SO Docs is just built for a different audience. I'm not sure what that audience is, but that's the only reason i could see SO to still be pushing it.
Dec 20, 2016 at 21:35 history answered Nicol Bolas CC BY-SA 3.0