291

I don't see how this analogy helps the user to understand what differentiates the Q&A from the documentation. I don't even get the analogy (maybe a cultural thing).

SO is not a place for this type of analogy, especially in a feature (documentation) that has been struggling to be understood.

I propose that this is removed from the tour. We can leave a blank space for now.

53
  • 7
    The idea is that they are two different things that go good together. (Lots of people like chocolate and peanut butter together. Think of Reese's and many other candies that combine them.) But you're right, the only thing harder than writing good software is coming up with good analogies! Jul 27, 2016 at 11:21
  • 222
    Lots of American people. Outside America, peanut butter is not such a big thing. Jul 27, 2016 at 11:23
  • 19
    I understand it is quite popular in the Netherlands, as well. Of course, they call it "peanut cheese", since it doesn't actually have butter in it. (Nor does it have cheese in it, but naming is yet another hard problem!) Jul 27, 2016 at 11:28
  • 31
    It's funny: I found the analogy very fitting, because I took it to mean: "If Q&A is good, Documentation is half-hearted". (Probably the peanut butter I have tried is not as good as it is supposed to be.)
    – mat
    Jul 27, 2016 at 11:28
  • 279
    "If you are allergic to Documentation, you can probably still eat Q&A."
    – Sumurai8
    Jul 27, 2016 at 11:35
  • 12
    Maybe marmite would be a better analogy, at least in the UK. Jul 27, 2016 at 11:39
  • 8
    @CodyGray even if your interpretation is true, in what sense are documentation and Q&A supposed to be combined with each other? What, concretely, does that mean? It seems like meaningless fluff to me.
    – Mark Amery
    Jul 27, 2016 at 11:40
  • 14
    @Mark I am not the right person to ask that question. I have no idea how Documentation is supposed to work. But this is not a failing of the analogy, it is a failing of vision. Or at the very least, an inability to articulate that vision. There is no doubt that my interpretation is correct, however. They are trying to make the point that, while they are two seemingly different and unrelated features, they complement each other nicely. Most of the Documentation Tour is "meaningless fluff"; I've made this point before. Jul 27, 2016 at 11:53
  • 7
    I'd say two peas in a pod is more appropriate. The peas may not like each other - but they're stuck in the same pod and have to live with it. Jul 27, 2016 at 12:26
  • 25
    @Omar Now you're confusing Canada's national tree with a British fictional crime solver.
    – Mr Lister
    Jul 27, 2016 at 12:28
  • 6
    'In the 1970s and 1980s, a series of commercials were run for Reese's Peanut Butter Cups featuring situations in which two people, one eating peanut butter and one eating chocolate, collided. One person would exclaim, "You got your peanut butter on my chocolate!" and the other would exclaim, "You got your chocolate in my peanut butter!". They would then sample the mixture and remark on the great taste, tying in with the slogan "Two great tastes that taste great together."' -- en.wikipedia.org/wiki/…
    – Randy Levy
    Jul 27, 2016 at 12:38
  • 62
    Well, Q&A is not chocolate. I know chocolate. I run on chocolate. Chocolate is a friend of mine. And Q&A, folks, is no chocolate. Jul 27, 2016 at 12:47
  • 22
    @RandyLevy so this is a reference to an ad that was aired in the 70's and 80's in the USA. It would flag it as too localized.
    – A.L
    Jul 27, 2016 at 13:35
  • 7
    @Vince That just makes it an even better analogy! To many new visitors, Stack Overflow is unusable. And to many veteran users, Documentation is an allergen. On a broader note, the culture clash here is extremely interesting. This is literally an analogy that 99.99% of Americans would immediately understand. It is not an obscure reference to a 70s/80s TV advertisement. It is a reference to a significant feature of the culture: eating candy and junk food. Hey, why does the US top those world obesity rankings, again? Jul 27, 2016 at 14:00
  • 6
    I assure you, @VinceO'Sullivan, the "American chocolate" that you've probably tried is inedible to a lot of Americans too.
    – jscs
    Jul 27, 2016 at 16:41

3 Answers 3

66

I think the core issue is that the Tour acts more like a marketing landing page than an actual "introduction" (by that, I mean teaches people how to use it, not just to draw them in). I'm rather aloof of the Web 2.0 approach of a high widget to content ratio, that is less content. I'm not going to spend half an hour of my time studying a pamphlet when a plain page with bulleted points would do.

So far as I'm aware, the core audience of Documentation so far are the beta testers, who are active contributors that are well acquainted with using SO, judging from the fair amount of activity on meta. Extending that, the consensus is that the desired contributor demographic are knowledgeable users with quality contributions that don't care for rep. So, the marketing speak just comes off as patronizing.

While my post seems to be hijacking the topic at hand, I think trying to come up with a better analogy (or cute phrase) is missing the point. It's a bikeshed problem and an American based company is probably not going to be able to come up with something that appeals to all demographics. It's a waste of time that should better be spent writing Documentation on Documentation.

TL;DR: More content, less market speak.

4

After reading a few of the brilliant counter-analogies in the question's comments, I summed most of it up and here's what a good analogy should or could be:

  • globalized without promoting local products or lifestyles;
  • lead people to conclude that Documentation can be as good as Q&A;
  • suggest that Q&A and Documentation when used together become an even better resource.

And should not:

  • have any references to allergens, since some may associate them to their or others health conditions;
  • promote habits that may induce unhealthy lifestyles;
  • attempt to reuse popular marketing campaigns (since they had their own purpose and can be "too localized");
  • lead people in thinking that Documentation should be used instead of Q&A and vice-versa;
  • contain subliminal messages.

However, if the Tour is to be transformed in order to be devoid of marketing purposes, as "uh oh somebody needs a pupper" suggested, hard/statistical data may be used in order to show how Q&A and Documentation complement eachother. For example:

  • a list of questions which are covered by a list of examples in the documentation of certain feature or technology could help answering the question or answer it directly;

  • how to link a question or answer to certain parts of documentation in a simple and fast way, and vice-versa

    (this may be another question/feature by itself - a search box near the form's textarea that lists the results of the other site, or when typing on the textarea or the title bar the text would be scanned and list documentation examples on the sidebar).

  • details on how the review, voting and reputation system works differently from Q&A.

Feel free to add or modify the lists according to common sense.

-5

Eh... I don't care for the analogy either. It's familiar, but it doesn't actually convey much of value. You could just as well say, "Documentation is intended to augment Q&A" and convey the same information (or lack thereof) without the cultural reference.

...But I also don't care to change it at this point. Vague, aspirational language is appropriate for this stage; as we continue to build and learn, more concrete descriptions of things like the relationship between docs and q&a will emerge.

Think of it like touring a newly-built house: you can see where the structure was built to allow for various furnishings, and perhaps there are even a few placeholders (cheap lights, rental furniture) dropped in to help give you an idea of what it might look like with your stuff in it... But most of that is necessarily left to your imagination. "Large fenced yard" becomes "...a place for a rose garden" for one viewer, and "bocci ball!" to another; "unfinished basement" might translate to "spare bedroom", "workshop" or "guilt-free storage!" Only when the house has been lived in does the tour change from "imagine the possibilities" to "evaluate the reality".

Right now, folks are still very much moving in...

3
  • 9
    I'm afraid I don't agree with this analogy. Sure, creating a fancy pamphlet is pretty quick to do nowadays, but is it really that much faster than a scratch guide? Even just taking the information from the annoying blue circles (that was complaining about on another post) and putting it on a single page with a page with no markup or CSS would be an improvement. Jul 29, 2016 at 3:44
  • 5
    From what I've seen ( and it's not a lot ) the following analogy would be closer: you are touring a construction site, where some structures are partially assembled, while other materials are barely unpacked. Then your tour guide says: "Now, let's all together build something. We have tentative blueprints, but we will not share them. You are professionals, so you are better equipped to decide what the final structure should be. You will be doing everything at the same time without much supervision, but at the end it all come together."
    – PM 77-1
    Jul 29, 2016 at 14:12
  • 5
    I love that the explanation for the analogy was explained with another analogy. Analogy-ception. Illuminati confirmed Jul 29, 2016 at 14:55

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