I read the tour page on Documentation and it looks to me like it is meant to document errors and such things. That seems broad to me. Could anyone explain exactly what it is and how it's going to be used?
-
101The million dollar question...that everyone fears to answer.– JonHCommented Jul 27, 2016 at 18:58
-
3Have you read the announcement? The long answer is, Documentation is what the community makes with it. We are working on providing a framework and have some ideas about how it'll go, but ultimately it'll be up to contributors to shape it.– Jon Ericson StaffCommented Jul 27, 2016 at 19:07
-
2A similar question was on my mind, but surely one can learn more than "document errors and such things" from the Tour page?– JeroenCommented Jul 27, 2016 at 19:18
-
See meta.stackoverflow.com/a/329486 and meta.stackoverflow.com/questions/329291– jscsCommented Jul 27, 2016 at 19:21
-
1I also have no idea what it is. Am I supposed to be going to people's answers and click some button to add a documentation section for the classes that are in their answer?– Don RhummyCommented Jul 27, 2016 at 19:23
-
65@JonEricson: "Documentation is what the community makes with it." But the community does not have the power to control the structure of documentation. We can only fill in the blanks in a form letter; the form of that letter is defined by you. So it's entirely reasonable to ask what those blanks mean.– Nicol BolasCommented Jul 27, 2016 at 19:42
-
1Related: Trying to understand Stack Overflow Documentation– ThisSuitIsBlackNotCommented Jul 27, 2016 at 19:46
-
28It's a new toy that has "some assembly required" but there were no assembly instructions or pictures in the box. Hundreds of people try piecing it together, each with their own vision of what it should look like.– charlietflCommented Jul 27, 2016 at 21:11
-
11In short, it's crap !– adeneoCommented Jul 27, 2016 at 22:23
-
3@charlietfl ... and fighting with each other when they assembled it The Wrong Way™.– BraiamCommented Jul 27, 2016 at 22:23
-
11@JonEricson - It sounds like really ridiculous. It's like saying: we have created an online word editor and have some ideas about a plot, but ultimately it's up to you to write a book. You will be doing it altogether, having no idea what others are doing, stepping on each other toes but at the end it will all work out.– PM 77-1Commented Jul 28, 2016 at 16:10
-
10stackoverflow people say Documentation is here to stay, and there are partners (other companies/projects) involved in the Documentation thing (probably why they insist it's here to stay). I think somebody(s) at SO have something in mind for what Documentation is supposed to be. Funny that the people actually writing the documentation seem to be the last let in on the secret.– hatchet - done with SOverflowCommented Jul 28, 2016 at 20:07
-
5This is documentation.– Andras Deak -- Слава УкраїніCommented Jul 28, 2016 at 23:03
-
good question..– Giorgi MoniavaCommented Jul 29, 2016 at 7:13
-
doesn't give me any reputation! I wouldn't use that...– Raja SimonCommented Aug 1, 2016 at 9:04
2 Answers
"Official answer"
This is "the official version" of what Documentation is:
Documentation is broad, and it is a general reference. You aren't documenting a specific problem you're facing, you're helping others deal with an entire class of problems by documenting.
These resources haven't had a place on Stack Overflow, Documentation gives them a home.
It's all about examples.
Examples, examples, examples - show beats tell. In Stack Overflow Documentation, examples are the star of the show. Anyone can add one, so good topics will eventually have several useful examples. And much like answers on Stack Overflow, the most helpful ones will usually be voted up to be right on top
What it is right now
It's really hard to tell what it is, or what it isn't, but I can tell what I think it is right now:
- The perfect way to get easy reputation by making almost no contributions at all.
- A place to find a lot of code snippets, some of them brilliant, some of they completely wrong.
- A magical place where if you go into a page, and go back the next day it might be completely different because making edits on it is extremely easy for everybody.
- The place where people who put effort in creating good documentation go to bang their head on their desk because an example got vandalized after they rejected 20 awful edits on it and now they have to roll it back, for the 5th time.
What it could be, after a lot of work on it
A documentation system oriented for programming with peer review where everybody with an internet connection in the world can learn and contribute, updated constantly with a reputation system that rewards valuable community members who put their effort into making it work.
Which potentially could be extended to many other areas such as science, and be transformed slowly into the "knowledge base of humanity" (a.k.a. Wikipedia with reputation).
-
11Dilemma: I'd really like easy access to the 10,000-rep moderator privileges (!!!), but when I actually tried Documentation during the closed beta, it just didn't seem interesting or worthwhile, and I just can't quite bring myself to spend time there again. What to do, what to do.... Commented Jul 27, 2016 at 22:37
-
5First though "Oh god, not another rant" … then burst out laughing … "magical place", "bang their head on their desk", "20" (!!), "5th time" … Thanks for ranting with humor at least :-)– bwoebiCommented Jul 28, 2016 at 1:50
-
@bwoebi I've been trough that myself, I rather take it with humor than getting mad :) Commented Jul 28, 2016 at 2:18
-
2++ it really does have the potential to be amazing, but I swear if I have to reject one more Entity Framework topic request from the C# language, I'm going to scream. Commented Jul 28, 2016 at 10:37
-
-
-
5I confess I didn't actually read your answer before writing mine. Partially, I expected a rant and partially I didn't want to be writing in a reactionary way. But I needn't have worried. This is a fine (and concise) answer. Thank you.– Jon Ericson StaffCommented Jul 28, 2016 at 21:07
-
7"Wikipedia with reputation" - man, I'm glad Wikipedia doesn't have a rep system. Commented Jul 28, 2016 at 23:47
We've tried to explain Stack Overflow Documentation in the tour, the blog post announcement and the meta announcement. If after reading all that you are still unsure about what the feature is for, let me try another approach: long, wandering personal anecdote.
For two thousand years encyclopedias were outrageously expensive. The only people who could read them were either extremely rich or in the business of copying books. As technology advanced, the price of reproducing books dropped and more people were able to get their hands on compiled volumes of knowledge. By my grandparent's generation, encyclopedias were sold door-to-door as subscription service (starting with Volume 1: "Aalto—Arithmetic"). Competition and technology drove down the price to the point my parents bought me an entire set (World Book (used), if I recall correctly) when I was in junior high. The year after I graduated high school, Microsoft released an encyclopedia on CD-ROM, which opened the doors to even more people. Including the cost of the PC, even that was out of the reach of many, however.
Then Wikipedia (plus Google) changed Encyclopedias forever. Not only has the cost dropped to essentially free for readers, the barrier for entry to contribute evaporated. Instead of hiring top experts in the topic, as traditional encyclopedias do, Wikipedia remains largely open for anyone to contribute to, which seems like a dubious idea. However, as Joel put it:
The early criticism of Wikipedia: “I went to this article and it was wrong.” By the time you read the criticism, the article has been fixed. There was that year, not last year, but the year before, when every traditional journalist wrote a funny thought piece in their newspaper about something they looked up in Wikipedia and just how wrong it was. By the time their column appeared in print, the Wikipedia article was corrected, making a liar out of the journalist. Eventually they learned to stop writing that story.
So to steal my own thunder, Joel said that stuff about Wikipedia in order to describe Q&A. By any reasonable measure, Stack Overflow did to programming questions what Wikipedia did to encyclopedias. And by "Stack Overflow", I don't just mean the model which can be cloned, but the community of programmers of all abilities who have donated time and effort to create something useful. We try our level best to make the system run smoothly, but the magic is really in you, the people who write and curate the content.
Computer manuals followed the evolution of encyclopedias at a much greater pace. When I was a working programmer, we had tons of printed manuals scattered across our desks and taking up shelf space. A few years ago, there was a massive office shakeup and people were forced to move their stuff from one cubicle to another. (To be clear, this was not Stack Overflow.) Printed manuals found their way into piles in the breakroom with "free!" sticky-notes. I grabbed a few out of nostalgia, but most of them ended up in the recycling because the information is all online now anyway.
Most technical Documentation is in the "Encarta online" stage of evolution. Ages ago, I bought The Perl CD Bookshelf, which, as the name suggests, was a collection of Perl books on CD. Since the content was formatted as HTML, the CD included a little web server so that you could read in your browser. As strange as it sounds, that was revolutionary at the time. Unfortunately, the revolution stalled. If you look at Perl's official documentation, which includes many well-written articles, it's not too dissimilar from pages served off a CD. Being an open source project, there is at least a way to update Perl's documentation, but it's not as easy as editing Wikipedia.
Ok. So we want to do to Documentation what we did to Q&A and what Wikipedia did to encyclopedias, right? Not so fast, cowpoke. Both the encyclopedia and programmer question landscapes were dysfunctional when they were replaced. Stack Overflow launched to replace the hyphen site and a disparate collection of mailing lists and newsgroups. Like many other programmers, I leapt into the stream like a grizzly during spawning season. The system didn't start off perfect, but it was far better than anything else that existed.
To be honest, there is a lot of excellent documentation out there. Emacs has a wiki that can be edited Wikipedia-style and is of high quality. When I run across a problem using Emacs, I often prefer the wiki over the official documentation because it tends to have fresher information. And if you already are comfortable with existing documentation, I'm not sure there's any reason to switch. Plus, it's a waste to duplicate effort when there's no pressing need. Therefore, Stack Overflow Documentation needs to offer something new.
What we hit on was that most technical documentation lacks sufficient emphasis on examples. A number of people we've talked to have had an experience something like mine but with different technologies:
I need to write a query for research I'm doing with SEDE, but I forgot how do something in SQL or maybe don't know if it's even possible.
Google gives me a link to the official documentation, which I click on out of a sense of duty. After several minutes scanning the manual, I give up and scroll to the examples at the bottom of the page.
I hit the back button, find the Stack Overflow link, use the sidebar links to jump from the MySQL version to the SQL Server answer, and use the top answer as a starting point.
The problem with step #2 isn't that the official documentation is bad (or at least that's not the primary problem). Rather, the manual is written from the perspective of someone developing SQL Server and not from a user's perspective. (Meta comment: that's at least part of the reason the resources I linked to in the first paragraph might not work for you.) I don't need to know all the theory of how the feature works or the edge cases or the optional parameters or any of the things it might be important to document. I just need a little reminder of where to start. Even if the question turns out to be nothing like the problem I'm trying to solve, having a bit of working code helps me to move forward.
So, while we'd like to revolutionize Documentation, we're starting off with a humbler goal. When programmers need a snippet of code to demonstrate some language feature, they can search Google, click a Stack Overflow link, and get that code without the distractions of questions, comments or any of the cruft a the top of most online documentation. We are betting the feature on the proposition that programmers will appreciate easy access to good examples.
Now there are a lot of other features we've thrown into the mix because they are things we wish documentation did better as a rule or so that Documentation fits into the Stack Overflow ecosystem. But if you could do only one thing, we'd like you to consider contributing, reviewing and honing examples. Obviously there are other ways to get involved, but the core of the feature is examples by and for programmers.
-
41It might have been better to call it Examples instead of Documentation. Commented Jul 28, 2016 at 20:28
-
5This is exactly how I expect to see SO docs, but.... then when i open a tag i'm instead seeing official docs being replicated. not copy pasted/plagiarized, but duplicated none the less.– Kevin BCommented Jul 28, 2016 at 20:38
-
2@hatchet: I don't disagree with you. The name was certainly the subject (many) intense internal debates. In the end we decided to be a little bit ambitious. It's possible to imagine a future where new projects start off building example-based documentation right on Stack Overflow as the feature matures and it would be a shame to cut that evolutionary path off prematurely.– Jon Ericson StaffCommented Jul 28, 2016 at 20:42
-
13@JonEricson - given that Documentation is rather open-ended, I think it would be really helpful if SO picked a little topic, and did a kick-ass coverage of that topic that shows all you hope this will be. Then we can use that as a model to spread goodness and light. Let's not start with bad and try to evolve that to ok. Let's start with good and evolve that to great. Commented Jul 28, 2016 at 20:46
-
2@KevinB: This is our fault. Between the messaging (which is perhaps unclear) and missing limits and the lack of editorial features and the unexpected enthusiasm of users (both veteran and new to Stack Overflow), there's a lot of content that's in the example section but isn't really an example. We are working to correct those mistakes as I speak.– Jon Ericson StaffCommented Jul 28, 2016 at 20:47
-
16@JonEricson: "the bigger issue is that we really don't want to tell you what to do." The problem with that is that you are telling us what to do. You've called it "documentation". You associate documentation with "tags". Each tag has a number of "topics". And each topic has a number of "examples". These words give people ideas about what should be where. And it gives people different ideas. And in most cases, those ideas are different for different people. You're telling us to build whatever we want, but only within this very inflexible structure. Commented Jul 28, 2016 at 21:05
-
18It's frustrating. I want to help clean it up, add quality content, etc, but when i go to clean it up, i feel like a jerk because i'm deleting a lot of content contributed by other users that simply saw the documentation as something I did not. But by not defining what it IS supposed to be, maybe I am being a jerk and shouldn't be trying to enforce what I see docs as being, because it isn't defined. (but now it kinda is, i guess?)– Kevin BCommented Jul 28, 2016 at 21:08
-
6After the chat ban by SE employees and tone of other posts I read which felt like SE was saying "We've explained it enough - you're just not reading it or its your fault for not getting it". I expected another post of the same tone just pointing to the tour and update that I have already read. Instead, this finally explains the scope and goal of SOD plainly. I'm still not convinced this is a good direction for SO but this at least convinces me to give it, and SE employees, some time to see if (a big if) SO can improve the UI, rep, and other problems. Commented Jul 29, 2016 at 0:11
-
27I pushed super hard for the name Examples from the first time I heard about this proposal. Couldn't a highly curated group of Q&A around some extremely narrow thing be bundled together into a form of examples? Commented Jul 29, 2016 at 7:50
-
17"Documentation" gives off a very strong vibe that we should not only be providing examples but lots of prose to explain how everything works - even if you tell me not to do that I'm still going to be inclined to do it because I'm writing "documentation."– Ant PCommented Jul 29, 2016 at 7:54
-
6"Even if the question turns out to be nothing like the problem I'm trying to solve, having a bit of working code helps me to move forward." But isn't this Q&A again, not Documentation? Also there you have bits of working code. Also "... the core of the feature is examples by and for programmers." sounds a bit like a slightly different Q&A, say a Q&E. Commented Jul 29, 2016 at 9:49
-
2@JeffAtwood: That's certainly one way to go. In fact, I was pretty sure that's where y'all were going with this post. Not sure why that didn't go anywhere further, but it seems like no real work has gone into encouraging collaboration. It's early yet, but Documentation has seen lot's of people working on refining content in ways that we rarely see on Q&A.– Jon Ericson StaffCommented Jul 29, 2016 at 16:22
-
8"We've tried to explain Stack Overflow Documentation in the tour, the blog post announcement and the meta announcement. If after reading all that you are still unsure about what the feature is for..." yes, we are. Because nothing there explains what it is. It's a bunch of marketing nonsense that contradicts itself. See here: meta.stackoverflow.com/questions/330289/…– MamutCommented Aug 1, 2016 at 9:30
-
4"@hatchet: I don't disagree with you. The name was certainly the subject (many) intense internal debates. In the end we decided to be a little bit ambitious. It's possible to imagine a future where new projects start off building example-based documentation right on Stack Overflow as the feature matures and it would be a shame to cut that evolutionary path off prematurely." ---- this is why the iPod wasn't called the iPhone. Try again on the naming thunking. Admit you got it wrong, that it's causing massive confusion, and rewind... it's just a beta, after all...– SKOOPCommented Aug 1, 2016 at 16:25
-
4After reading commentary from people that run the show, I think there's an enormous arrogance in play. It seems the powers that be think it's ok to redefine the meaning of a heavily used word (like "Documentation") and attempt to make it mean anything they think or desire it to mean, even if that's causing maximum confusion and disorientation for others. Ironically, generally speaking, this is the biggest problem with documentation in programming, that it's usually written in such a way that only those that already understand it can grasp it. Think of the audience instead of yourselves.– SKOOPCommented Aug 3, 2016 at 23:18