31

The current documentation model is focused on a set of arbitrarily defined topics, within which are examples.

I believe that this model has led to widespread confusion about what Docs.SO is for, and therefore widespread misuse of it. People are making topics and examples for things that we were probably not intended to document. In some cases, people are just copying&pasting stuff from existing documentation. In turn, this has led to people trying to clarify how it's supposed to work. Or just trying to establish it, since nobody seems to know.

Q&A is designed in terms of a "problem->solution" model. A person has a focused problem, and thus asks a question. People post answers which represent solutions to that problem.

But in the early days of SO, we had some problems with people expanding this model into more opinionated questions that did not represent problems to be solved. Eventually we clamped down on that, focusing the scope of the site, not really on Q&A, but on problems&solutions.

Docs.SO's model is topics and examples. But these concepts are so nebulous that everyone interprets them differently. Just like SO's early days of Q&A, people aren't really sure what a "topic" is.

I think a better model for truly code-focused documentation is not so much topic&examples, but task&examples.

Tasks are things that are bigger than Q&A's focused problems. These would be something like "string searching". That's not a focused problem, since there are a lot of cases of string searching, so it wouldn't work as a question. But as a task, it is much more reasonable.

You would have examples of various kinds of string searches: basic exact matching, regex searches, Unicode-based, case insensitive searching, and so forth. If there are commonly available libraries that can aid in searching, examples can be made for them too.

When you have task-focused documentation, voting on examples now makes sense. The examples are effectively competing with one another. Each one represents a complete solution through different approaches. And while different approaches may be valid, some are very much so better than others. The order of examples in a task is relevant only in how good those examples are at accomplishing that task.

So rather than documenting how regex works in a language, we would instead document the things you would use regex to do. But not in a "with regex" kind of way; we allow regex to be one possible example of dealing with that task. We focus on getting stuff done, not on the minutiae of syntax.

That would prevent us from getting involved in creating reference documentation. It would keep us focused on what we do well: solving things. Docs.SO should be generating cookbooks of usable code, not rebuilding reference manuals.

This would also solve one of my biggest issues with the current system: topics for which code examples cannot be provided. They simply would not exist, because there are no topics; there are only tasks. And tasks are things that have to be able to have code.


This answer from Kevin Montrose seems to agree with this point of view:

  • The primary focus of Documentation is clear and concise examples.
  • Examples should illustrate solutions to common problems and ways to accomplish common tasks
    • Examples should be broader than the typical answer. Q&A still exists, after all.
  • Syntax, Parameters, and Remarks support Examples
    • they should reduce duplicate explanations
    • they're optional because there isn't always duplication to reduce

If those are what examples are for, then collections of such examples are not "topics". They very much are "tasks". Tasks define what you want to do; examples show how to do it.


This answer from Oded also seems to support this view:

In general: SO Documentation is supposed to be a source of examples of how to achieve specific things in a said technology.

What we usually see in official documentation is a list of APIs without any explanation of how they are supposed to be used, how to achieve specific goals using them or any examples of usage.

Achieving specific goals? Like a task, right?

9
  • 1
    On this model, we would accept the existence of bad-practice examples, allowing voting to sort them to the bottom, like Answers in Q&A. How does that integrate with the apparent ubiquity of edits and Improvement Requests? It would seem that they'd become subsidiary activities to original authorship and voting: you wouldn't edit such an example, you'd just provide a contrasting one. That would make the Docs interaction model a lot closer to Q&A than it appears now. Do I follow you correctly?
    – jscs
    Commented Jul 23, 2016 at 18:12
  • @JoshCaswell: It would be more Q&A like. In essence, it would be for general "questions" that in and of themselves are just too broad for Q&A. The kind for which no one answer could be complete. And you would edit an existing example, but only to clarify it or make it better within its domain. Commented Jul 23, 2016 at 18:19
  • 3
    I like this "cookbook" model, in particular because, as you say "voting ... now makes sense". But for the sake of argument, what about something like this: stackoverflow.com/documentation/ios/246/… "UILabel", the Topic, is a class; all the Examples are things you can do with the class. These are tasks, sort of, but there's not really more than one way to do most of them. Wouldn't it just be a useless mess to break them out into separate topics? Or is this the wrong level? Is the Topic not "Setting a UILabel frame" but something like "Displaying fixed text"?
    – jscs
    Commented Jul 23, 2016 at 18:47
  • 3
    @JoshCaswell: Tasks are about goals, not the means. Solutions to tasks are the means to achieve them. Whether that solution is a UILabel or something else is a question of the solution's quality. So yes, the task would be about displaying a textual label. Commented Jul 23, 2016 at 18:51
  • What about tasks that can be accomplished in different ways? How would that fit into a doc style?
    – Dux
    Commented Jul 23, 2016 at 19:37
  • 1
    @Dux: They would just be different examples. The task is not "search with regex"; it's "search with string". One (or more) of the examples could use regex to do so. They could use something else too. Commented Jul 23, 2016 at 19:41
  • 3
    It seems to me that this "cookbook" model is much closer to what the team had in mind when they began talking about Documentation. Especially if you read between the lines, with all the focus on "examples" and considering the way it is structured. Mind you, I'm not sure that I am a big fan of it. Every "cookbook" book that I've seen has been...well, shitty, and I don't really understand (has Josh has already said), why the cookbook (problem -> solution) model wasn't already more than adequately covered by Q&A. But at least this might bring some sanity to the anarchy, so you've my support.
    – Cody Gray Mod
    Commented Jul 24, 2016 at 3:18
  • Personally, I'm organizing both around tasks and tools. So "Doing task X" and "Using thing Y for thing Y-ables". An example under X may link to Y ("oh, and by the way, look at Y to get a better grasp of how we solved this and where else this thing may be useful"); and vice versa ("look here to see alternative ways of approaching this problem"). It entails a small amount of duplication, perhaps, but seems more useful than the restriction topics == tasks.
    – Frank
    Commented Jul 27, 2016 at 17:11
  • Given what seems to be the goal of Documentation, organizing by tasks rather than topics does make sense to me. For instance, I posted this under the topic of "Movement", but it would be a much better fit as a task, with each method of accomplishing the goal listed as a separate example underneath the theme of the specific task.
    – zarak
    Commented Jul 30, 2016 at 23:17

3 Answers 3

21

To be honest, with your definition of Docs I don't really see the distinction to Q&A anymore.

Staying with your regex example: In Q&A I can search for my specific problem, and either find an answer "use a regex for this task", or one like "your regex should look like xxx". Before I post a Q for my specific problem, I read several Q&A and try to get the info I need out of them. In Docs, I personally would like to see a topic on regex, that I can read to be able to specify a regex for my specific task, detached from the actual problem. Because that would bundle the knowledge I can get from browsing through tons of Q&A...

One of the biggest things Docs might achieve eventually is that specific concepts that are hard to understand (maybe badly documented originally, or most examples only cover the easy tasks, e.g. matplotlib) can be understood by reading a well maintained, well understandable Doc here. And after that one will be able to solve not a specific but several problems based on that knowledge. And that is not possible with tasks.

18
  • 1
    "Because that would bundle the knowledge I can get from browsing through tons of Q&A..." Or you could look up the actual regex documentation for your language of choice. I don't see how this is any better than this (ignoring the massive quality difference, of course). It didn't become better just because it's hosted here. Commented Jul 23, 2016 at 18:55
  • I can ALWAYS just look up the original documentation. Which may or may not be way too heavy to understand at first or second read. With that argumentation, why write a doc at all?
    – Dux
    Commented Jul 23, 2016 at 19:03
  • 18
    "With that argumentation, why write a doc at all?" Then at last you've come to the fundamental question that has yet to be satisfactorily answered: what exactly is the point of Docs.SO at all? Right now, it is a dumping ground, a disorganized hodge-podge of random crap. My suggestion here is intended to give it a well-defined purpose. If you want it to have a different purpose, fine, but you need to actually state what that purpose is. And equally importantly, a scheme that will actually achieve that purpose. Because Docs.SO currently will only produce what you're looking for by accident. Commented Jul 23, 2016 at 19:26
  • I believe I gave this purpose? Write a doc that is easy to dive in, and that is nevertheless extensive. I understand your point, and you are right, docs IS disorganized atm. But I guess so was Wikipedia back then, and look what has become of it.
    – Dux
    Commented Jul 23, 2016 at 19:36
  • 9
    Wikipedia doesn't have a rep system that encourages bad contributions. Wikipedia doesn't have a built-in structure that encourages contributions that are neither extensive nor easy to dive into. MediaWiki was nothing more than a system for collaborative editing of marked-up text. Wikipedia worked because it managed to create a culture of people who were willing to build and follow certain rules, and it made it easy to make major changes to pages in accord with more reasonable organization. Docs.SO has none of that, nor is it likely to without major, fundamental changes. Commented Jul 23, 2016 at 19:44
  • 2
    @NicolBolas They don't have Rep, but contribution count is also an impressive stat and not totally ignored over there. Also, a major difference is that if you write repeatedly low quality text, you get publicly called out, on your discussion page. That's more stigmatizing than anything we have here. [The downside of that is that you need a thicker skin.] And still, Wikipedia has had some notorious hoaxes and perfidious vandalism long unnoticed … because you can just not verify everything. They do have a lot of bad contributions, but most of them are obvious and reverted. Same problem here.
    – bwoebi
    Commented Jul 23, 2016 at 21:29
  • I believe that the problem statement in stackoverflow.com/tour/documentation, "It was usually written once, often by someone not even using the technology, so it was a guess at what to focus on." suggests that the argument that documentation already exists from microsoft or whoever and therefore does not need to be replicated here is not considered a valid one by the people who made Docs.SO.
    – CWilson
    Commented Jul 24, 2016 at 1:01
  • 1
    Wikipedia is completely different because it is far more free-form than Docs is. In that sense, Wikipedia is much more like our self-answer Q&A. The question introduces the topic/problem, and the answer gives a solution using any format that is appropriate.
    – Cody Gray Mod
    Commented Jul 24, 2016 at 3:12
  • 1
    @bwoebi: "They do have a lot of bad contributions, but most of them are obvious and reverted. Same problem here." No, it isn't. As you point out, people who make negative contributions are punished. We don't do that; the most we'll do is undo the change. Furthermore, Wikipedia makes it very clear what the difference between good and bad contributions are. Docs.SO does not; we can't even decide what constitutes a "topic" or whether a valid example on a language page should include a library written in that language. Commented Jul 24, 2016 at 3:31
  • 4
    @bwoebi: "But you cannot expect that to be present in first days of public beta." ... why not? What was the several months of private beta for, if not to develop those facilities? "I very much agree that we need to first figure out what docs is before everything else." If you launch a service, it's incumbent upon the launchee to figure out what it is before it gets launched. Wikipedia knew what it wanted to be from day 1, and they found people willing to make it into that. We have lots of people willing, but far fewer with ability and even fewer with any idea what we're supposed to do. Commented Jul 24, 2016 at 4:10
  • 6
    @bwoebi: "Private beta sadly wasn't able to truly expose the issues, so we have them now :-(" Nonsense. I exposed the conceptual issues with Docs.SO months ago. The lack of structure, the question of how to document things that aren't code, the unclearness with how Docs.SO is supposed to work, and so forth. Nothing was done about any of that. Commented Jul 24, 2016 at 4:23
  • 1
    @bwoebi: "the people in charge of docs...where they want to guide us" Unfortunately, that's the explicit and conscious opposite of what they are doing "what [they...] are saying" they say "wait and see".
    – jscs
    Commented Jul 24, 2016 at 4:45
  • 2
    @JoshCaswell and herein lies the core problem… they give us not enough guidance.
    – bwoebi
    Commented Jul 24, 2016 at 4:51
  • 1
    Plus an interface that's making me go cockeyed. What the f just happened in this review stackoverflow.com/documentation/proposed/changes/…
    – jscs
    Commented Jul 24, 2016 at 4:55
  • 1
    @josh You think that's confusing, proposed changes have a critical bug wherein they diff against the current revision, rather than the revision at the time that the changes were submitted. I mentioned this as an afterthought here; perhaps I need to promote it to a separate question. I doubt it'll do any good. There are so many bug reports for Docs on Meta the team is surely overwhelmed.
    – Cody Gray Mod
    Commented Jul 24, 2016 at 7:29
10

The title of the Documentation site is a misnomer:

StackOverflow Documentation

Should be read as:

ExamplesOverflow

Marketing, truth and titling are something programmers struggle with. They seem to think it's ok to lie and mislead because the naming conventions, terminology and lexicon of programming are often arbitrary and miles off of normal English use.

SO.docs was never about documentation. It's about traffic, and "engagement".

They've even stated they nearly called it "examples", which they imagined could grow as widely and wildly as Q&A did. It can't. Examples are a smaller, finite domain, and much more particular than Q&A.

But there was optimism in the hills around SF, at the offices of rules and regulations that reduce conversation and communication about the intricacies of coding and creativity on computers, and cooking.

And there's the rub. The SO.docs site is ultimately designed with the hope of porting its platform of increased engagement to all the sub-sites of StackOverflow.

Cooking examples, for example. Oil changes, Photoshop layouts, etc etc etc...

Every kind of example, under the misnomer of documentation, for all the problems of the world's programmers.

More traffic, and engagement = more fundraising for more potential advertising in the never never when it all makes cents.

6
  • I was going to suggest "Stack Overflow How-Tos", but you nailed the general point: most of the disgruntled meta contingent has ideas about what documentation should look like that are very different from what the SO devs want us to build. Commented Jul 24, 2016 at 13:47
  • 1
    As someone who has been close to this project from it's inception, I think the perceptions expressed in this answer are far from the truth. The folks who are working to build the documentation project do care about engagement, but mainly as a measure to whether or not the things they're building are making developers lives better. Sure, SO is a business and needs to make a profit to pay its employees, but I don't know anyone at SO that doesn't care about the mission of making useful tools for developers. If it were just about dollars, they could be working elsewhere.
    – Kurtis Beavers Staff
    Commented Jul 26, 2016 at 22:57
  • 1
    Is documentation perfect in it's current iteration? No. Is it simply a ploy to make more advertising dollars? No. Will it get better with time and collaboration with the SO community who also cares about making developers lives better. I believe so. There are already a ton of great ideas circulating on meta to continue to improve and shape the beta.
    – Kurtis Beavers Staff
    Commented Jul 26, 2016 at 22:59
  • @KurtisBeavers You're offering platitudes of progress about something that should have been designed better, less cynically, more considerately before release. Much of the problems were pointed out early in the beta, when it was closed. The size, disorganisation and peculiar imbalances are such that it's probably impossible to make significant and meaningful changes. And take a close look at the finances. I highly doubt SO makes a profit.
    – SKOOP
    Commented Jul 27, 2016 at 12:29
  • @SKOOP My point is simply that the current state of the beta release of the project has nothing to do with ill intentions as you infer in your post.
    – Kurtis Beavers Staff
    Commented Jul 27, 2016 at 13:10
  • What's the reason for the deceptive name?
    – SKOOP
    Commented Jul 27, 2016 at 16:14
4

My own spin on this idea: let's call it "Best practices (for broad tasks)".

As we're going to be building a guide for explaining how to solve problems, talking about various possible complication and performance bottlenecks, it would make sense to call it that, and the message would be clearer.

Sometimes solving a problem, like in cases of giant and old software solutions, means you can't afford to remake the whole thing and "make it right" from scratch, so the next best solution is to do it quick and dirty, but at the same time avoiding making common mistakes and give possible exceptions good descriptions. I suppose this is also a part of best practices in its own way.

2
  • 2
    Call me selfish, but I am not interested in pre-writing 'giant and old software solutions' (or new ones) for some theoretical future company that will not even know my name, let alone thank me for it. If they ever exist, which isn't guaranteed. Does that make me a bad person?
    – CWilson
    Commented Jul 24, 2016 at 1:05
  • 1
    This isn't about any single one of us, it's about the greater good in the software industry. The more people have an easy way to learn how to avoid the worst mistakes, the better your bank of choice's mobile app will be, and the faster your local tax service's operations will go through. Commented Jul 24, 2016 at 4:24

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