270

If you have told us (or privately thought) Documentation isn't working: You are correct. It isn't. Yet.

Since early on in the private beta of Documentation, we’ve used a simple, rigid structure:

Tags => Topics => Examples + optional sections

At the time, users wondered if this was the right structure. Since Documentation is a grand experiment, we figured we’d wait to see how the structure gets used and adjust as needed. But rather than being a step in the right direction, tags and topics were just getting in the way. We didn’t address the problem partially because we focused on other broken features and partially because we hoped the current system would pan out.

At long last, we’ve got the message: fundamentally the structure we provided isn’t working and the artifacts being created don't serve users particularly well. This isn’t something we can address by tweaking a few features; it’s the foundation of the entire product. Let’s work together to find a way of organizing and creating Documentation that’s better than what we have now and, perhaps, revolutionizes the entire genre of documentation!

If you want to cut to the chase, read down to the “What happens next section?” below.

How we got here

I’m sure you’ve heard the (misquoted) saying “If you build it, they will come.” As many people over the years have pointed out, it ain’t necessarily so. Plenty of creative people have built stuff that never gets used by anyone not related to the creator. Typically, the moral is that if you want people to use your creation, you gotta build it and sell it. Ultimately people need to have some use for the thing you built or it’ll go unused.

Documentation isn’t a Field of Dreams story. There was no mysterious voice telling us to build it. Instead, after a good deal of success in community-driven Q&A, we scouted out other ways for our community improve upon existing tooling so that developers everywhere can benefit. Having a product that works and that millions of developers depend on every day has one significant drawback: it’s tricky to make structural changes. As Shog9 wrote:

So a few years back, some folks within the company decided to push in a different direction: if we can't experiment on the main Q&A system, let's build new systems, and test ideas that way. Let's throw a whole bunch of pasta against the wall & see what sticks. Will it be mentoring? Videos? Teams? Stories? International sites? Documentation? Dancing?

Kevin Montrose spent a good deal of time looking at what's missing in existing programmer documentation. He proposed the main thing developers struggle with is finding practical and immediately-useful examples. After quite a bit of internal debate, he pitched the idea on Meta. Folks seemed excited about the concept, so we built a system for people to contribute and maintain example-first documentation, and opened it to a private beta. After months of intense work and user testing, we finally were ready to launch.

So we built it and my personal fear was that nobody would come. I need not have worried. In the first ten days, nineteen thousand people tried out Stack Overflow Documentation (beta). Some people got the concept and others didn’t. We fixed lots of (in retrospect) obvious problems and created new ones for ourselves. Despite the predictable drop in participation over the next few months, it felt like we were on the right track. After some initial hiccups, people were able to contribute new content and get it reviewed. Spot checking approved changes showed they measurably improved the quality of topics. Most of the topics were not to our community’s exacting standards, but we could see how they might get there.


If this were a movie, the soundtrack would get ominous and there would be gathering clouds in the background. It’s as if we had a cornfield, purchased a bunch of tools and building materials, and invited all comers to make something. At first the sounds of labor are comforting as it means things are getting done. But what, exactly? And can it reasonably be called Documentation? And did we provide the right tools?

We read feedback on Meta and conducted usability tests to find out. The results were . . . inconsistent. You see each tag is its own silo and it’s not easy to navigate from, say, Ruby to Ruby on Rails. And within each tag, topics are their own silos. So people who use tags or topics that are well written and informative will have a different impression than those who have mostly seen examples with glaring problems. The plan was that people would start seeing Documentation via Google searches and propose changes to fix problems. While we are starting to see that happen, it doesn’t seem like it will do enough to produce the exceptional artifacts we’d like to see.

One concern we keep hearing is that the structure of Documentation isn’t working. Some users (both on meta and in interviews) told us our structure was too sterile and generic. Others told us it was too rigid and specific. Nobody's quite sure if we want API-level documentation or tutorials or cookbooks or something else entirely. The optional Syntax and Parameter sections made sense to some and were head-scratchers to others. By attempting to serve all sorts of technologies and all types of documentation and all levels of users, we managed to serve none particularly well.

What happens next?

So we are going to try something different. Instead of giving users a blank slate and a fist full of chalk, we’re going to sketch out (with your input) some documentation blueprints. Initially, we’ll prototype what a page of Documentation could potentially look like for just one technology. We’ll test it with Stack Overflow users, our employees, and outside technical writers to get critical feedback. Once we have one artifact that meets our expectations, we’ll see if we can extend the structure to a few more technologies. By starting from the ground up, we hope to find a rich and flexible way to structure Documentation.

If this sounds a little vague and hand-wavy, it’s meant to be. It won’t help to fall into the same trap of completely creating the product and then soliciting feedback. Instead of developing incrementally, we’re shifting to a true iterative approach. To quote Jeff Patton’s Don’t Know What I Want, But I Know How to Get It:

By incremental development, I mean to incrementally add software [over] time. Each increment adds more software—sorta like adding bricks to a wall. After lots of increments, you’ve got a big wall.

"All in all it's just another brick in the wall"

By iterative development I mean that we build something, then evaluate whether it’ll work for us, then we make changes to it. [We're] building expecting to change it. We never expected it to be right. If it was, it’s a happy accident. Because we don’t expect it to be right, we often build the least we have to to then validate whether it was the right thing to build.

"Woman in pastoral setting"

I’ve used the two figures above for a number of years now to help illustrate the concept. Artists work iteratively. They often create sketches, decide to create a painting, create an under-painting showing colors and form, then eventually begin finishing the painting.

In our first draft we’ll create some Internet pages documenting parts of Transact-SQL. There are several reasons for this:

  1. It’s a technology many of us in the company use on a daily basis and many others are interested in learning. This will give us the widest possible internal audience to test our artifact on.

  2. We identified shortcomings in existing T-SQL documentation (both official and from third parties).

  3. The Stack Exchange Data Explorer (SEDE) provides an obvious way to demonstrate T-SQL concepts. We also have a wonderful SEDE tutorial which was written by a community member for inspiration.

  4. After some debate we figured it didn't matter too much what we picked as long as we picked something.

Part of the exercise is to figure out what sort of structure works for this particular technology. If we do it right, there’s a good chance the structure won’t work so well for, say, JavaScript, .NET, and Git. But hopefully there will be commonalities and broad categories of documentation we can extract and build on.

Should I keep contributing to the Documentation beta?

Yes, please. Since the next phase of development addresses structure, concentrate on writing effective examples. Even with the broken structure and missing elements, people are starting to take notice. One consistently positive thing we’ve heard about the existing system is that people like the focus on examples. It’s difficult to imagine a scenario where Documentation won’t emphasize examples. When we have a better way to arrange content, you’ll be able to move things around.

How can I help?

We’d like to continue hearing from you about what works and what doesn’t for documentation in general and our beta product in particular. I’m not sure we’ve properly expressed our appreciation for months of feedback in private beta, dozens of users we’ve interviewed, and 1500+ meta questions. It’s been immensely valuable, but also overwhelming. So we’re going to start asking for specific feedback that can help us with what we are working on at the moment. To start, please take a look at this companion meta question: What T-SQL documentation has helped you?

Documentation is very much in beta and it could yet fail. But I gotta say, it’s exciting to be working on something new that has the potential to change how the next generation programmers learn their craft. We don’t know exactly where we are going or what we will find when we get there. No matter what, we’re going to learn something. Come join us on the adventure!

47
  • 353
    Unless you rework docs to be a service that provides product developers with a documentation platform that is smoother and easier to maintain than their own web sites or GitHub readmes or whatever, with a search function that yields more effective results than e.g. Google and is as or more convenient than typing search queries in your address bar, I can't see this ever adding value to the internet; it's a really fundamentally flawed premise no matter how many tweaks you try and make to it.
    – Jason C
    Commented May 18, 2017 at 18:17
  • 117
    I keep coming back to the thought that there needs to be multiple types of pages. When you're documenting a concept, the structure of the page should probably be different than when you're documenting a function.
    – user4639281
    Commented May 18, 2017 at 18:22
  • 23
    @TinyGiant: That's a great insight. I think we mostly focused on functions (hence Syntax and Parameters). We should have known that wasn't going to be universal when we started writing Example Databases and Tables topics.
    – Jon Ericson Staff
    Commented May 18, 2017 at 18:25
  • 19
    I'm not in great shape for reading right now, but is the tl;dr "exactly like before, except we'll provide some examples of what we actually want this time"? Commented May 18, 2017 at 18:28
  • 14
    @JanDvorak: More like: "we're going to test samples early and often". We built the private beta in isolation and didn't change the fundamental structure and elements since. That's a mistake I hope to avoid in the future.
    – Jon Ericson Staff
    Commented May 18, 2017 at 18:34
  • 17
    @JanDvorak "Exactly like before, except a completely different structure (or structures) that the community will have some kind of input in, much more testing and user input, all built off of actually trying to write documentation on a given product then asking people to review the documentation that we've made to make sure that it checks all the boxes." So exactly the same, but completely different. Basically they're keeping the "Examples first" concept, and putting everything else up for debate.
    – user4639281
    Commented May 18, 2017 at 18:34
  • 8
    I've brought up similar ideas in meta but I'll repeat it here now that substantial changes seem more on the table. Utilize the existing wealth of knowledge on Stack Overflow in Documentation. I dislike the idea of having them be silos when there's an extreme amount of overlap between the two.
    – Goose
    Commented May 18, 2017 at 18:57
  • 95
    What @JasonC says on the top was always how I personally thought SO envisioned documentation - a platform that is so great to build documentation with that product owners and advanced devs would flock to it and want to do everything with it and ditch whatever they were using right now - with community contributions, editing, and examples added for flavour. Not just a sign put up on an empty field asking everyone and their dog to "contribute" stuff that mostly already exists elsewhere in the eternal quest for reputation points.
    – Pekka
    Commented May 18, 2017 at 19:11
  • 9
    "Should I keep contributing to the Documentation beta? Yes, please." Wouldn't it be better to start from scratch? It would be easier to be strict about the new content than cleaning out the bad content to fit the new model.
    – user694733
    Commented May 19, 2017 at 8:01
  • 48
    One of the biggest problems with Documentation now is the content. The system has been encouraging poor content, and even if you revise the system, keeping that content will kill any future iterations of the product. If you're going to start over with the idea, you need to start over with the content, or it will look and feel (and be) the same thing with a new GUI.
    – ssube
    Commented May 19, 2017 at 13:12
  • 12
    I don't know if anyone suggested this here yet, but I'd like to see any and all reputation-giving incentives removed, or Docs should get a separate reputation counter. I'm all for rewarding people who contribute but only those whose contributions are for the sake of helping others not for racking up points by copy-pasting in other documentation on the Internet.
    – SeinopSys
    Commented May 19, 2017 at 13:28
  • 37
    @ssube is correct, easier to find examples that are wrong is actually making the internet WORSE. as long as the content is W3Schools level, changing the navigation/organizational structure will do nothing to make the content more correct. but no one seems to even offically acknowledge that this is a fundamental problem.
    – user177800
    Commented May 19, 2017 at 14:24
  • 14
    enables creation of good, useful content is not the same as eliminates less than useless incorrect information, it still perpetuates the Balance Fallacy.
    – user177800
    Commented May 19, 2017 at 15:49
  • 43
    Rename it Examples instead of “Documentation”. As meta.stackoverflow.com/questions/303865/… explains, fundamentally what’s not working and never going to work is that y’all gave the thing the wrong name to begin with. The rest of the issues are symptoms of that fundamental mistake. Re-brand it as Examples and re-work the structure entirely around it being a place for examples rather than “documentation” and it will have a much better chance of success and much better chance of actually becoming useful.
    – sideshowbarker Mod
    Commented May 21, 2017 at 8:06
  • 17
    I still think this whole experiment is like throwing 1,000 cooks into a kitchen, from professional chefs to folks who struggle with boxed mac and cheese, giving them all equal authority, and asking them to produce a well structured menu and delicious meals. I'm curious to see how it goes, but after a couple months of trying, I found the whole experience to be far too frustrating.
    – JDB
    Commented May 25, 2017 at 14:02

25 Answers 25

135

I'm glad to see this new approach. Thank you. I'm also glad to see the first phase of understanding your users (the companion question). Documentation doesn't exist in a vacuum; it exists because there are real people with real needs, and also prior work.

Regardless of subject, there are a few types of documentation, and when it comes to structure one size does not fit all. For example, there's tutorial-style documentation (like that SEDE tutorial), which introduces concepts as needed (just enough, not too detailed) while walking the reader through a progression of examples, which might have iterative cycles. Another type of documentation is the complete, documented example -- something that the reader can download and run himself, that has good comments and then some doc wrapped around it. (I don't necessarily mean one big <code> block; sometimes it's better to go method by method, for example.) Reference implementations are an advanced form of the complete, documented example.

Then there's conceptual documentation, where you explain in more detail what's going on with the different kinds of JOIN, for instance. And -- perhaps less relevant here, but I'll include it anyway -- there's task-oriented documentation, where you provide step-by-step instructions for how to do something procedural like configure Kerberos. What distinguishes task documentation from documented examples is that there should be fewer decision points -- getting that DB web front end up and running might require 37 steps but they're pretty much always the same 37 steps. That's different from doc about how to optimize a query, where you might be teaching a skill instead of providing instructions.

There's also reference documentation -- think API reference or language spec here -- where the focus is on being complete but comparatively terse, but where examples are also valuable. (This is probably not going to be where our best bang for the buck is.)

My point in saying all that is: these different types of doc require different enabling structures. This doesn't need to be a ton of work, but it's something to think about. We probably want something more than "here's a textbox" and less than "here's the schema for our fancy XML representation" -- maybe we just need some templates? Maybe the question about what T-SQL doc has helped people will evoke answers that touch on structure and organization.

One general point: being able to organize content is important. (Even better if it can be sketched out early on, before all the pieces exist!) In Documentation 1.0 examples on a topic were ordered by votes; there's no way to do a progression that way. A tutorial can involve several examples or example fragments, and they need to be orderable. It also won't make much sense for them to be evaluated (e.g. by reviewers) in isolation, away from their surrounding context. That's great for an initial code review, but you also need to be able to answer the question "is this a good example of that thing we just explained?".

20
  • 26
    I think this is the most important question we need to decide on before we start building structure. What kind of documentation do we want to encourage? I went into detail on the needs of different forms of documentation way back on the original Warlords of Documentation post. Commented May 18, 2017 at 21:11
  • 17
    What I need the most is reference documentation. I can find tutorials, conceptual explanations, and step-by-step guides around the internet. However, I've had countless experiences of needing to use (or at least understand) an undocumented (or poorly documented) API. Often my only recourse is to laboriously analyze the source to see what it does.
    – Suragch
    Commented May 18, 2017 at 23:14
  • 48
    @Suragch: Really? Because my experience is essentially the opposite. I can find reference documentation for pretty much any API in the languages I use. But conceptual explanations? Those are much harder to come by. Until I wrote most of the OpenGL Wiki, you couldn't find any of those concepts explained effectively online. By contrast, you could find the ARB's reference docs for OpenGL functions. Now, that doesn't mean that it was good reference docs. But if you want to find out what the parameters of a function do, you usually can. Commented May 19, 2017 at 0:00
  • 1
    @NicolBolas, As an example, take any one of the constructors or methods of Android's StaticLayout. This type of documentation may be enough for expert programmers like you, but it is severely lacking for someone who is learning like me. By comparison, Android's explanations on broader conceptual topics (like Layouts) is quite good.
    – Suragch
    Commented May 19, 2017 at 2:34
  • 5
    @Suragch: But reference documentation is for experts. Or rather, it's for people who have an idea of the concepts already, and just need to know what the functions do and what the parameters mean. It's for someone who's already familiar with the system. Reference docs are intended to be technical and comprehensive. They are not intended to be learning materials. From a quick skim of that link, it seems decidedly... adequate in quality. It's not meant for the neophyte; it's meant for someone who needs to remember how that one function works. Commented May 19, 2017 at 3:09
  • 1
    In order to remember what a function does, one needs to have learned it before. I would be pleased to see a bit more explanation and examples for that initial learning.
    – Suragch
    Commented May 19, 2017 at 3:16
  • 22
    @Suragch that initial learning is probably best addressed by concept and tutorial docs, though. Then when you need to know about that one parameter that's relevant for this weird corner case that doesn't rate tutorial coverage, you'll have the background you need to dive into the reference doc and get your answer. Starting with reference doc is not a recipe for success in my experience. Commented May 19, 2017 at 3:20
  • 1
    Even better if it can be sketched out early on, before all the pieces exist! Say, like how I handled this topic? I wanted to have a "Stat here" sort of index and branch off into the two major areas with a few common topics highlighted and links, providing some organization. Commented May 19, 2017 at 3:29
  • @Draco18s yes, something like that. (I don't know your topic area at all, so I'm just commenting on structure.) Commented May 19, 2017 at 3:33
  • 4
    I understand @Suragch s point. Tutorials often only cover the simple use cases. Often enough you have some kind of disconnection between understanding the simple cases and understanding the finer points up to the functionality you need. Connect that with very sparsely written or not existing API Docs and you are stuck. So for me the problem seems to be that both kind of documentation are missing pieces.
    – Rhayene
    Commented May 19, 2017 at 14:08
  • 8
    @Rhayene yes, agreed -- a mature doc set needs all of: tutorials that cover the basics, rich documented examples that are more advanced (as your knowledge increases you need less of a tutorial style, though elements remain), conceptual documentation that among things enables you to reason for yourself about stuff not covered in examples, and complete reference documentation. A lot of doc sets skip the middle two -- and then they skimp on the reference doc, leaving people wondering "so you did 101; where's 201 and 301 and...?". Commented May 19, 2017 at 14:53
  • 1
    I don't think (multi-example) tutorials are compatible with collaborative editing. Everyone has their own ideas about what examples are appropriate and the order in which they are given. Of course, broad tutorials are likely to get praised on twitter, but long-term, no one can maintain them but their original authors; and late-comers who think concepts should be introduced differently will be accused of duplication if they make their own tutorials to their liking, or of vandalism / edit warring if they rework the first-mover tutorial.
    – Frank
    Commented May 19, 2017 at 15:35
  • 12
    @Frank I've been part of multi-author projects like that, but the key is that there's a roadmap up front. If each person is just doing his own thing it's as you say; if there's someone leading the effort or sufficient structure for the community to lay out and record their plans, and some sort of monitoring, it can work with multiple writers. It is harder, of course. Commented May 19, 2017 at 15:44
  • 1
    I think the idea of different types of docs is exactly what is needed. Rather than sticking with one type though, why not have options. For example, c# could have reference, tutorial and task-oriented document sections quite easily. So perhaps a menu of types per tag would work? Addressing this and then quality of content, and I think this will be a viable platform, perhaps even one where library authors would consider using as the primary source.
    – DavidG
    Commented May 21, 2017 at 15:10
  • 1
    I'm all for multiple documentation structures, or at least classifications when browsing Documentation pages to help me find the type that I want. Commented May 29, 2017 at 7:50
110

Please, please, please consider also to solve what is the major problem of Documentation: quality.

I agree that the current shape is not ideal, and what you are proposing really is better, but even as it is it could work and be great, if the content is of the right quality level. As many already have pointed out, the problem is that so many saw it as a new SO, a new land to be colonized and so "let's start pushing stuff into it and be the next Jon Skeet"! Many time writing useless docs, many times just copy pasting.

So, OK with reviewing the shape of docs, but please also reconsider quality: reputation, peer reviews, privileges. Compared to Q&A, you really need to raise a bar here: it's not A question you are answering, it is THE documentation you aim to write. You need to be 10x more serious and strict.

8
  • 1
    I plainly agree with that point, if anyone can review a post for the topicness. Rightness of a documentation is a total another matter.
    – Walfrat
    Commented May 19, 2017 at 13:13
  • 23
    I think that to have quality, you have to have qualified people who are interested in contributing to the product. Right now the qualified people tend to dislike the structure. I figure that if we work together to make a product that is actually useful and that people want to use, we will get quality content.
    – user4639281
    Commented May 19, 2017 at 16:19
  • 7
    Just fixing the structure won't fix the quality. It can be perfectly structured, easy to use, etc; but if it's full of crap content, experts won't use it, and therefore they won't contribute. We need good quality content to get more good quality content.
    – Blorgbeard
    Commented May 19, 2017 at 18:15
  • 14
    It's probably worth remembering that questions and answers were of extremely mixed quality even in the earliest stages of Stack Overflow. We've managed to increase the overall quality of content by aggressively deleting posts. That will likely be necessary on Docs too, but we really can't put rules into place until we know what good crowd-sourced documentation looks like. In the meantime, you have the authority to propose changes, including deleting entire topics.
    – Jon Ericson Staff
    Commented May 19, 2017 at 18:29
  • 1
    Though even the garbage questions that were fun were still good fun, and not just garbage. Commented May 24, 2017 at 22:42
  • "questions and answers are of extremely mixed quality" NOW in stack overflow. That is the entire magic of SO. Human beings are incredibly good at sifting through a pile of information (some crap, some priceless) on a screen, and finding what they need. That's the entire point and magic of SO. the "documentation" failure was an attempt to be wikipedia, and it's as useless as wikipedia.
    – Fattie
    Commented May 26, 2017 at 12:59
  • I totally agree. In the arrays example specifically, I found all of the information in the official java tutorial on the site.Even the images were stolen and put there. On top of the fact that that info can easily be found elsewhere, it is utterly impossible to quickly use. You need to read large portions of it to understand. I would much prefer to see that example like this, but, unfortunately, that edit was reverted.
    – J Atkin
    Commented May 26, 2017 at 20:41
  • 2
    @JonEricson There are still questions that shouldn't pass review and get a lot of votes, but on the overall situation of SO, this isn't a matter. However, as for the documentation, there won't be tons of topic on each tags but only what is necessary. If we can afford to have some still nowadays "not so good questions & answers", I don't think the problem apply the same on Documentation, since there is for each "case" to have one and ONLY one sample in Documentation.
    – Walfrat
    Commented May 29, 2017 at 8:43
65

Even with the broken structure and missing elements, people are starting to take notice. One consistently positive thing we’ve heard about the existing system is that people like the focus on examples. It’s difficult to imagine a scenario where Documentation won’t emphasize examples.

That's a perfect example of where "people are starting to take notice" and "focus on examples" are working at cross-purposes.

The primary example on the Java Arrays page is a gigantic mish-mash of stuff. It's basically "everything you ever wanted to know about arrays, all shoved into one little box."

Is that what we're supposed to be making? Is that what "example focused documentation" looks like? Because what that page is really is a chapter from a Java book. It's not plagarism, but if you were going to have a Java book with a chapter on arrays, that's kind of what it would look like.

Is this what we are supposed to be building? Tutorials or chapters/sections in a book?

That's the biggest question we need to deal with, and we need to deal with it before we define how we structure examples. We need to know what kinds of examples are good examples, which must be distinguished from popular examples.

Remember how SO started. There were good questions, but there were also a lot of chatty, subjective questions too. We eventually banned the latter, because we realized they didn't work very well. Even if it was a popular and highly upvoted "question". This was done by the will of the developers, and with the support of (much of) the community.

We need to do something similar here. We need to know what a good example is and what isn't a good example. Even if the example presents good information in an easy-to-digest way, we still need to be able to ditch that example if it doesn't fit community standards.

We need a standard, driven by the community and enforced by users, as to what a good example needs to look like. There should be little ambiguity in whether an example measures up to that standard, and there should be a mechanism to remove it if it does not.

6
  • 8
    My point wasn't that the Java Arrays topic was particularly good, but that, for some reason, the Java Twitter channel mentioned it. I agree that topic is a mess and so we're going to find some way to fix it. This time we are following the early SO model you mentioned. But please let's not decide on a standard of what's a good example yet. That's the incrementalist approach we've already been burned by.
    – Jon Ericson Staff
    Commented May 18, 2017 at 21:35
  • 10
    As we know from SO, mature and successful rules don't have much ambiguity to them. Commented May 19, 2017 at 3:28
  • 7
    I think that the example you cite highlights the problem I see: lack of focus and direction. When doing any writing, technical or not, you have to have a purpose in mind, and that purpose rarely fits in what amounts to a headline. A clearly written question defines scope of the answers and helps the answer authors stay on task. Existing SO Q&A could be used to have curation topic questions with answers linking to other relevant answers and curating related content better than search results would. The SO search engine could include such related answers even if not picked up by search keywords. Commented May 19, 2017 at 13:08
  • Hm. I agree with the principle that a standard is needed, but I actually don't think your argument supports your conclusion. Your argument is based on the fact that SO started off kind of a mess and eventually got refined into something better. From there, you argue that we should avoid the mess entirely and get a standard now, but SO's success doesn't suggest we need a standard immediately. It suggests that, "Let a flood of crap come through and then we'll start sifting for gold," might actually be a viable strategy...
    – jpmc26
    Commented May 26, 2017 at 6:44
  • @jpmc26: But there's a difference. Old questions effectively go away. Even if they're not deleted, they're barely here. They may show up on Google searches, but they're not something you see every day in the list of questions on tags. On Docs.SO, old documentation is more prominent than new documentation. We show the highest voted stuff first, which will be the oldest stuff. Docs.SO needed a standard immediately because content never ages away. SO deleted some older content, but left other older content lying around. You can't do that with Docs.SO and still have good documentation. Commented May 26, 2017 at 14:53
  • Maybe that means part of what's needed is a way to phase out obsolete stuff more effectively? It's entirely possible that you'd end up just building another SO trying to go that route, though. I dunno. It just seems like maybe, "Make it all perfect right now," isn't a winning strategy. Even if you get a standard, if it doesn't turn out to be a good one, you'll need to clean up the mess. (Hence the current situation.)
    – jpmc26
    Commented May 26, 2017 at 23:28
56

I just wanted to thank you for the difference in approach here.

(I don't really have a specific comment on this topic as I've already been far too verbose.. heh)

I'm looking forward to seeing what happens next.

18
  • 1
    Thanks! If you have a moment, I'd really appreciate know what you see is different than what we've done in the past. I have some ideas, but it's better to hear it directly from you. Other people in the company might appreciate the meta-Meta feedback.
    – Jon Ericson Staff
    Commented May 18, 2017 at 18:46
  • 57
    @JonEricson honestly? It's that your post reads as "we want your help to guide the design of Docs" rather than "we've made this awesome product you will love. do you agree!? why u no agree!?" or some less cheeky variant of that. For example, this post is a great engagement post with the community. It feels less of a "SO ramming this down our throats" to a "SO wants to make this good with the community."
    – enderland
    Commented May 18, 2017 at 18:49
  • 10
    Yeah, the whole "let's involve the community" is a big thing 'round here... you know... where the community hangs out.
    – user4639281
    Commented May 18, 2017 at 19:00
  • 30
    Why is this not a comment?
    – TylerH
    Commented May 18, 2017 at 20:20
  • 33
    @TylerH because it's good, from time to time, to actually remember people from SO that we do like them. I'm happy to have an answer (not a comment that will disappear) to upvote to that effect. Commented May 18, 2017 at 20:42
  • 2
    @TylerH Why is that a problem? This is Meta, after all.
    – duplode
    Commented May 18, 2017 at 20:46
  • 13
    @duplode Because even on Meta, if your post consists purely of "thanks", it doesn't really belong as an answer. Answers are intended to address questions. This one is just noise (nice noise, but still noise).
    – TylerH
    Commented May 18, 2017 at 20:47
  • 15
    @TylerH I'd say this answer is not noise -- not in the context of this Meta discussion.
    – duplode
    Commented May 18, 2017 at 20:51
  • 7
    @duplode You're free to disagree of course but I don't see what value "thanks" provides as an answer that really addresses the question, or that can't be provided in a comment.
    – TylerH
    Commented May 18, 2017 at 21:16
  • 5
    @JonEricson to me the main thing that's hugely important in your difference in approach here is that your new plan is use your own platform to make something valuable and learn what features it needs through that process. This will force you to be constantly asking the questions "Is the content we're writing useful? Is it presented in the way readers will want to consume it? Will the people who would benefit from reading it be able to find it?" that we are constantly asking, and then to structure the whole product in a way that allows the answers to those questions to be "yes".
    – Mark Amery
    Commented May 19, 2017 at 10:55
  • 8
    @JonEricson By contrast, your old approach seemed, from the outside, to broadly be "We picked a bunch of functionality, stitched it together at random, and offered it to the public. We have only vague and sometimes contradictory ideas about how anyone's going to use it, but we're sure the public will figure it out." This approach was never going to work, and it's encouraging to me that you seem to have now recognised this.
    – Mark Amery
    Commented May 19, 2017 at 10:59
  • @TylerH This type of answer isn't noise in this context, because it indicates the number of people that agree with what the team want to do with Docs, and consider it a good idea. Considering that they're deciding how to change the structure, and have proposed a plan for doing so, knowing how many people agree with their plan can indicate to them whether they need to change it and/or ask for more community input. In this regard, it's just as useful as a "Yes, this is a good idea, but you should do X too" answer, or an "I disagree with your tentative approach because Y" answer. Commented May 22, 2017 at 18:20
  • 2
    @JustinTime Again, a comment can do that just as well, because comments can be upvoted. This answer does not provide any useful info beyond "thanks, +1 from me", which IMO is hardly worth a comment, let alone an answer.
    – TylerH
    Commented May 22, 2017 at 19:00
  • 2
    @JustinTime That is what upvoting/downvoting the question is for. We don't need a "yay" and "nay" answer for every proposal/suggestion that gets posted to MSO every day.
    – DBedrenko
    Commented May 23, 2017 at 16:12
  • 1
    @JustinTime If you just want to indicate you agree with a post on meta, you vote it up. Like I said, and like DBedrenko mentioned just now as well, this answer is arguably not even appropriate for a comment. It's definitely not appropriate as an answer.
    – TylerH
    Commented May 23, 2017 at 18:43
48

I still don't understand what exact problem does the Documentation system solve, other than giving a different name to what I've been largely doing on SO anyway. I admit that myself I thought Documentation would be somehow better, but now I don't see how.

I do see two problems that it might prevent:

  1. Q&A self-answered pairs with a well-posed question garner immediate downvotes. I can only presume that they are considered karma-whoring (as if I cared).

  2. Flagging questions as dupes that are better covered by a comprehensive Q&A pair seems to cause coronaries, especially if the author of said Q&A flags the dupe, and doubly so if the Q&A post-dates the original question.

These two problems, I believe, are best solved by consumer education and advocacy - e.g. a warning message for anyone downvoting a Q&A pair the first time, explaining that no, these are not somehow bad just because they are Q&A.

Other than that, could you pitch the Documentation system to convince someone who has provided 0.5k buildable examples so far and seemingly needed nothing more than what's already out there?

15
  • 3
    The original pitch is still relevant. Not many people self-answer questions and some questions are closed as too broad. That means critical elements of programming knowledge have no place on Stack Overflow Q&A. I think Q&A does serve as "shadow documentation" for a lot of technologies. It's better than the old system where knowledge was passed down in person or on unstructured forums. But maybe we can do better. If you want to help us find out, we are asking for your help.
    – Jon Ericson Staff
    Commented May 18, 2017 at 21:26
  • 16
    @JonEricson: "Not many people self-answer questions and some questions are closed as too broad. That means critical elements of programming knowledge have no place on Stack Overflow Q&A." I don't agree that A leads to B here. Can you provide an example of a Docs.SO example that shows "critical elements of programming knowledge" which could not have a sufficiently narrow question that generates that as an answer? Commented May 18, 2017 at 21:28
  • 2
    @NicolBolas: I'm pretty sure any example I give I could also get on Q&A with a little bit of effort. But if someone with no SO experience were to ask the same question (in their own words) they would be downvoted pretty quick. Keep it up? Question banned. Maybe that's the ideal solution. Or maybe, just maybe we can do something different.
    – Jon Ericson Staff
    Commented May 18, 2017 at 21:49
  • 18
    @JonEricson: You seem to be saying that Docs.SO is just Q&A, but we allow crap questions. And therefore, you're agreeing with Kuba that they're the same. Commented May 18, 2017 at 21:56
  • 3
    @NicolBolas: Not at all. Documentation won't have questions.
    – Jon Ericson Staff
    Commented May 18, 2017 at 21:56
  • 4
    I often add Q&A pairs. I can usually expect my questions to get several downvotes at first by those who patrol the new questions (probably for being too broad) (example - please don't downvote it back below 0 again), but over time they go positive after getting upvoted by the general community. My answers would probably fit better in a documentation format. I tried moving some of them there, but I quit after at least one was deleted because it was competing with another earlier example. When documentation is more stable I may go back to it.
    – Suragch
    Commented May 18, 2017 at 23:30
  • 1
    @NicolBolas In my opinion, say we had a question on SO "What are all the Arithmetic operators in PHP and how do I use them?". That'd be closed the instant it's asked. However, it might have been a good example on Documentation, under something like "Arithmetic Operators in PHP".
    – SGR
    Commented May 19, 2017 at 8:39
  • 10
    I think that all we need is a [documentation] tag with a policy that such questions are broader and are meant only for documentation-style work. From what I gather thus far, documentation is: a system of answering broad questions without stating them first. As any writer knows, a problem/question statement positively influences the quality, scope and focus of any "answers" written to it, I claim that question-less documentation is not how anyone should ever write any documentation anyway. The "question" may be more of a statement of purpose/goal/outline, but it needs done. Commented May 19, 2017 at 13:02
  • 4
    @SGR: We've seen many topics just like that. And they are, uniformly, garbage in terms of quality. Every keyword, operator, or whatever topic on Docs.SO is an unformed mess of stuff. It's not something you would ever read. And as reference material, it's terrible. Seeing how to use the else keyword doesn't tell you much about it. Commented May 19, 2017 at 17:24
  • 3
    @JonEricson The 'original pitch' has been critiqued and refuted point by point and had its assumptions and inferences demolished so many times that it most certainly isn't relevant, and never was. This is the basic problem here, not structure. There is no logical basis for this project, and never has been.
    – user207421
    Commented May 20, 2017 at 3:47
  • @NicolBolas I'm not disputing the quality of the material, I'm simply stating that what would be an off-topic question at it's very core, regardless of the quality of it on Q&A could make a good example in detail on Documentation, at least to my reading. Just because Documentation has a wider scope of what would be "on-topic" doesn't mean it's letting any old crap in by default. The actual quality of Documentation is in theory up to the contributors.
    – SGR
    Commented May 22, 2017 at 9:25
  • "Flagging questions as dupes that are better covered by a comprehensive Q&A pair seems to cause coronaries" ...It causes arteries and veins?
    – jpmc26
    Commented May 26, 2017 at 23:36
  • I do agree that there are several types of documentation, and that all are needed, and that some have a greater need for improvement, in content, scope, searchability, etc. And giving the size of the how-to/cookbook industry, and proliferation of how-to medium articles, I believe that there is a clear value for the programmer for cookbook/how-to examples. It is also clear that any how-to example, is an answer to an how-to question, hence the overlapping with Q&A. STILL, it is worth identifying and (re)packaging key most-useful recipes. So there is a need/pitch. Now let's see the product. Commented May 28, 2017 at 1:18
  • @jpmc26 It's a word whose meaning highly depends on context. Here, I used it as a short for coronary thrombosis. It's a rather popular use of the term in the U.S., but perhaps not so elsewhere - I apologize for any confusion :) Commented Aug 25, 2019 at 15:14
  • @KubaOber The common term for it would actually just be "heart attacks." I have never heard anyone use it in non-medical conversation.
    – jpmc26
    Commented Aug 25, 2019 at 15:20
48

None of this does anything to address the main problem.

The majority of the documentation is just worst practices and misinformation being perpetuated by those with just enough knowledge to be harmful.

The entire Documentation site is just taking the Dunning/Kruger Effect that is already well represented on the main site to its next logical conclusion.

I am convinced that the entire premise of crowd sourced documentation without some sort of actual qualified vetting and curating is never going to end in anything but misery.

Until the Balance Fallacy that is being embraced, that everyone's contributions are equally valid, is thrown out the incorrect content will always outweigh the correct content.

After I had contributions mutilated over and over and over in edit wars with people just trying to inject their incorrect code as edits to my idiomatically correct code I just requested all my content be deleted and my name be disassociated with whatever the powers that be decided they would not delete for whatever reason.

I do not think anything can be done about this situation even if the powers that wanted to address it. I still think "Documentation is on its way to becoming the next W3Schools" and not slowing down, structural organization of wrong information is still wrong information. Until someone officially acknowledges that the content quality is terrible nothing else is anything but making that fact even more evident.

22
  • 2
    I'm curious what method you use to evaluate the existing content. I can't help but wonder if it might not be a hasty generalization. In any case, one of the key steps in iterative development is frequent testing and evaluation. You will have a chance to provide input on specifics in the next few month. We hope to show off samples of excellent documentation and see if the community agrees.
    – Jon Ericson Staff
    Commented May 19, 2017 at 15:04
  • 12
    I'm curious what method you use to evaluate the existing content., simple is it correct? the majority of the content and edits in my experience fails this simple test.
    – user177800
    Commented May 19, 2017 at 15:51
  • 5
    Unfortunately, that method of evaluation doesn't really scale.
    – Jon Ericson Staff
    Commented May 19, 2017 at 18:51
  • 24
    I agree with Jarrod. A common theme of successful documentation projects is that they have specific ways of ensuring quality - and those means, at some level, are undemocratic (some core group with recognised expertise has absolute authority to remove what they consider bad content, and to kick people out if they keep committing bad content). That is completely at odds with everyone having equal votes in a crowd-sourcing model. True, such approaches do not scale, but quality is non-quantitative consideration, not something that scales with total number of contributors.
    – Peter
    Commented May 20, 2017 at 1:11
  • 14
    @JonEricson Your comment is absolutely and utterly meaningless. Truth doesn't scale? Quality doesn't scale? This would be thrown out as a category error in any Philosophy 101 course.
    – user207421
    Commented May 20, 2017 at 3:49
  • 2
    @EJP: I'm talking about the method of evaluation: Jarrod judging the correctness of each and every edit. That's assuming he's willing to do it. My point is we have to find some way for the community to curate content. Most suggestions amount to naive assumptions that high-reputation users will gladly take the burden of review. Many do of course, but not nearly enough. For many, it's just not rewarding for long stretches. Personally, I'd rather high-reputation users do something they enjoy anyway.
    – Jon Ericson Staff
    Commented May 20, 2017 at 3:57
  • 10
    I never said or volunteer to judge anything, I just said the criteria is simple as is something correct. Personally I do not think there is a way to crowd source quality because the signal to noise ratio will always be extremely bad.
    – user177800
    Commented May 20, 2017 at 13:12
  • 6
    @JonEricson You cannot get 'the community' to curate content.
    – mrr
    Commented May 20, 2017 at 14:33
  • 6
    Totally agree, in fact this is something I went into war over when Pet.se was launched. The internet has become a means to dissolve wisdom and truth as popular opinion runs rampant and takes it's place.
    – user3956566
    Commented May 20, 2017 at 15:46
  • 10
    the Balance Fallacy will always undermine any system that all opinions are given equal weight because there are more people that think they are experts that are not than there are actual experts. SO already proves this with all the massively upvoted and checkmarked "answers" that are at best not correct and at worst maliciously wrong.
    – user177800
    Commented May 21, 2017 at 0:16
  • 5
    @JarrodRoberson: "The majority of the documentation is just worst practices and misinformation being perpetuated by those with just enough knowledge to be harmful." Is it? I haven't taken a close look at a large number of documentation pages. But if you ignore the organization of information, I haven't seen a lot of misinformation or bad practices being promoted. At least, not in the fields I know well enough to judge them. In particular, the C++ pages seem to have correct content. Commented May 21, 2017 at 16:34
  • 6
    @JarrodRoberson: "SO already proves this with all the massively upvoted and checkmarked "answers" that are at best not correct and at worst maliciously wrong." Similarly, are all or even most "massively upvoted and checkmated" answers "not correct" or "maliciously wrong"? I think its unreasonable to castigate a system for only working 99% of the time instead of 100%. No system can achieve perfect accuracy. Maybe SO's accuracy could be better than it is, but the fact that there is inaccurate information does not make the source unreliable. Commented May 21, 2017 at 16:36
  • 3
    @NicolBolas - show me the statistical proof that 99% of all the highly upvoted answers and accepted answers are 100% correct and I will recant my statements, until you do this, yours is just hyperbole and alternative facts at best.
    – user177800
    Commented May 21, 2017 at 19:01
  • 7
    @JarrodRoberson: You've provided no more evidence for your statements than I have. You're simply declaring that "the majority of the documentation is just worst practices and misinformation being perpetuated by those with just enough knowledge to be harmful." You haven't even provided anecdotal foundation for that claim, let alone "statistical proof". I was simply responding to your unfounded statements in kind. But I guess it's easier to keep believing that everything in Docs.SO is garbage than it is to provide evidence that it is. Commented May 21, 2017 at 19:12
  • 4
    @JarrodRoberson: "You both are guilty of this" I'm curious as to how, exactly? Your argument is, "I have looked at Docs.SO, and to my estimation, it is dominated by erroneous information, and nothing is being done about this." My argument is, "I have looked at Docs.So, and I do not see this rash of erroneous information. You have provided specific instances of errors, but no evidence that they dominate the available information." Commented May 22, 2017 at 14:21
39

Just a thought: What if, instead of T-SQL, you instead documented a few SE things as part of the initial experiment? E.g. the SEDE schema, the API, the StackExchange JS object. Not to mention the public dumps could use some documentation, this could help with the issues in that thread too by giving that stuff a proper home. This seems like it would make more sense: You have full control over it, the resources to do it, a user base interested in the topics, and worst case it's still helpful. Plus you get first-hand experience with some of the difficulties (maybe even more, since those items have a comfortably wider variety of needs, so you won't accidentally tailor it to T-SQL; a manageable variety of technologies can give more diverse feedback). And also it's got more of a ... "this is ours" kind of vibe to it, if that makes sense.

Plus, all the SE technologies are enough to chew on. We can reasonably document more than one of them completely, whereas T-SQL is fairly massive, with entire books written on its subtleties. With a small but diverse variety of manageable topics (and ones the community has a direct vested interest in), more users can contribute, rather than just those familiar with a single technology.

The other upside is it directly shows that SE (and the community) is confident enough in the service's value to use it, which is not a bad selling point.

The thing is, nobody really gains anything by redocumenting T-SQL. But documenting SO stuff not only accomplishes the goals of the exercise, but has the bonus of actually adding value in the process, something which, so far, Docs has had a very hard time with.

6
  • 1
    Those are useful suggestions and we might tackle them later. The goal of this round is certainly not to produce something useful (though, of course, it would be great if we did). Instead it's trying to discover what the components of excellent documentation are. To meet that goal we have to start with a widely used technology so we can get diverse feedback. Far too few people use the items you mentioned (perhaps because of poor documentation?) for us to get the feedback we need.
    – Jon Ericson Staff
    Commented May 19, 2017 at 17:33
  • 3
    @JonEricson I suppose, although, imho, I feel like the collection of people who do use those features can also give very good and representative feedback, plus I hypothesize that the types of people who use those, on average, care very much about the site, which is good. Sort of like the same reason the HTTPS moves were done on the Security site first (sort of, I know it's not the same).
    – Jason C
    Commented May 19, 2017 at 17:34
  • 11
    I like this idea a lot. I don't think it needs to be an either/or, though. What works well for a language (e.g. T-SQL) is probably not quite what works for an API (e.g. ours), though there will be similarities and overlap. It doesn't terribly matter which we start with as I suspect we're gonna have to do both either way IMO.
    – Adam Lear StaffMod
    Commented May 19, 2017 at 17:44
  • 2
    Search alone could be a pretty spiffy topic if you toss all the ninja options in there and give some common use cases, good idea.
    – user50049
    Commented May 19, 2017 at 18:01
  • 3
    There's a huge variety of things to choose from that kind of cover both worlds, too, as a compromise (relevant to SE but also with a large user base and existing documentation), e.g. Markdown, MathJax with examples, etc. Wouldn't want to throw everything in there, but the point is there's a good variety of stuff to choose a handful from, plus the diverse technologies give more well-rounded feedback.
    – Jason C
    Commented May 19, 2017 at 18:05
  • 2
    The fact the fact that this idea is just occurring --"trying to discover what the components of excellent documentation are"-- is the source of the problem. Rather than starting from trying to do something, why not start from user stories? Or by talking to people who have worked on different kinds of documentation and understand what they are/can be? People always say "there is no documentation; they actually don't mean that, they will say that about code that has complete self documentation in the code or man pages. They mean they can't find what they need to do what they want.
    – Elin
    Commented May 20, 2017 at 14:33
23

I still do not get the exact value proposition. What is the void that this effort is supposed to fill? What are the needs that are not met by current documentation solutions in existence?

With Google search capabilities at our disposal specification-type documentation and real life examples do not have to have to come from the same source.

While we can come up with shortcoming lists for various Wiki-style platforms, what will SO Documentation have that is likely to overcome them?

Developers should be good at reading, writing and documenting code. Developers are quite often are lousy in creating documentation for wide audiences. That's why technical writers can still earn their living.

This effort seems to me like building an open-source application without an original vision behind it.

"Guys, here's GitHub page - start contributing. We are not sure what exactly we want you to write, but we hope if enough people get involved, something useful will come out."

In your "Mona Lisa" example you already decided that it will be a portrait of a woman. With SO Documentation you have not got that far. To me it seems more like "picture of a life being" at best.

Please prove me wrong.

2
  • 1
    From the announcement: "Documentation is community-curated, example-focused developer documentation, based on the principles of Stack Overflow." That vision is still in place. Your imaginary quote isn't too far from how we launched. Our approach is a little different now. We are starting much smaller and plan to provide a lot more direction.
    – Jon Ericson Staff
    Commented May 19, 2017 at 18:49
  • 15
    @JonEricson - Why do it at all? Just to create a repository of loosely connected peer-reviewed examples?
    – PM 77-1
    Commented May 19, 2017 at 19:43
17

Glad to see you're sitting back and taking a stab at doing better. I look forward to what that turns into.

As my use of Documentation has been specifically for which, once the tag was approved for documentation, I had to scratch my head at how I was supposed to be using it, the template didn't seem to fit the pattern I had in my head. As it seemed everyone else who supported the tag thought the same way: no idea how to use it. It was only in the last two or three months that it's gained some topics and I duplicated the approach to write a few more pieces of documentation. But every page that exists is something that falls into the lines of "new user tutorial."

And its to that end that I'm wondering what the changes and new approach will bring to the topic that I know and wish I would see fewer questions about why something's not working when the developer blindly followed a 3 year old tutorial and thought "eh, v1.8 is like v1.11, how much different can they be to mod for?" And inevitably something goes wrong and they have to ask for help and I see the same mistakes being perpetuated.

It's essential that documentation and tutorials be maintained and kept current because things change so rapidly and several of the tutorials that do exist were written by people who actually didn't know what they were doing, but they thought they did and they put it out there (sometimes in a very copy-paste-it-works-trust-me totally-not-a-cargo-cult way) and bad practices and horrible design patterns spread. "I did it that way because the tutorial told me to." "What tutorial?" "" "Oh god, not that one again, it's four years old and its for 1.8 and you're using 1.11, why are you following that garbage?"

There's one mistake I can spot a thousand miles off, title "custom crop crashes. "Why yes, of course it does, you passed null to the constructor." "No I didn't, see?"

myCropSeed = new CustomSeed(myCropBlock);
myCropBlock = new CustomCrop(myCropSeed);

Only they don't see it as being that obvious, because they see this:

class ModItems {
    public static Item myCropSeed;
    public static void Init() {
        //ModBlocks.myCropBlock holds a reference to the crop block
        myCropSeed = new CustomSeed(ModBlocks.myCropBlock);
    }
}

And they know that in another class they have the other line, therefor everything's fine. But what they missed was this:

public static void Init() {
    ModItems.Init(); //crop block *is still null here*
    ModBlocks.Init();
}

It's an easy problem, I swoop in tell them that they created their item before their block, mark it as a duplicate, and GTFO. In this case if they swap their init calls around, they still have the same problem, only now instead of it crashing when they harvest the crop, it crashes when they plant it (because the block refers to the item and the item refers to the block). They tried to be clever and it bit them in the arse.

Two thirds of modders are not accomplished coders [hyperbole], a good 2-4 people every month try to "learn programming by modding Minecraft" and they get no help on the Forge forums because no one there wants to explain WTF an "object" is. Get out, learn Java, come back later. It even says so on the forum's description. The forum is for understanding the specifics of how to interact with Minecraft's internals and Forge's API. Sure we'll cover things sometimes too, but its expected that all we need to say is, "This object qqq is null at this line" and the asker can go "oh you're right" and be able to fix it on their own.

Now take that and compound the complexity and obfuscate the methods because in order for the methods to even function according to the desired spec, their signatures are littered with generics. Like Capabilities (introduced by Forge in Minecraft 1.9ish). Explaining how to use these doesn't fit into the existing Documentation "flow." Even a well-rounded programmer can take one look at this and think, "Dear sweet hexidecimal Jebus, what in the sixteen hells is THIS?"

public <T> T getCapability(Capability<T> capability, EnumFacing facing) { ... }

CapabilityManager.INSTANCE.register(<Class T extends...?> capability, <Class U extends Capability.IStorage<T>> storage, <Class V extends Callable<T>> factory);

You can't explain this at the method-level. You can't even explain this at the class or interface level. You have to pull all the way back out and explain three different classes (ok, a class, an interface, and a static factory class) all at once as a group. They're too tightly interwoven with each other.

And it's so confusing I don't trust myself to write a tutorial page on it for Documentation. And apparently three other people aren't comfortable doing it either. I managed to implement it once myself and I did it by largely closing my eyes, uttering four "Hail Mary"s, and stepping into the void. It works. I don't know why. And I have little interest in going in and pulling on levers and pushing buttons to figure out what could possibly go wrong.

A community managed repository of knowledge is what I want. The Forge team does a good job providing the tools, but is awful at everything else. I've tried to get the documentation pages updated on an occasion or two, but its like pulling teeth. Everything has to be done through git pull requests and those get ignored all too frequently. I hope that Documentation will support this.

5
  • 1
    That's because you're trying to explain how to programme to children. 'Why does crop not grow???' is not a StackOverflow-level question.
    – mrr
    Commented May 20, 2017 at 14:35
  • 2
    @MilesRout I never said that "why does crop not grow?" is a SO-level question. It's merely a problem I've seen dozens and dozens of times and 7 times out of 10 the person goes "oh, you're right, I see what I did wrong." Of the remaining 30%, 80% of those only need a slightly more in-depth explanation. The last handful are actually children. But I want docs for Capabilities, because the ones that exist are terrible. Am I a child for asking that? Commented May 20, 2017 at 15:13
  • 3
    @MilesRout - actually Why does crop not grow??? is the majority of stackoverflow questions for the past few years.
    – user177800
    Commented May 25, 2017 at 17:57
  • @JarrodRoberson that's why this site is so bad now
    – mrr
    Commented May 25, 2017 at 22:48
  • 1
    "Show me teh cropz" is pretty much SO all over. "I get some kind of error message since two days ago". "My connection to (some url) is very slow when i'm typing plz help me".
    – user146043
    Commented May 26, 2017 at 22:51
16

I have been following docs ever since that whole Warlord thing, and since meta was asked to solve one of the two most common problems new features have

  • naming things (hint: it was this one)
  • syntax errors
  • off by one errors

While there have certainly been ups and downs to the project, it inherently seems like it should be able to work. Perhaps it is not there now, but that doesn't mean that the fundamental premise isn't possible to achieve. I believe this because SO's Q&A system lacks the ability to achieve two main factors without mangling content:

  • Canonical Posts
  • Tag Wikis

Just as long ago we all went through What Stack Overflow IS, and What Stack Overflow is NOT, we also seem to have been going through What SO Documentation IS, and What SO Documentation is NOT over the past several months. The largest response I have heard was that SO Docs

  • is not a library,
  • and that it is a source for examples.

So how can we make SO Docs more like a set of examples, less like a library, and yet still retain the crowdsourcing spirit? This is the question I consider when I consider what the structure of SO docs should be. SO Docs needs to create the canonical ability that SO lacks and improve the tag wiki approach that has almost no support at SO - while still being versatile enough to allow anyone to contribute, and structured enough to allow content to be found. Given this, it is not surprising that finding this structure has not been easy, nor that even with iteration it will be immediately complete.

As pointed out with the example images in the question here, often projects are iterative, and while the end goal may be known or dreamed, it is not achieved after the first step. Any time I think of this scenario, I always think back to the telephone in the US. When it was first invented it was not envisioned to be in everyone's pocket worldwide. Instead, it was only crafted to be hardwired from point A to B, or from number 1 to number 2; which is to say that the first phone numbers were single digit. Today there are more phones than people.

SO Docs does not need to made perfect, it just needs to achieve progress one step at a time.

Many users want to contribute to Docs, but either are not sure how, or are not sure where. I think expanding the available space to contribute will allow at least the where to become more available and thus only leaving the how. How can I add value? Many people do this in the form of a personal blog, documenting the procedure they use not only for future use but for others as well. Many others simply want to give a canonical source of the underlying tools that procedures may use. There is no reason that if those two overlap only one should be allowed to occupy that space.

However, that is what the current silo structure enforces. Perhaps that is best, and we should just let the silo structure remain. I think that it is holding us back though. Content should be allowed to compete, this is a game after all isn't it? Okay, not really, but there is gamification and everything is sorted by votes.

Documentation needs to be decoupled. It is currently God code. The topic Arrays in Java owns all examples on Arrays, all explanations, everything. If you have an array, you absolutely must import this topic in order to use it, and that is the only code you have access to. This prevents so many nuances and facets of Java's Arrays from being discussed.

If there is a custom use of Arrays, coupled with another type of platform or library, then it should not be pigeonholed to this one topic. Instead, topics should be allowed to cross the tag boundary. Allowing topics to be tied to a title and a set of tags while containing a set of examples will literally open a floodgate of availability for content to fill. It does not need to be properly ordered by some sort of clustered index. All it has to do is have the availability to be searched.

Imagine something like this:

Topic:
Using the visitor pattern in c# to generate MySQL

Examples:
Setting up the expression visitor
Setting up the parameter visitor
Setting up the join visitor

This structure allows for such a large variety in content. Moreover, where would something like this fit in the existing structure? Perhaps in the c# tag? How hard would this be to find by searching though, probably rather difficult. You would need to make sure that it wasn't in the .net, or mysql tags. There is no way to look for "generate mysql" in the current docs search unless you are already in the current tag, and you also cannot use multiple tags. In fact, Docs lacks a general search ability right now.

This structure allows for elasticsearch to examine topic titles with tags included just like SO's Q&A structure. It could view each example as an answer and almost directly plug and play into the existing structure being used.

This structure allows for the "my tags" section to be relevant in Docs, and also allows for a more familiar browsing environment where users can browse by "Active" in their "my tags" settings (something which has already had a lot feature coverage in Q&A).

While this may make Docs feel slightly more like Q&A, it still provides for the same topics and examples setup. All it does is leverage the powerful lessons that Q&A can provide after almost a decades worth of use.

5
  • I agree with almost everything, but I'm not sure where the idea that SO Docs is not meant to be a library. I'm not even sure I understand what that means.
    – Jon Ericson Staff
    Commented May 19, 2017 at 18:18
  • 1
    @JonEricson - I guess it came from Documentation is not a library, tags are not books, since it seemed rather popular, and my disagreeing points didn't seem to go over well. I don't really think that docs is not a library, however, consensus seemed to indicate others did.
    – Travis J
    Commented May 19, 2017 at 18:27
  • 1
    Wow. I never saw that. (Or if I did, it was immediately replaced by some other meta question in my brain.) You can safely ignore that question, I think. The point of this exercise is to figure out what Docs should look like and we aren't going in with preconceived notions. (Or at least not consciously.)
    – Jon Ericson Staff
    Commented May 19, 2017 at 18:35
  • ✔ Safely ignored.
    – Travis J
    Commented May 19, 2017 at 18:42
  • 3
    I'm not even sure that there is a clear idea about what "an example" means. Maybe it would be better to call it Examples instead of Documentation because as mentioned in other comments Documentation covers everything from man pages to tutorials for beginners.
    – Elin
    Commented May 20, 2017 at 14:54
11

Design Efficiency

Jon Ericson, your post has me wondering if the design process could benefit from a little tweaking.

First my compliments: It's simply outstanding to watch a company post with such self-awareness, thoughtfulness, and honesty. Compare to a company like Lexus (Toyota) who has well documented issues matching their designs to customer desires in the US. Yet they still have almost no direct channels of communication/feedback with the public, let alone communication that requires some courage to get out there. So great job on doing what many companies frankly are incapable of.

On to efficient design. One way to look at the challenge of design is that only two things matter: talent and efficiency. In this case I have no doubt on the talent part, but designing stuff is so time intensive that even a talented team has to iterate quickly to not fail (or get lucky, but we don't want to roll the dice more than we have to right?).

So what’s the problem?

Too Much Coding

It seems the team is resorting to writing code too early in the idea process. Writing code should normally be one of the last resorts in iterating your design. Code is important, but it's so damn expensive (w.r.t time) it needs to be used in design sparingly - when the value of what it teaches you will be high and when that learning value is not readily available through some simpler/faster means. When I heard "throw a whole bunch of pasta against the wall & see what sticks" I thought, sure hope that doesn't mean thinking of 10 ideas and writing code to test viability for each one. It's just too slow for early stage projects when goals are still so open ended.

Too Much Waiting

“We read feedback on Meta and conducted usability tests” I was surprised to read this happened so late in the cycle. Usability needs to come an order of magnitude sooner. Had a cool idea last night before you fell asleep last night? Great, test it today! Then, try to find out whether it's a good idea or not before you go to lunch, and then test another one of your ideas in the afternoon. Not to say everything gets short shrift. A lot of ideas can be quickly dismissed, and the better an idea is the more due diligence it deserves. The point is, we want to minimize the time between someone first having an idea and testing the viability of the idea. “Idea” of course means either entirely new software or a specific feature.

Subjectively, the word “conducted” also gives me pause, because it’s too suggestive of formality. I’ve been in big labs with a bunch of cameras and people watching behind glass taking notes, but it doesn’t always have to be that heavy. Usability has very simply objectives. Learn what works, learn what doesn’t, and as a bonus maybe even learn the reasons. The clock is our enemy and we need to get to our next iteration as fast as we possibly can. Maybe you’ve already read Krug’s book. He does a great job explaining fast, informal usability testing: https://amazon.com/Rocket-Surgery-Made-Easy-Yourself/dp/0321657292

No Wavy

If this sounds a little vague and hand-wavy, it’s meant to be

Please no! Hand wavy is typically anti-efficiency, and doesn’t really help the creativity side of things either. I see you’re trying to learn from Jeff Patton and that’s great. But these words might give someone the wrong idea, and in fact if I recall correctly Jeff said at some point [make sure you’re not just hand wavy].

Pain Points Not Well Defined and Not Well Understood

Call this whatever you want – Pain points, elevator pitch, problem statement, mission statement, the vision. They’re all buzz words but this is still an important thing to do right. Can you tell me plainly and succinctly why this project is a great thing?

I’ve looked around but haven’t been able to find a simple, precise, and compelling problem statement. On an intuitive level it sounds like it could be cool. It’s vaguely interesting enough for me to be here writing this. That’s a good start, but it’s not enough to be confident the right code is being written. For example, consider a few things about Kevin’s post:

Stack Overflow has made all of that better, but there's one area that is still hanging around: Documentation.

So, it's a developer pain point because it’s “still hanging around”? Too imprecise. It's too hard to derive the meaning from the sentence. If the point was just that SO doesn’t do docs yet, that of course would also not be a pain point.

put [Documentation] online in a form that is trivially easy to find

I can be slow sometimes but, put it online has no meaning to me, everything already is online. Trivially easy to find also doesn’t illuminate much. Google has already made everything easy to find. What is the actual novel value we are trying to add here? I don’t doubt he was thinking of some visionary shit but the whole team needs to see it, and see it the same way.

We’re interested in fixing what’s broken with documentation

Excellent, I love when people want to help developers. Unfortunately this sentence also has great intentions but not so much direction or guidance. We want to hear what is the necessity here that will to be the mother of our invention.

No intent to unfairly cherry pick from what Kevin wrote, the entire content is not more than two pages w.r.t. the problem statement. It's just that this is a foundational artifact that ideally helps to lead and align thousands of people to understand things the same way.

To give an example, here’s a made up problem statement for Stack Exchange:

There is currently no fast, efficient, and scalable way to crowdsource and share expertise on the Internet, despite a provably insatiable demand for finding more information while using less time to find it. [a few words here to explain how badly people hated expert-exchange]. We propose to improve the quantity of information available and to reduce the time needed to find it. The guiding principles to enable these improvements will be: 1) An environment that's easy to access and not obstructed by short sighted advertising or membership goals. 2) An environment that’s structured for easy participation with an extremely flat learning curve. 3) The potent use of game theory concepts to motivate broad participation and a virtuous cycle among the participants.

Sure, it’s trivial to write that in 2017 but that’s not the point. The point is it’s a very short description but still allows a pretty good sense of where the path lies.

In the comments there are tons of different ideas of what this project should be, and that also doesn’t feel quite right. The tons of ideas phase, should be 5 people hanging around a cubical or chatting on Slack. In this current public phase, I would have expected comments at least one level below the 10,000ft view.

I hope this all came across constructively, I wish you nothing but success.

It’s not that you can’t succeed the way you’re going now. It’s just going to take a little longer, and a little more luck. The luck part of course still being important to all new software trying to do something new and special.

4
  • 1
    Devs: If you're looking for some quick reading, I recommend this article about the Google Ventures "research sprint" method. If nothing else, please click that link and check the images. A still-pretty-small but longer rec is Disciplined Entrepreneurship by Bill Aulet from the Martin Trust Center at MIT; steps 1-5 are about market/user research, step 6 is about how the users use the product, and only at step 7 do you write a high-level spec. Docs did the reverse so far. Commented May 25, 2017 at 4:40
  • 3
    We have been doing usability tests for over a year. They have largely focused on example creation. For another take on the goals of Documentation, see: my answer to What, exactly, is Documentation? The current phase addresses the bits that were locked in fairly early. It also starts looking at the consumption rather than production angle. We'd rather naively assumed people would be able to write the sort of material they would like to read. But it turns out that's not how people work.
    – Jon Ericson Staff
    Commented May 25, 2017 at 5:48
  • @JonEricson I didn't see that post thank you. The other points still seem to stand (I grant it's an outsider view). My simple suggestion would be to grab a fresh set of eyes who hasn't been close to the project. I think we'd both agree the best team in the world sometimes benefits from doing so. Commented May 25, 2017 at 20:04
  • 3
    I agree. One of the things that might not be obvious from the outside is that we are doing things differently now because we have a new PM: Vasudha Swaminthan. She's our first full-time Product Manager for Documentation and has been the fresh, outside perspective you are talking about.
    – Jon Ericson Staff
    Commented May 26, 2017 at 16:37
9

My opinion of Documentation is NULL. Here's why:

I have tried to add an Anjuta tag. Anjuta is an easy way to start Gtk + Python or C++ programming. Trying to add Anjuta tells me "This tag cannot be backed because it is too new or has too little activity".

Huh? So you cannot add a tag because it has too low activity. So you cannot create documentation for Anjuta and therefore there never will be any activity. Users will go to some other site to ask questions and create documentation.

I would really like to create documentation for Anjuta on the Stack Overflow site because of the polished way everything is run around here. But...

I do not have a solution how to fix this problem. I am just hoping somebody that pulls the ropes thinks of a way to make this edge case work. Otherwise I will find somewhere else for my documentation.

4
  • 5
    "Too little activity" in this case refers to Q&A activity. We originally limited the tags that can have Documentation created to ones that are likely (for some value of "likely") to have an already active and sizeable community that'd be interested in contributing to or reviewing Documentation as well. As we go through the new iterations, we'll be looking at other ways to create Documentation areas and see what makes sense based on the feedback/usage we get.
    – Adam Lear StaffMod
    Commented May 19, 2017 at 15:56
  • Re: "pulls the ropes". Isn't it pull the strings that is idiomatic? Commented May 19, 2017 at 23:13
  • @PeterMortensen Whoops! I should have checked the meaning first. When we said "pull the ropes" at home, it meant the guy that is in control or gets to make the final decision. Thanks for correcting me on that. Furthermore, is there any one person that gets to make the decisions concerning Documentation?
    – theGtknerd
    Commented May 20, 2017 at 2:36
  • 3
    I had the same problem with the svn tag. I had some use-cases which were not documented, tediously pieced it together, and wanted to share it on documentation. But no, the tag is too small...
    – Domysee
    Commented May 23, 2017 at 6:44
7

There should be a way for questions/answers to get "promoted" (and expanded, refined, contextualized, maintained, etc.) to "documentation" (aka canonical answers).

2
  • 2
    This sounds like it goes together well with a suggestion I was discussing with Jon Ericson. meta.stackoverflow.com/questions/348407/…
    – Goose
    Commented May 19, 2017 at 17:58
  • @Goose – yes, that was my thought. A good set of Q&A (question with one or more good answers) can be used to kick off a context discussion or explanation of the larger issues, etc. Links, or a rewrite – either or both might work.
    – spring
    Commented May 19, 2017 at 18:23
4

I am going to throw out an idea which if not the right thing to do might lead to other ideas: What if Docs was just a collection of links to Q&A?

Docs still has the huge issue of points. People are compelled to get those points and therefore they'll argue and edit and compete and delete like crazy. Q&A mostly solves this problem as one person asks, n people give answers. Docs though with shared documentation is a giant minefield because of the point system.

3
  • 2
    @AndyG Uh, I think gman meant links to Stack Overflow Q&As. Like making Docs the equivalent of the c++-faq tag. Commented May 19, 2017 at 17:57
  • This is certainly a reasonable approach. But I don't think you'll get around the problems with points. If such a thing were built and became popular, there'd be a constant battle to get posts linked to from there. You'd just be pushing the same motivation one step removed.
    – Jon Ericson Staff
    Commented May 19, 2017 at 18:40
  • 2
    The problem isn't the same. The problem with docs is you're competing to edit the same document. With Q&A you're competing to get your answer voted up. IMO docs will never work as long as it's community edited and has a point system. A more Q&A style with individual answers removes the community editing problem. Removing the points would remove some of the bad motivation (although as seen from wikipedia it won't solve the political problems of community edited content)
    – user128511
    Commented May 22, 2017 at 2:53
4

Flogging a dead donkey here, but the gap I see in the 'market' is the big picture, high level stuff. And contrary to the current system where (I believe) there is fundamental mismatch between supply & demand, the 'right' people would be motivated to curate quality high-level content. I would, in any case.

I also am slightly bemused at your choosing T-SQL, as "Books Online" is what I would have spontaneously chosen as an example of good documentation.

Also, forgive slight cynicism, but this whole documentation 'thing' does read a bit like "we've got too many developers and too much money and we're casting around for something to do". Nice problem to have :)

4
  • 1
    I wouldn't say we either have too much money or too many developers. (Kevin Montrose, our lead developer, is also the Data Team lead, for instance.) Documentation is a long-term investment (and a bit speculative at that). We aren't really focusing on the market just yet. There's got to be a useful product first. I assume you are talking about this page? I'm not sure what's good about it, so maybe you'd be willing to answer this companion question?
    – Jon Ericson Staff
    Commented May 23, 2017 at 16:41
  • Benjol, it's actually that they have more developers than their money can support, and they're trying to put them to work instead of laying them off. (I'm not aware of any actual discussion of layoffs, but as of their most recent VC round, the company was not profitable, and their focus is on finding money. Maybe the revamped SO Jobs got them back in the black, maybe not.) Commented May 23, 2017 at 23:34
  • @JonEricson, I must admit that I was harking back to when Books Online was offline - so yes, that was the first page that came to mind. I see that there is something more up-to-date here, which seems fairly complete.
    – Benjol
    Commented May 24, 2017 at 5:42
  • 3
    @JonEricson, I can't quite get my head around the notion of how one defines a "useful product" without having an idea of who would use it, i.e. what the market is. The challenge for SO is that you also have to dream up the "demand" of the "supply": people who want to provide the content for free.
    – Benjol
    Commented May 24, 2017 at 5:44
4

In many real world applications, a lot of programs and tools go into making a working product. For example, some games I've worked on included C++, python and a working a knowledge of windows file systems hierarchy. Past projects included things like linux and docker, batch scripts in hybrid with vbscripts and so on.

How documentation is structured now is that there is only examples pertaining to one item or tag. There are no connections or ties to other languages or programs that can have the most enlightening and practical applications of each. As such the documentations current set up is ideal for beginner programmers or newcomers to the language, and thats fine!

What i am suggesting is to keep the current structure, with examples dedicated to each language alone, but add ways to cross link documentation with other tags to produce more advanced examples. I'd like to see what interesting things I can do with a C++ and Java program, or see how someone mounted C++ to working iOS devices, and that is difficult to do when all the documentation is relating to one subject alone, or a "Tag Only" documentation.

// Examples of the Issue:

1.) I'm sure many of you have heard of the LAMP stack, but for those of you unfamiliar, its an abbreviation for using Linux, Apache, MySQL, and PHP/Python/Perl for web development and is considered the most popular development stack in use today. Because stack overflow is so awesome, there are already documentations of all 4 tags each with detailed examples to each application alone.

However there is no documentation relating to the LAMP stack itself. Sure there is a tag for it, and its already got some backers but if it does get turned into documentation then what? Are we going to write documentation for things that already exist both on stack overflow through already present documentation and through the world wide web?

What many people seek is "What can we do with the LAMP stack?". What programs and applications can I combine to produce a more invigorating end product? This is the kind of documentation that the current structure can not provide because its based in a "Tag Only" documentation, where only tag relevant information is allowed.

~~~~~~~~~~~~~~

2.) JavaScript, which bears some resemblance to Java, has seen widespread use across the web for creating dynamic and interactive webpages. Even the thing that's allowing me to type this suggestion to this webpage is being maintained with JavaScript's. Again, stack overflow is already awesome and has documentation relating to, again, the language alone.

However JavaScript is tied heavily into other applications such as html, and often has to be specially configured to work with mobile devices. Should we make a tag for documentation on JavaScript for mobile devices or html? NO! We already have documentation for each topic alone!

Topics like these already serve a bulk of the questions you can find here on StackOverflow. These questions are multi-tagged, asking for expertise from people interested in those array of disciplines, and yet the examples people provide can never be written down because the current documentation structure demands for only relevant information to 1 topic alone! Documentation would benefit greatly if people can post their examples, tag it as so to link it to each documentations home page, so users interested can browse their favorite tags to find something new to try out.

// Conclusion:

StackOverflow is structured to be a Q&A for any programming questions. As time goes on, and more services and applications are integrated, the questions that people will ask will become more complex and the current documentation structure will never be able to combat these kinds of questions.

Documentation should maintain a similar structure to the Q&A version, in that questions pertaining to multiple fields can be seen by multiple people. Having documentation to just strictly be for one field of information will never be able to produce a significant amount of meaningful or practical applications in the real world, so allowing people to post examples with relevance to multiple tags will serve as a better basis for documentation.

// EDIT

Possible duplicate of Travis's answer here, if not more refined. Consider for merging.

3
  • 2
    Yes, I think the real market for Documentation isn't rehashing the same basic concepts found in individual tags, but mashups of seemingly disparate technologies only a few people are using together. Maybe you need to integrate a legacy database into your Node.js app. Unless one of the handful of other people who have done that have written a blog post or whatnot, there might not be any information on how to do that. Docs on Stack Overflow might provide just enough incentive to encourage that developer to write down their experiences, tips and suggestions. But it's hard when siloed by tag.
    – Jon Ericson Staff
    Commented May 26, 2017 at 16:31
  • @JonEricson Exactly. If users weren't restricted to share these things, Documentation would see a massive increase in activity and useful examples. Then for each example someone shares and someone comes across something useful or an improvement, they can tell the example creator "Hey you should try considering this" or "Hey i found a more efficient way to do what you want" further increasing everyone's knowledge about the subject.
    – Jouster500
    Commented May 26, 2017 at 17:16
  • I like this idea! Maybe a super-tag called "tech stacks" where each topic is a unique combination of technologies (from programming languages to cloud infrastructures) with working examples to illustrate what can be done with that particular combination. This would be very useful. Like techstacks.io -- but this would be a collection of reproducible examples Commented May 27, 2017 at 11:36
4

I think that addressing the structure is important, and since I don't know what changes to expect, I can only hope that they will not be a one-size-fits-all solution.

I don't think Programing languages documentation structure should be the same as a library structure. Example: jQuery UI vs. JavaScript - While JS structure should emphasize about functions, syntax, runtime errors etc.., jQuery UI should show usage examples with the different (And limited) features this library has to offer.

The last thing I suggest is to step down with that absolute collaboration idea - I hate it. It made me take a step back from the documentation:

  • This great song pretty much sums up the current state of the documentation as I see it.

  • I don't want to get my submitted changes approved/rejected by any user. I want to know that the decision was made by someone who know what they do - Professionals in the field of the topic, and also Professionals about StackOverflow community.

  • Anybody approving a change should also speak fluent English (Which rules me out).

  • There must be strict rules, not just general recommendations. We must clean the documentation and remove code-only examples, super short ones, duplicates and so on.

  • I need to know that it's being monitored and moderated. I want you to kick the hell out anybody who is caught plagiarizing. They should not be a part of this. NEVER!

What I really trying to say is that you should consider appointing a documentation-moderators for every topic, they should decide and direct about the structure and set a quality standards for examples:

  • A documentation-moderator must be highly motivated to contribute and responsible, just as the real moderators here.
  • Only specific and chosen users will have the final say about what goes into the documentation.
  • If possible, they should have a gold badge (Or at least silver) in the tag they moderating.
  • They will edit, approve and reject the submissions from the rest of the "regular" contributors.
  • They should coordinate (In a closed chat room) about macro details (Missing topics, need improvement examples etc..), but one of their votes will be enough to approve/reject/delete any submission so that we don't have to wait too long.
  • There should be more documentation-moderators on active topics.
  • Of course, our real and beloved moderators will always be able to overrule any decision made by a documentation-moderator.
  • Being a documentation-moderator should be for a limited time (Not sure how much), and a good documentation-moderator should get a special new gold badge, and maybe as a token of appreciation - A goodie bag with SO t-shirt, mug, stickers and a pen.

I believe that with good guidance there is a really good chance to make it work.

9
  • I didn't want to get too specific in my question, but we definitely will be considering having multiple templates for different types of documentation. Once we finish our T-SQL experiment, we'll pick something that might not work with the same structure we land on for that tag. I think we can address some of the pain points you discovered with collaborative editing, but I'm not sure the specific moderator scheme will work out. It might make sense for super popular tags, such as Java and JavaScript, but it's not going to work for tiny tags that arguably are in the most need of good docs.
    – Jon Ericson Staff
    Commented May 30, 2017 at 18:00
  • @JonEricson That's fine, I wrote my suggestion when I saw you immediately replied to the last suggestion, and I just had to post my suggestion too knowing that it is very diffecult to implement. But it sums up all the disappointments I experienced so far from the documentation and the things that could have helped me continue contributing again. I guess the TL;DR is - Strict moderation, having a Creative/Technical directors, and solving the current state of fragmentation
    – Alon Eitan
    Commented May 30, 2017 at 18:10
  • 2
    Over on Wikipedia there's a concept of stewardship, which is not exactly ownership but with some of the benefits. I think in the long term every collaborative system will develop a similar system. It's not our focus right at the moment, however.
    – Jon Ericson Staff
    Commented May 30, 2017 at 18:33
  • @JonEricson Thank you. It was very interesting and refreshing thing to read, it helped me to better define and identify a state with some sort of a failure/malfunction and what can be done to address it. I'm more at ease now, knowing that you're aware, and choose not to address it, at least for the moment.
    – Alon Eitan
    Commented May 30, 2017 at 18:50
  • 1
    Documentation moderators: nice idea, but here's my question: where do these moderators go to discuss coming to a consensus about how to approach their topic? I committed to [Minecraft] back when Docs was just getting started and when it got 5 people it stayed dead for months because I wasn't sure how to put the content I had in my head into the template. But I had no way to ask the other four committers what we wanted to do, what good content was. I still have no idea what constitutes good content. Commented May 31, 2017 at 15:59
  • @Draco18s I thought about a private chat room, where you can have nice and productive conversation (Like this room that I like). I don't know how to fix the documentation though - But I do know that other, much more experient people might know how to take if from here - And I'll be happy if they would to take the reins and lead, and I will be happy to follow them
    – Alon Eitan
    Commented May 31, 2017 at 16:12
  • 1
    I wouldn't necessarily want it to be private (suggestion taken, filed, marked "todo") but that might work. Now to figure out who the hell the other committers are... Commented May 31, 2017 at 16:17
  • @Draco18s Yes, I think you're right about not having a private room. I thought that it will help to reduce "noise", but coming to think about it - Being able to to share ideas and to provide a constructive feedback is very important,
    – Alon Eitan
    Commented May 31, 2017 at 16:21
  • 1
    Yep, basically I want a "[tag]Docs meta." ;) Commented May 31, 2017 at 16:22
3

I'm quite new on SO but I think I got the gist (;)). What I had in mind when I saw the documentation headline was something like

"Perfect, I might be able to use what's in there to learn a language\concept\whatnot from the bottom up, albeit with a bit of logic and (not-so) common sense"

But what I found there wasn't like that at all. So, my idea for documentation is a place where you'll find the answer for:

"I want to learn\better understand <insert name of language\algorithm\concept here>, but have no idea where to start"

(Which may cut down the number of questions posted on SO that request that)

In fact, it is actually restructuring the order and relations between existing examples. (And maybe adding half a sentence between examples)

2

It seems like there is prior art in this area. Jupyter/IPython notebooks come to mind as quite similar to the need that has been articulated.

Interactive execution + arbitrary multimedia/HTML as needed.

Of course only 40 languages are currently supported in the example I gave, but it could be extended.

  • CS-Script is supported (e.g. a script form of a "typically compiled" language).
  • The existence of interactive C++ implies the approach could work for (anything?) Wikipedia description.

I'm failing to see what's new/needed with Stack Overflow's version of this concept.

8
  • Does Jupyter support rep-tied, peer-reviewed editing and SO integration? Is there a large-scale project for general documentation of anything that needs it? No? Then there you go. Commented May 20, 2017 at 8:50
  • 6
    @NathanTuggy StackOverflow documentation is not peer-reviewed. Random people upvoting and downvoting things is not peer review.
    – mrr
    Commented May 20, 2017 at 14:36
  • 1
    @MilesRout: I think you mean it is not correctly peer-reviewed. There is clearly a deliberate design effort toward that end (and it's likely that that will be improved further). Jupyter does not appear to include anything vaguely resembling that in its basic design. Commented May 20, 2017 at 19:08
  • 2
    @NathanTuggy Nothing on StackOverflow is peer-reviewed. Nothing on MathOverflow is peer-reviewed. Peer review is double-blind review by experts in the field, and randoms voting on answers that look right or work right for them is not peer review.
    – mrr
    Commented May 21, 2017 at 23:40
  • 1
    @MilesRout: OK. Then pretend I said "reviewed by peers" or something else instead if that helps get past the incorrect idea that I was referring to the formal scientific process of preparing for publication. The point is, Jupyter doesn't seem to have any of that, not even the knock-off stuff that SO uses. So no, SO is not a "peer-reviewed journal". That doesn't mean peers do not, in some fashion, formally review the work as part of the system, if much less rigorously than one could wish. Commented May 22, 2017 at 2:31
  • @NathanTuggy sure, I'm fine with saying SO answers are 'peer reviewed' through voting/selecting answers. But this is on the basis of per-answer (or per-question) votes. So a documentation answer would be reviewed/community-voted/etc in the same way; it would just be a more powerful mix of code/multimedia, and leverage an existing framework; I guess it seems like some of the SO documentation is re-inventing the wheel rather than extending current, widespread tools. Commented May 24, 2017 at 16:54
  • Regarding whether a iPython/jupyter notebook could be peer reviewed in the same way as an existing SO answer/question: those answers/questions today may be edited by the community (of sufficient rep) and those edits don't change/invalidate previous 'peer reviews' ... so using the jupyter notebook as the documentation implementation still wouldn't change this. Commented May 24, 2017 at 16:55
  • @mike: I guess my point originally was that if you want to use Jupyter for e.g. the editor component, that's fine. But you're going to have to either hack it extensively to make it work with rep and votes — exactly the areas current SO Docs struggle with most — or else you're going to have something that does not meet the basic standards of SO integration. So it doesn't solve the biggest problems, just shuffles them around some. Commented May 25, 2017 at 1:08
1

Has anyone proposed noting existing exemplary documentation projects and identifying what general principles they exhibit that make them exemplary?

If we did this, I think we'd quickly arrive at a core set of general types or structures, as well as some guiding principles that apply across all general types. Building Documentation to support these types and ideas would at least make it possible to facilitate the creation of similar high-quality docs for any language/library.

This is separate, but foundational to the question of how to correctly incentivise quality contributions and QA.

4
  • 1
    "Has anyone proposed noting existing exemplary documentation projects and identifying what general principles they exhibit that make them exemplary?" Yes. This was actually mentioned in the very post you're replying to, with a direct link to a question asking for exactly such examples. Commented May 22, 2017 at 19:22
  • 1
    @NicolBolas I've read the What's Next? section of the OP as well as the T-SQL call for input question you referenced. The T-SQL question does ask this, but only for T-SQL. What I'm asking is if anyone's proposed starting with all "great docs" to identify patterns/principles, rather than picking a specific technology. As the OP says, "If we do it right, there’s a good chance the structure won’t work so well for, say, JavaScript, .NET, and Git." It's for this very reason I'm suggesting it may be good to gather a variety of good examples to begin with. Commented May 23, 2017 at 17:42
  • 1
    The point of picking a specific technology is so that they can document it, then compare the effectiveness of that documentation with existing work. That's how they're planning on moving forward, so they have to pick a specific thing. And they picked that because it's something that they know well enough to be able to document. Commented May 23, 2017 at 18:57
  • I think this initial first step with T-SQL is a good one and understand and agree with it. My question is whether a parallel broad assessment could help balance the overall effort by providing some big picture points that may not be as apparent from this initial case. Commented May 30, 2017 at 15:05
0

Maybe this has been proposed before, but what if documentation was restricted to information that could not be framed as a question suitable for a Q&A topic? So you have high level, conceptual questions which then are associated with specific questions linked from the Q&A part of the site.

e.g. For the question/category of: How can categorical data be plotted using matplotlib? This would basically be a much better/comprehensive version of this matplotlib docs page maintained by SO users and linking to Q&A questions.

And then you have really low-level API kind of documentation that duplicates what the developer should be (or is) doing, but also improves on it. So now we're talking about a much better version of these kinds of matplotlib pages. Again, examples (in the form of linked SO Q&A questions) would be associated with particular functions/methods/classes or whatever.

Don't know what exists or what you're looking for and you want to learn --> Documentation overview that is organized somewhat similarly to how docs are now, except there is no substantial content in the docs pages, there are just links to relevant Q&A questions. No good Q&A question exists for a topic/task you think should be there? Ask a relevant valid Q&A question and link it! (and better yet answer it!)

Don't know all of what exists, but you know what you're trying to do --> Do the normal google search for a relevant Q&A question. Nothing comes up? Double check the high-level docs for your topic to make sure there are no relevant Q&A questions you're missing (I'm imagining that these are the kinds of questions that might only show up after going a few clicks deep through "Related" or "Linked" questions to a kinda-similar Q&A question you happened to land on--the questions that don't show up on your original google search because the OP didn't really know what they were asking and the title is misleading). Still can't find anything? Ask a question, or check the low-level API doc functionality.

Know what you're trying to do and know the functionality must exist, but it's poorly documented. It's such a small and specific thing that you don't want to ask a question, but you could really use some references. Maybe if you made a Q&A question here it would be marked as a duplicate. Maybe you don't think it'll get attention fast enough, if at all. The developer referenced this functionality, but it's not in their docs! Check the SO low-level documentation!

Summary:

  • High level docs are really just a way to organize Q&A questions around specific topics (these are probably around the same specificity as a specific set of tags). They link to relevant Q&A questions.
  • They also link to the low-level API docs which are a better version of what the developer should be doing, maintained by the community.
  • Q&A questions link to what high-level conceptual docs they are a part of, and what low-level reference docs would be relevant to them. Thus, this is more of a horizontal kind of organization between Docs and Q&A, not a hierarchical one.
  • Problems this solves: No effort is duplicated on docs that is already a part of Q&A. Deals with the problem of developer docs not being complete enough. Helps organize the mass amount of knowledge already available through the Q&A part of the site, and guides beginning programmers through the most useful Q&A questions to begin learning about particular topics or languages.
  • Problems this doesn't solve: I can see the SO community being very good about organizing Q&A questions into conceptual and task-oriented categories (especially since existing tags would be very helpful for this), but we still have the problem with getting high-quality API-style documentation. I like the idea of keeping the reputation of docs separate from the Q&A--not that this solves the problem though.

Q&A Scope:

  • Tutorial and task-oriented documentation

Docs Scope:

  • Conceptual (broad topics) and reference (API) documentation

Sidethoughts:

  • Regardless of the path forward for docs, I think we should be sharing more example docs pages that we get inspiration from, or use as conceptual templates. I love how seaborn (a python package) organizes their docs. Lots of right-level-of-detail examples, and also streamlined API documentation. They're still missing some of their API info though.
  • Docs should perhaps include example data sets where necessary? ... although I'm not sure how these would integrate with existing Q&A questions
4
  • Anyone who downvoted care to give feedback? I'm interested in what other flaws people see or suggestions!
    – spacetyper
    Commented May 24, 2017 at 22:47
  • I didn't downvote you but at first glance it seems too complicated and too restrictive. Remember that if a concept takes more than a single second to grok you will get lots of frustrated users (even among developers). Adding rules always poses a risk of being counter productive. Many say Wikipedia participation has tanked because of the byzantine like rules that have evolved and the over zealous moderators who actually enjoy enforcing them. Commented May 25, 2017 at 0:13
  • That's a totally fair criticism. I really think that docs shouldn't duplicate what's already on SO though, so it seems like it needs to be more rigidly defined. So far it's been pretty wiki like and is a total mess. Maybe it's just totally the wrong product though.
    – spacetyper
    Commented May 25, 2017 at 0:50
  • If it helps, I upvoted. I think your basic idea is a good one: We don't allow broad questions in standard Stack Exchange sites because it makes succinct answers difficult and frankly harder to understand. However documentation is exactly what answers broad questions... rtfm is rtfm for a reason, and I'd suggest that the manual is synonymous with the documentation.
    – MER
    Commented May 30, 2017 at 17:30
-2

I have been thinking about writing this for a while now, and I feel this is the best time to put my pen to the paper. I will start with a proposal on what I think Documentation should be, then try to justify each of the changes. Sorry if some of it has already been said.

The proposal

Different kind of documentation pages

We have two types of documentation pages:

  • (Core) concepts
  • Plain old API references

(Core) concepts would be a more traditional page, just like I am organising this post. It will have headings, and explanations under these headings. There will be examples on these pages, but only to supplement explaining these concepts. The order of parts will be fixed, and can be changed by editing. Voting will be a side-activity and not very visible to someone visiting the page, and will only serve to give "thanks" to people that wrote a particular paragraph, and to spot bad or not useful parts of the documentation.

API references will be more like the current documentation, in that there will be a parameter section that shows how to use something in particular, and a bunch of examples. Besides parameter lists, the section will make it easier to indicate what return values can be expected, and which exceptions can be thrown.

Hierarchy

We can organise both types of pages with some kind of hierarchy system. This hierarchy will be visible at the top of the page. This allows the user to quickly see what they are looking at, and find their way to similar documentation if this was not quite what they expected to see.

Current documentation pages very much stand on their own. By adding hierarchy and breadcrumbs, the user can easily navigate to related documentation posts and is able to more easily place information in a larger context.

We could go as far as pulling relevant information from child pages into parent pages (e.g. Library X has methods x, y and z, so on the page of Library X we display these methods with the first example). This allows us also to write about things that may not really warrant their own page normally as the best content of that page is easily visible in a more general scope, really leveraging the fact that we can add a lot of overlapping examples and let the best ones bubble to the top, without having to worry that we have to fit some arbitrary topic in some arbitrary amount of examples.

Easy access

The "root" elements of the hierarchy should be easily accessible, for example via a separate box in the sidebar. This will for example outline the core principals of a particular framework, how to get a minimal workable product and the root components of the framework (e.g. if the framework has controllers and views, this would be a great place to put a link to Controllers and a link to Views).

From any page under a particular tag we can go to a different part of the documentation via this box.

Search by hierarchy

Now that we have hierarchy in the pages, we can search for a particular part of the documentation using the hierarchy itself. If I navigate to PHP, I should by default search under php, but be allowed to change this. If I navigate to a page "Controllers", it should by default search under that particular page and let me easily choose to search more generally if needed.

Search results should be grouped per page title and should display what is relevant on that particular page. Example titles are totally useless in this view and should not gain any priority to be displayed. If 7 examples under a particular topic match my search criteria, having them all 7 displayed as well as the topic title itself does not improve my search experience.

The justification

Structure first, examples second

The current version of Documentation lacks any sort of focus. The structure is completely flat. The list under each tag does not help in any way to find what I am searching for. The list does not help to understand what a framework is all about, what it is good at and what it's weaknesses are. The introduction topic is a collection of examples (by design) that leaves the reader with more questions than answers. At least they can copy paste the code and see that it works... more or less. That might be the only good thing about it. The search function does not help find what you are looking for either, usually showing seemingly duplicate entries, either example titles that are too short to really know what is under them, or too long to properly read. I found myself having trouble to locate things I have written myself on both occasions I tried to find something for a co-worker. If I have trouble while exactly knowing what I am looking for, how is someone visiting SO Docs normally supposed to find it?

While examples are great, and SO Documentation should always explain things based on examples, examples without context are not useful. The only way to currently provide context is to write about larger topics. Take for example PDO. PDO is a library for PHP. On SO Docs we have captured this entire library in 6 examples. That in itself makes it far less than covering the subject. Who does it help to read this topic? Likely only someone that heard about PDO and wants to learn a bit about it. It still does a bad job at telling the reader exactly when and when not to use it and is probably also unsuitable to make anyone comfortable with using the library. It is a bad reference for people just wanting to look up the naming of a function, or the return values/exceptions it can give.

By changing it to have a "topic" per function, we gain a few things: - We can add multiple examples per function. If one example does not help you, an other might. Good examples can bubble to the top, just like good answers bubble to the top in Q&A. Right now we are stuck with half an example dedicated to a specific function, which is often buried in an example you didn't really know to look for in the first place. - We can provide context by navigating to the parent page, or by being on the parent page where the top example is loaded in. One could even load in the parameter section on the parent page. If more information is needed, one can always navigate deeper to get more information.

But you could accomplish the same with linking

No, you really can not.

Linking helps to group similar things. Hierarchy helps us in seeing the bigger picture.

If you ask me "How do I use query()?" then I ask you: "Which language?" and "What library are you using?". These are abstraction layers. Things to group information in our mind. By introducing hierarchy you introduce a standardised way of navigating in this hierarchy as well as providing context for what you are about to learn, and how to get back there.

Unlike linking, hierarchy also provides us with a starting point and allows us to dive deeper if necessary.

Splitting core concepts and plain references

While concepts and references go hand in hand, and you will need to link extensively between the two to get any kind of coherence, they are two very different things with two very different focus groups.

An API reference is something people use when they can't quite remember if the function ticklePolarBear threw an PolarbearOutOfRangeException or just returned null. Examples are useless to them, and the current topics are way too broad for them. They would benefit from SO Docs because the existing documentation may be spreading this information over an entire page, or may be ambiguous when certain things happen. One can link this API reference from an Stackoverflow answer instead of an external resource, or a current topic where the information is buried... somewhere.

A core concept is useful to outline how to accomplish certain things in a language or library. Something that comes to my mind is the concept of "Props down, events up" in Vue. It is a particular topic that is easy to mention on a Stackoverflow answer, but might require additional reading. In a documentation topic one probably wants to start with explaining what this principle actually is and why it should be used over something else, then start building on top of that. You probably want to explain first how to convert regular "event down, event up" to this principle, then explain how less common constructions can be avoided by using this principle. In the current SO Docs you would end up putting them in arbitrary examples, which get shuffled around for no apparent reason and make reading the entire thing a nightmare. People that have never heard of the principle and are just browsing the documentation will currently not find the topic either.

By having dedicated pages for "core concepts" we can have the structure fixed, focusing on readability and natural progression. It will be linked from the sidebar allowing people to get familiar with the framework/library/language faster. You don't have to bombard these people with arbitrary examples or arbitrary API references, because this is not the reason they are reading documentation.

Showing different search results

As a developer I often find myself knowing where to search for some information, then quickly navigating to something I need to know. If I know that I need to find something in the Mysqli library, it is not useful to me to search in the entire php tag. Being able to find what you are searching for should be the top priority of any documentation. Hierarchy helps with that, but search is a good help too.

By showing information from the example itself one can judge quicker if it will be helpful. An example title "Introduction" does not tell me much. By limiting the search to a particular area one has to go through less results to find what they are looking for.

By grouping examples under a topic title it will be immediately clear which generic topics might contain my information. It also tells me about the scope of a particular search result. If there is hierarchy in the topics itself, one can even group topics together in this view.

3
  • 6
    Why are people so willing to limit organization schemes to simple hierarchies? Why not full-fledged directed graphs? Commented May 21, 2017 at 16:27
  • You can implement that as a category system I suppose. Can you give an example of documentation that should be listed under 2 or more categories though?
    – Sumurai8
    Commented May 22, 2017 at 6:35
  • 2
    Yes. A Vertex Shader is both a stage of the rendering pipeline and a shader stage. And that's just the first thing that popped into my head. Commented May 22, 2017 at 13:35
-2

Try a new concept, that is fundamentally different than other Stack Exchange sites.
Proposal Details

  1. Create documentation that consists solely of two things
    1-A stated problem/purpose/use case for which code is needed or designed to fit
    2-Example code to match that use case
  2. Anyone can create a stated problem/purpose/use case (a documentation item for short)
  3. These documentation items are created much like SO questions now... with a few differences:
    1- It is completely fine & expected for someone to provide an example for a documentation item they created.
    2- a slightly different, but very similar, documentation item would only be considered a duplicate in the instance that it is really the exact same documentation item but worded differently, but if there are nuances to the second, very similar, documentation item then it would not be considered a dupe
  4. And now, for the part I expect most people to disagree with, no one can edit or remove another person's example code
  5. Finally, there would be voting on documentation items and voting on examples as normal for stack exchange sites (minus the focus on things being similar automatically being seen as dupes).



Some points of clarification:

  • There really is a lot of good documentation around the internet, really there is. It could even be argued that standard Stack Exchange sites are some of the better forms of it.
  • While there is a lot of good documentation it could be said that there are also many different views on what good CODE is. If I could remember who said it I'd link it here but it's been said that any programmer seeing either their old code or someone else's will automatically think it's bad and want to change it. THIS is what we are fighting with this documentation with examples... human nature.
  • By not allowing the examples to be changed but only downvoted or upvoted, we don't lose the perspective of someone who may have a very good methodology.
    Functional programming, for example; most programmers ten years ago would likely have seen any code leaning toward functional programming as horrible code, now many see it as an advancement, despite the fact that it's not new.
  • Regardless of what we all think, we are all right sometimes and wrong sometimes... which means our old code is probably not as bad as we think, and neither is fred's code that we had to take over...
  • Finally, this would be the only way I can see a NEW service to add value to documentation. It would become a library of examples to look at, learn from and decide for ourselves (as the programmer looking for example code) what is good and what isn't.



Anyway, it's a thought, a potentially new one... despite that, I hope someone might find it valuable.

8
  • Seems like maybe your proposal is incomplete? (Also, the disclaimer doesn't seem very helpful or correct at this point. Someone seems to have upvoted before I arrived. ;-)
    – Jon Ericson Staff
    Commented May 30, 2017 at 15:38
  • It was me who upvoted, and I agree that this proposal is incomplete but it reflects what I feel about the documentation where I just can't see where's it going and how it can be saved. A few days ago I deleted so much bulls**t from the Angularjs tag, and on the tags i'm following nothing happens - It's all in a standstill. Not fun anymore, not exciting and I can't see what can I do to make any contribution at the current state of the project.
    – Alon Eitan
    Commented May 30, 2017 at 15:42
  • @JonEricson Yeah, not even sure what keys I hit but apparently they equaled post... lol... fixed it in edit... (well fixed might be a relative term)
    – MER
    Commented May 30, 2017 at 15:51
  • 1
    @AlonEitan Yeah, I really think that a wiki is a better solution for this type of collaboration... or a more open rules version of SO... (maybe?) but to have it work and actually provide value that will draw people I think it needs to be a much different concept. Fundamentally I think this is a tough one because, as programmers, we tend to think whatever we are doing right now is ideal, (for good reason really). Unfortunately this leads to us seeing most existing code as bad, which is also fundamentally true... nearly all code has weaknesses... anyway tough nut to crack.
    – MER
    Commented May 30, 2017 at 15:59
  • 1
    And after reading the full proposal I agree with it even more. That so-called collaboration where anybody can overwrite anyone else's edit, combined with a hint of plagiarism, made me take a step back
    – Alon Eitan
    Commented May 30, 2017 at 15:59
  • @AlonEitan Definitely a concern for me too. The one time I contributed there seemed to be an assumption I didn't put any effort into what I had written or that there was no value in it (as it was literally all removed...) even though what I shared was real world stuff that I'd actually used in utility code... AND the person/people who replaced what I wrote said enough of the same things that it felt like it was rep whoring more than an attempt to provide good documentation. (it could also have been a bug in documentation but that was how it felt to me)
    – MER
    Commented May 30, 2017 at 16:12
  • 2
    One argument we've heard is that Documentation's use case is already adequately covered by Q&A. I think this proposal overlaps even more than the existing system. Questions are, in many cases, specification for a particular need and answers are very rarely edited for more than minor fixes. The difficulty is that very old answers have received many upvotes and people are reluctant to change outdated code (unless stopped working). Collaborative editing ought to reduce that fear and encourage updates down the line. (Not that we are there yet, mind.)
    – Jon Ericson Staff
    Commented May 30, 2017 at 16:40
  • @JonEricson Yep, I see where it's similar and that we have a half baked version of what I described in the form of SO already. I suppose my point is that IF we want to provide something of value in the form of documentation that's not a wiki, then a library of code is a decent alternative, which SO can not provide in its current state (as it's seeking the ultimate answers and ultimate questions as provided by collaboration... and I think this is done very well with wikis for documentation...). So I suppose most will see this as a dupe of SO where I disagree that it's a dupe :D
    – MER
    Commented May 30, 2017 at 17:26
-3

This sounds fantastic. My first thought is that one could (at least for Python) use the existing Python documentation at python.org as a framework of topics/sub-topics to start with.

My second thought is that this has the potential to be amazing. All the hated, beginner-level questions (where the real issue is 50-50 beginner not knowing how to ask their question // laziness) can be closed and redirected to the documentation where there are already great examples with the answer they need. This could simultaneously accomplish the creation of documentation and solve some of the issues with SO.

Rather than debating whether a question is equivalent to already answered, etc, redirection to documentation/examples that a user can see answers their question (I think sometimes it's hard for beginners to see how the duplicate questions they are pointed to answer their closed question). The only issue I see with this is a potential overload of examples, but maybe accompanying explanation will assist with this. Or maybe a dedicated chat room for assisting there?

Whichever way this heads, it sounds exciting. I see potential for migrating and editing existing SO answers for more general application. There's some great answers on SO that deserve to be seen by more people.

6
  • Documentation will only be useful for QA if it is effectively a re-creating of existing documentation. I don't think that's what SO Docs is/was supposed to be.
    – Kevin B
    Commented May 22, 2017 at 15:17
  • @KevinB: Well, for one thing, it's not supposed to duplicate existing documentation. I suppose it won't help to point you to all the things we've written to explain the goal. The only thing we can try now to help out is improve the product to the point where it becomes obvious that it's either meeting the goals or the goals are unobtainable. A priori assertions aren't worth a whole lot.
    – Jon Ericson Staff
    Commented May 22, 2017 at 18:09
  • 1
    @JonEricson Right, my point was that for it to be a useful tool for QA, the example would need to exist on SO Docs. so any case where the problem is already well covered in the official docs, it wouldn't exist in SO docs and therefore wouldn't be useful for QA, we'd instead be doing what we currently do which is provide an answer re-gurtitating docs or dupe closing. It's like only half of a solution. I think it needs to be a recreation of official if we want to be able to tie it into handling common Q/A questions that are covered by the docs. Otherwise... it's never going to be anything ...
    – Kevin B
    Commented May 22, 2017 at 18:17
  • ... more than just a suggestion list of topics on the right.
    – Kevin B
    Commented May 22, 2017 at 18:17
  • 2
    @KevinB: Ah. I misunderstood your comment. In the beginning, we had people ask if we were going to just copy in documentation from other sources. The answer is that even if the licensing worked, we would not want to essentially fork content. But if Docs needs to cover the same material as an external source and people are willing to write (and review) the content, that's not a problem. Duplicate broad questions are a good indication the official documentation is lacking something. So having a good answer (or topic or whatever) to explain in different words is clearly useful and not a waste.
    – Jon Ericson Staff
    Commented May 22, 2017 at 18:29
  • Well I've been finding Documentation useful in answering questions I've had. I don't understand how "working together to build the best reference material for developer tools on the internet" could be both successful in that goal, and not innately be able to answer questions? Commented May 22, 2017 at 18:51
-4

This may sound as very wild recipe for Documentation / Example success, but if the new system will please copy-paste style of programming, it will have tremendous popularity. Actually, SO already almost works like that: Type what you want to achieve into google search, and there comes 2-3 useful and copy-paste-able pages with examples: Natural language programming!

A bit more semantics, maybe, tweaking parameters, and here it goes.

Say, rookie searches for "print all lines in a file". It goes to the hub of that task, where rookie can choose the programming language, paradigm, maybe version, if applicable, and get production-ready code.

There could be options, like, whether the file is readily open stream, file path, file-like object, URL, S3 file, ... - these can be appended / prepended.

And yes, then StackExchange can even sell that to, eg, IDE developers, as well as offer to the public.

Implementation is certainly not as easy as a bunch of textual objects rendered together, and require more semantics, maybe type / logical / whatever reasoning, but I see no fundamental blocker provided all that wealth of data on SO.

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