242
votes

Let's rename Documentation to Examples, as suggested by @Jeff Atwood (one of the founders of Stack Overflow) here and here.

The term "Documentation" is the root cause of many of the evils we currently see in this otherwise great project (I still really believe in the fundamental idea!):

  • An expectation of completeness, leading to people duplicating already existing official documentation

  • An expectation of a uniform editorial voice (for lack of a better word) and structure, both of which we will never be able to fulfill (and the system is not designed to deliver)

"Examples" would take the project's goals down a notch or two, but it's warranted at this stage IMO.

It can always turn into "Documentation" again once it's achieved world domination and really has taken over a great number of official documentation efforts in terms of quality, quantity, and visibility.

(I can't believe this hasn't been put in a feature request yet. Am I overlooking a duplicate?)

The "naming the Documentation feature" is not a duplicate of this. This is a request to rename the finished product, based on observations made since it launched. I bet a lot of us who thought "Documentation" was the right thing back then (including myself) no longer think so.

44
  • 25
    OK, so I like this suggestion, also the possibility to get them deleted
    – Alon Eitan
    Commented Aug 12, 2016 at 10:59
  • 134
    Yes, there must be a way to delete stuff. Examples sounds like a good name, though the most accurate name so far is collection of random crap. Or Crappypedia perhaps? Crap overflow? Crap Exchange?
    – Lundin
    Commented Aug 12, 2016 at 13:04
  • 9
    @Lundin all of that was already taken by the main site...
    – Braiam
    Commented Aug 12, 2016 at 13:06
  • 50
    @Lundin Crap overflow is awesome..:D
    – Dev
    Commented Aug 12, 2016 at 13:10
  • 24
    Examples is far more clear and conveys the point better than Documentation. Commented Aug 12, 2016 at 13:11
  • 5
    This is not a question, lobbying, blogging. Commented Aug 12, 2016 at 13:16
  • 6
    Why don't we just call it Answers? Hold on...don't we already have one of them...
    – Liam
    Commented Aug 12, 2016 at 13:31
  • 27
    @MartinSpamer I suppose you're not really familiar yet with the purpose of Meta? (for those who can't follow, that comment comes from a Close Vote)
    – user247702
    Commented Aug 12, 2016 at 13:39
  • 9
    Note that this is not a duplicate of the Naming post, because this is asking to rename the currently named section, while that other post was asking what to name the as-yet-to-be-named section. Commented Aug 12, 2016 at 14:11
  • 19
    What's with the weird off-topic close votes? @Martin et al. That one person might misunderstand the purpose of Meta, ok, but three at the same time?
    – Pekka
    Commented Aug 12, 2016 at 14:19
  • 19
    @MartinSpamer: "This is not a question, lobbying, blogging." It's a feature request. Those are allowed here. As evidenced by the fact that we have a tag for it. Commented Aug 12, 2016 at 14:39
  • 13
    @VGR: "My understanding is that the point is to provide quality documentation for things which lack decent documentation." The stated goal of a thing is irrelevant. What matters is whether the implementation achieves that. And this doesn't even come close to achieving that goal. It's a bunch of random examples, not genuine documentation for anything. Commented Aug 12, 2016 at 14:40
  • 8
    @VGR SO employees have stated that the focus is on examples: meta.stackoverflow.com/a/330003, meta.stackoverflow.com/a/329486 Commented Aug 12, 2016 at 14:40
  • 7
    And it's not like they weren't warned about this ahead of time, and not only by Jeff. For example, this answer on the initial announcement is entirely devoted to how much better a name "Examples" would be meta.stackoverflow.com/a/303981
    – Frank
    Commented Aug 12, 2016 at 15:34
  • 4
    @DavidG I think that it does matter. When I read "documentation" I visualize a tedious technical explanation about some feature, that maybe can have a useful example about it. It gives you that expectation, and as Pekka said, it also gives you the feeling of completeness. If I read "examples", then I know what I can expect
    – Lamak
    Commented Aug 12, 2016 at 16:21

5 Answers 5

32
votes

It's still not entirely clear to me what's the point of "Documentation", really.

Most of the topics covered seem to involve the most basic use cases explaining core language features, which barely differ (if at all) from the examples found at the Mozilla Developer Network, Microsoft Developer Network, CSS-Tricks, ... Personally, I don't see much added value in that.

What I would think is more useful, is teaching people about different design patterns. I'm talking about eg. BEM, OOCSS, SMACSS for a language like CSS. I'm talking about eg. the Decorator pattern, the Adapter pattern or Factory pattern for OO programming languages. Such topics are usually rejected, though, if you post them for a specific programming language. And while there is a design patterns tag in "Documentation", few will ever actually find it unless they're explicitly looking for it.

What I would think is more useful, is documentation how to write efficient algorithms. I'd love to see eg. some documentation on sorting algorithms and which cases would be suitable to use which kind of sorting algorithm. But again, such topics are typically rejected in language specific tags... and carefully hidden away at the algorithm tag.

And God forbid someone starts a topic on creating your own JavaScript games for the JavaScript tag. Creating small games is one of the most fun ways to learn programming. IMO, such a topic could be very helpful for programmers who want to create their first JavaScript games. But no, sir, that's not what the JavaScript tag is all about, so I'm told. It's all about those basic examples that really have no added value, I'm told. So which tag IS suitable for examples of basic JavaScript games? Beats me...

Personally, I do believe "Documentation" has a lot of potential, but only if it provides some added value to sources like the Mozilla Developer Network or Microsoft Developer Network. I do believe "Documentation" has a lot of potential, but only if it provides people examples that teach them stuff they don't find more easily elsewhere.

Right now, I do not believe that to be the case. And I don't think changing the name of "Documentation" to "Examples" will do anything to fix that problem.

19
  • 6
    No need to be rude about your rejected draft. Perhaps if you tried explaining why it's valuable instead of resorting to reposting and ad hominem attacks then it would have gone over better. I still stand by the idea that a topic devoted to game development in Javascript is much too broad for the current goals of Documentation.
    – Mike Cluck
    Commented Aug 12, 2016 at 18:37
  • 3
    @MikeC : I'm the one being rude now? You're the one using your dictatorial powers to highhandedly reject perfectly valid topics without inquiry just because they don't match your personal opinion of what the JavaScript tag should cover, even though you admit yourself the concept behind "Documentation" is still a work in progress that leaves much for improvement. IMO, such narrowminded moderation is precisely what prevents the JavaScript tag from actually containing information that has real value. Commented Aug 12, 2016 at 18:46
  • 7
    I disagree that it has value in that particular place. Therefore, I voted to reject it. Nothing rude about it. If you view my ability to instantly reject a change as dictatorial then perhaps giving users that ability was a bad decision. This is why Documentation is still in beta. It's that same reason why I vote in favor of what I think is best and, as best as I understand, what the community thinks is best. If this understanding changes, I will change the way that I vote.
    – Mike Cluck
    Commented Aug 12, 2016 at 18:52
  • @MikeC : If you view my ability to instantly reject a change as dictatorial then perhaps giving users that ability was a bad decision. - If rejection reasons are based on personal opinions on what qualifies as a suitable topic or example, than I don't believe that ability should be used... at least not without first consulting others in chat or on meta (to judge whether your opinion is shared by others or not). One man's very personal opinion shouldn't be the sole basis for what's suitable or not. Commented Aug 12, 2016 at 18:57
  • 2
    I agree. I also spend a relatively large amount of time in chat and reading meta. To the best of my understanding, your topic does not fit. If one was supposed to consult others for every single rejection then no user would have instant veto abilities.
    – Mike Cluck
    Commented Aug 12, 2016 at 18:59
  • 10
    "IMO, such a topic could be very helpful for programmers who want to create their first JavaScript games." I'm sure it would. But any example there would be gigantic. It would be impractically huge and unwieldy. Commented Aug 12, 2016 at 19:14
  • @MikeC : IMO, instant veto abilities could be useful to weed out plagiarized material, modifications that actually break the code of an example or other cases where rejection doesn't involve any personal opinion at all... but only for those cases. So maybe it would be a good idea to distinguish between opinion based rejections and rejections that are not opinion based? Commented Aug 12, 2016 at 19:14
  • 4
    @JohnSlegers: "So maybe it would be a good idea to distinguish between opinion based rejections and rejections that are not opinion based?" Why? Either the rejection has merit or it doesn't. Whether that objection reasoning is an opinion or non-opinion (and I have no idea how you would automatically determine such a thing) is irrelevant. If you believe that such broad topics are a good idea, but they keep getting rejected, then bring it here to Meta.SO. Make your case for keeping them. Commented Aug 12, 2016 at 19:16
  • 10
    @JohnSlegers: I meant "gigantic" in the sense that it takes up a huge amount of vertical space on the page. A single example should not take up 5+ screens worth of space. Commented Aug 12, 2016 at 19:20
  • 2
    @JohnSlegers: "So why should a single person be able to reject a topic or example based on what he / she considers suitable, when that single person may be a minority voice?" How would that be any different from someone going through the review queue now and rejecting any post that used tabs instead of spaces? Indeed, some people use their editing powers to arbitrarily change such formatting whenever they want. We might consider it bad form, but we can't stop it by mere fiat. Commented Aug 12, 2016 at 19:26
  • 2
    @NicolBolas : Questions generally need 5 votes to get closed & 5 votes to get re-opened. Edits of questions & answers by low rep users need approvals by several users (not sure how many) before they are applied. etc. While SO's traditional review system does not come without its flaws, IMO it's still a a far superior mechanism for reviewing changes than the one we have at "Documentation" right now. So why not just go with that? Why reinvent the wheel? Commented Aug 12, 2016 at 19:33
  • 1
    In Q&A, we agree with some specificity on what the appropriate grounds for closure are. Disagreements still happen, but we at least know how to hold a conversation about it. The problem with Docs review is that stuff can get rejected essentially as "not a good fit for Docs, in my opinion", since we have not pinned down what Docs is for yet. Slowing down review to a crawl is no solution. I'd say: convince people in your tag to have open minds about it, and agree that you'll similarly be open to the possibility that stuff you make proves not to be a good fit (once we agree on what that means).
    – Frank
    Commented Aug 12, 2016 at 21:14
  • 2
    Also, you can coordinate in chat, you know. Ask people what they think of a draft; get one of them to accept it; and so on. With 4-5 votes for review, I'd certainly never go near editing Docs.
    – Frank
    Commented Aug 12, 2016 at 21:15
  • 3
    ^ This is why I've been suggesting you join us in chat. A number of controversial topics and examples have been sorted out there. That conversation is how we're deciding what fits in Docs. Make your case and if enough people agree, that's the direction it will go.
    – Mike Cluck
    Commented Aug 12, 2016 at 21:58
  • 6
    John, you've had a tendency to post suggestions to Docs that are way too broad and ancillary to the topic at hand. Tags like BEM and SMACSS and OOCSS are their own tags on this site. Make a tag proposal for them and when 4 other users commit to it, contribute to it to your hearts content. I strongly recommend reading over the various staff posts on what Documentation is for before suggesting more overly broad/inappropriate topics.
    – TylerH
    Commented Aug 13, 2016 at 4:23
26
votes

I think the name of the project should follow directly from the goal that it has. So first of all, one has to be clear what the goal is of Documentation. Then naming it will be relatively easier.

"Examples" as title seems to have more constrained scope than "Documentation". Documentation can include examples, while vice versa, isn't true.

5
  • 21
    This is exactly it...because the focus is on examples, the ui is focused on examples, and because all the notes and info focus on examples it is what it is...people are focusing on examples and its natural for them to want to call it examples (holy long sentence). +1.
    – JonH
    Commented Aug 12, 2016 at 17:20
  • 1
    @JonH I read other comment of yours on the answer below, I think we have similar opinions on this matter. Commented Aug 12, 2016 at 17:29
  • 2
    If the site is renamed to Examples, wouldn't it make sense to just remove the topic headings that say "Examples"? It's unclear to me how Syntax and Parameters are necessary sections when Examples already handles those things (theoretically). I agree with you. "Examples" as a name is too constrained. Commented Aug 12, 2016 at 17:36
  • 2
    @JonH Besides I am not sure if being too focused on examples is good or not, I mean does it encourage "give me the codez" kind of thing? is there a point in having example if you don't understand what it does? Ok sometimes it may "save" you if you need something - and grab code snippet. But is it good to encourage this kind of thing? Commented Aug 12, 2016 at 17:41
  • 2
    I agree being focused on examples is bad, but all the tools that the devs have built focus on examples and missing examples is the gap in official documentation that SO Docs is supposed to fill. Docs content is bad right now because everyone's trying to use it for what it wasn't designed or intended for, and we could solve that problem by giving it an appropriate name. Commented Aug 12, 2016 at 19:33
11
votes

As stated in this answer about what the purpose of the "Documentation" site is:

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.

The idea is to complement and enhance such official documentation.

This is definitely useful, but definitely not full documentation. I don't like "Examples" as a name (though I like it better than "Documentation"), but it seems like the sorts of things we want to build already have other well-established names in programming/technology communities:

  • Recipes
  • How-tos
  • Guides
  • Samples
  • Tutorials, or Walkthroughs (iffy, not sure we'd want to sequentialize a topic)

I'm not clever with names, but maybe something snappy can be built from these familiar terms.

4
  • 3
    To be clear on motivation, I worry that the "documentation" name spreads the message that all we really want for documentation as programmers is sample code. I never want to work in a world where people stop writing complete API references or user guides and focus only on samples or video tutorials.
    – Jacob
    Commented Aug 13, 2016 at 0:57
  • 1
    I (and others) have suggested Cookbook a couple of times, but that carries a negative connotation for many people. I will note that the official Jsoup "example-focused documentation" calls itself the Jsoup Cookbook, for one. Commented Aug 13, 2016 at 2:36
  • I like "How-tos", I think it conveys the meaning well. Commented Aug 13, 2016 at 13:03
  • 1
    @Jacob I worry that the "documentation" name spreads the message that all we really want […] is sample code. I never want to work in a world where people stop writing complete API references or user guides and focus only on samples or video tutorials. +1million. Samples can be useful as ice-breaker, but they don't take me very far. API reference is essential. And that's official examples; I don't much care what random internet users think is illustrative. Videos? Any time I search for a guide and the page tries to load a video, that's it, closed. We write and read code; we don't watch it Commented Aug 15, 2016 at 9:24
8
votes

I think about this and it boils a lot to a parallel of sorts. Yes, we're very focused on examples, because that's the stuff we want prominent in the documentation. But as important as examples are, they're not really the umbrella it all falls under.

Think about the main portion of the site. What do people come here to get? Answers. But we're not called an Answers site, we're called a Q&A site. Because in order to have answers, you need questions in the first place. And in order to search for answers, you need to have a question that you're looking for in the first place. Which is why you search for a relevant question. Having the question is the important starting point for your journey.

Here, the ideal goal is that people find functional, strong examples in order to help build knowledge on a subject. But you don't look just in a giant pile of examples. You look at a list of topics, and find examples underneath them. Topics are the Questions to which Examples are the Answers, basically. Just in this case we want things more barebones and direct on the topic - it amounts to basically just a title at this point because rather than having an explicit problem you're trying to solve (which warrants a question body), it just covers a specific thing that you're trying to find examples of.

There's also the matter of hierarchy. Examples, they might be topmost in a given space, but they're actually two levels down. You gotta first drill past Tags (defining the discipline under which you're finding stuff), and from there, drill past Topics (defining what portion of the discipline you're looking for stuff under) before you even make it to Examples (defining how you do that thing you're looking for stuff on). One could say it's organizational frou-frou but the thing is that in this construction that organizational frou-frou is crux, it's important. This isn't "A place you can find a bunch of examples that are categorized by discipline and subtopics", this is "A place you can find topics within a discipline, and then find examples of those topics because that's what we intended as the most important aspect of them." There's an intended order you're supposed to go about here.

So while we have an enormous focus on examples as an item here, using "examples" as the overarching title on which the entire section is called feels very misleading. It's misunderstanding why we have a focus on examples at all, really. If we wanted to parallel Q&A fully you could say 'Topics & Examples' but T&E is just not very illustrative or cognitively immediate, really. Documentation may be a thing that people have preconceived notions of how it must be written, but when we're looking at a resource that describes a bunch of topics within a discipline you look at in order to find information, it's accurate enough. Maybe there's a better word out there (or phrase, if it must be) but I'm not going to find "Examples" to be that word - Examples are just the delivery mechanism.

17
  • 3
    This is close to my response in that examples is a bad name overall. But you hit the nail on the head with this: "It's misunderstanding why we have a focus on examples at all, really." - If that is the case the tour and the blog posts shouldn't focus on it so much. Also you did mention you go into an organization / hierarchy to even get to the examples - but I tell you the feel of it isn't really there. The UI does not make me feel that...it makes me feel that examples are very important and everything else is nice to have. Which is misleading to say the least.
    – JonH
    Commented Aug 12, 2016 at 18:09
  • 2
    @JonH That's something we're working on fixing - Kurtis is focusing on the UI to make the importance of topics a lot more relevant, among other things. The process should be able to downplay examples as being the end-all-be-all without sacrificing our intent that they're front-center portions.
    – Grace Note StaffMod
    Commented Aug 12, 2016 at 18:10
  • 1
    that sounds good...maybe and I mean maybe this will get better soon. If you guys address these concerns I would say topics such as name changes will vanish - it's a waste of time and too much into the beta to still be discussing a name. The name is Documentation - we just need to match the functionality to the name.
    – JonH
    Commented Aug 12, 2016 at 18:12
  • 5
    @GraceNote: Is there any focus on actually defining what a "topic" means? Why you would put an example in one topic vs. another? Or what is topic-worthy and what is not? What it means for one example to be voted higher than an example that explains some other aspect of a topic? You can make the UI more topic focused all you like, but the concept remains il-defined. Commented Aug 12, 2016 at 18:14
  • 2
    @NicolBolas That's part of what we're trying to address - it's a bit of an unsolved problem at the moment but it's one that's sort of actively experimental. In essence we're still grepping the shape of topics to see "What works" and "What doesn't work" in order to help create that focus that you're asking for. Because indeed - there isn't a solid, useful definition for a topic. But that being the central portion to start from is still key in the design.
    – Grace Note StaffMod
    Commented Aug 12, 2016 at 18:17
  • 14
    @GraceNote: I guess I just don't get the point of going through all the effort to build a site based around a concept that you admit you don't even know what it is. Yes, Q&A was refined somewhat over the course of SO's many years. But we always had questions at the top, answers at the bottom, votes on answers mean the answer is better, etc. We added comments when that was proven necessary, various editing and moderation queues, etc, but there were no major changes to the overall meaning of concepts. I don't see that level of maturity coming from the design of Docs.SO. Commented Aug 12, 2016 at 18:26
  • @Nicol A friend and I had a discussion about Docs with regards to the good ol' "Hidden Features of Java" type questions. When you have a congregation of experts such as our audience, we want to share our knowledge - but the inherent limit of Q&A is that you need a question to be asked in order to provide an answer, whereas there's a lot of information out there that people wouldn't know to even ask about at first. Hidden Features gave a place to tuck and stuff random tidbits that people wouldn't have known about otherwise, but it was bundled under essentially randomness [...]
    – Grace Note StaffMod
    Commented Aug 12, 2016 at 18:37
  • Documentation actually gives such a place for the answers to questions people didn't know to ask. But what makes it powerful to that tool is that you actually have the notion of the correct place to file that information under. So that if there's, say, an extremely useful tip regarding how to, say, sort arrays, the best place to find that is when you're looking up how to sort arrays rather than an open appendix. That sectioning there, that's what topics represent. The biggest missing piece is scope - does that file under "arrays" or "sorting arrays"? That's the part that eludes us.
    – Grace Note StaffMod
    Commented Aug 12, 2016 at 18:39
  • @GraceNote - It's almost as if you need to tag the topic...wow this could be difficult. Good luck.
    – JonH
    Commented Aug 12, 2016 at 18:44
  • 5
    @GraceNote: "The biggest missing piece is scope - does that file under "arrays" or "sorting arrays"? That's the part that eludes us." That's a trivial problem Wikipedia fixed years ago: let information go where it needs to. If it would go under one category or the other, then it goes under both. If it needs to be under 12 places, then it goes under 12 places. Commented Aug 12, 2016 at 19:10
  • 10
    @GraceNote: "Hidden Features gave a place to tuck and stuff random tidbits that people wouldn't have known about otherwise, but it was bundled under essentially randomness" And how is Docs.SO any different? Oh sure, you might file it under "arrays" or something, but it's still bundled under randomness. If you're looking for a trick that will help you actually accomplish a particular thing, Docs.SO won't necessarily help you. If you just want to browse random tricks, it might be useful. Maybe. But even then, that's still Examples.SO, not genuine Documentation. Commented Aug 12, 2016 at 19:12
  • 4
    "the best place to find that is when you're looking up how to sort arrays rather than an open appendix" -- I thought it doesn't matter where things go because Google will figure it out anyway (scroll to "What about hierarchies")? The current UI makes navigating very difficult, apparently because people aren't expected to use it. Commented Aug 12, 2016 at 19:29
  • 3
    The good ol' "Hidden Features of Java" wasn't useful because it was just a big ol' random mismash of irrelevant information. I don't see how that will be useful if it's imported to Documentation, either. Are you saying that you envision things like that actually being added to Documentation? Because (1) I don't see that happening, and (2) I see a lot of friction (both from the UI and from what I understand the official line being from the team) against it. I don't think that was good content for Q&A, and I don't think it's good content for Docs. The problem wasn't simply "where does it go"?
    – Cody Gray Mod
    Commented Aug 13, 2016 at 11:50
  • 3
    Furthermore, this problem of "the inherent limit of Q&A is that you need a question to be asked in order to provide an answer." Sure, that's a limit, but it's actually a good limit, because having to ask a question about it serves to provide scope. That's what Documentation is lacking right now, is any kind of reasonable scope. Dumping "everything about the C++ language" into C++ documentation isn't a scope, and the "topics" are so ill-defined as to be meaningless. Furthermore, how is this "limitation" a real problem? We solved it a long time ago by promoting self-answering. If you have...
    – Cody Gray Mod
    Commented Aug 13, 2016 at 11:51
  • 4
    ...useful knowledge you want to share about a particular topic, then you formulate a question about it and post an answer. This works really well in practice. If I have a useful tip to share about sorting an array, then I ask a question that demonstrates the situation in which that tip would be useful, and then I post an answer explaining the tip and demonstrating how to use it (sample code). Which is...exactly how it seems Docs was conceived to work. Which raises the question, again, of what problem it's actually solving. Scope isn't an issue with Q&A because it's language-specific.
    – Cody Gray Mod
    Commented Aug 13, 2016 at 11:54
6
votes

Examples is a great name for this. After it was first suggested (back in September of last year), Kevin passed around an RFC internally proposing the name change and listing out all the advantages of Examples as a name for what we were setting out to build. There were quite a few advantages. And quite a bit of support - internally as well as here on meta - for changing the name...

...But there was - and I'll wager still is - one crippling disadvantage to calling this "Examples": to an awful lot of people, a site for Examples is a snippet site.

what Examples means to a lot of folks...

You know the kind of site I mean. The ones that exist for the sole purpose of letting people send teh codez. They've been incredibly popular in the past, and still are in some areas (although micro-libraries and services like GitHub or the various package hosting services have been chipping away at them).

Now, there's nothing wrong with a site dedicated to providing pre-written bits of functionality for various needs - heck, there's a tremendous amount of that on Stack Overflow Q&A already! But... Therein lies the problem: we don't need another service for this; to the extent that folks on Stack Overflow want to write or find snippets, Q&A works just fine. And when it doesn't, myriad sites already exist to fulfill the role. If I'm looking for a leg up implementing some set routines, Stack Overflow probably has that; if I want a library of set routines, I'll go to GitHub.

The overarching goal of this project is to find a way to improve documentation. The specific approach here is to focus on writing examples that document things, but not to encourage the creation of more explanation-free code dumps. Picking a name that's more acceptable to folks who already know what this is about at the cost of driving in legions of people who will immediately assume it's about something else is a very costly mistake to make, especially at the outset.

Bikeshedding

To date, Documentation has been a "not very good but not very bad" choice for a name here. Other suggestions - including Examples - have been some combination of more descriptive and more misleading. Experience has taught us that this is an extremely dangerous combination... The site for Programmers has been struggling for years with the misconceptions caused by their name, which is a perfectly accurate description of their topic and yet implies something completely wrong to a majority of visitors.

I'd have to say that, while we're probably still open to changing the name here if an absolutely brilliant choice emerges, we're not particularly optimistic that this will happen... And have probably wasted too much time discussing it already. Naming is hard, and the payoffs of swapping one problematic choice for another are non-existent. Meanwhile, there are tons of bugs that need fixing...

45
  • 19
    You guys messed up when you put too much attention and focus into examples that is the #1 issue. Even in the tour you guys stress it a lot. Don't get me wrong, I want to keep the name "Documentation" and I despise the name "Examples" based on your feedback above. But what you guys are doing is truly building examples under the rooftop of Documentation and that is what is wrong. Examples should really be SECOND hand not FIRST hand in all of this. When I see the word documentation I expect there to be examples, but at the bottom not right away. I expect to understand what a function/api...
    – JonH
    Commented Aug 12, 2016 at 16:48
  • 5
    Example-driven documentation is the goal here, @JonH. So putting focus on writing examples is appropriate... As long as the goal remains documenting stuff using examples and not "writing examples for the heck of it".
    – Shog9
    Commented Aug 12, 2016 at 16:49
  • 7
    Does in the BEGINNING, what method's it has, what parameters are passed to it..and finally the examples. When I tell someone to read Documentation I expect them to read the workings of how a class / function / whatever have you works...not get th3 cod3z. Instead you guys focused on getting the cod3z and you're having this back and forth talk between users about changing the name. No this should not be the case...we should first never even think about calling it Examples because we should be building documentation. But what you guys have put forth and talked about is otherwise NOT the case.
    – JonH
    Commented Aug 12, 2016 at 16:50
  • 6
    Example driven documentation - is that a new buzzword? You don't tell people to read example driven documentation - you tell them to read the docs...anything else is bs.
    – JonH
    Commented Aug 12, 2016 at 16:53
  • 6
    I know that the number of people who have come to stack overflow and clicked on the documentation link expecting to get... well, something completely different is a number that is greater than 0. Examples, if misleading, seems to at least be misleading in a better direction. Commented Aug 12, 2016 at 17:01
  • 7
    @Shog9 - So you fix it by keeping the name Documentation and cut all the "EXAMPLES ARE VERY IMPORTANT" part because then people won't be so focused and tied to this notion. For pete's sake we have people on meta requesting a name change to something that is pretty logical - documentation - why would anyone want to change it to something like examples (yuck). They are doing that because its engraved in their mind through your guys' blog posts, tour, and who knows what else that "EXAMPLES ARE VERY IMPORTANT".
    – JonH
    Commented Aug 12, 2016 at 17:10
  • 5
    I give up (again)...Documentation is the same experience with Jobs - this is not community driven anymore.
    – JonH
    Commented Aug 12, 2016 at 17:11
  • 5
    @Shog9 I'm not clear on the difference between "plz send teh codez" and what SOD seems to be already. Aside from rewarding blatant plagiarism, or people getting [exceedingly confused]( stackoverflow.com/documentation/proposed/changes/80546). I've read a few posts that indicated the goal of examples/SOD was to have nearly copy-pastable code. Is that not the case? Commented Aug 12, 2016 at 17:22
  • 12
    "As long as the goal remains documenting stuff using examples and not "writing examples for the heck of it"." Here's the problem. Everything about the current site design leads to "writing examples for the heck of it." From the way edits are reviewed, to the reputation model, to voting for examples, to the fact that all non-example content is at the bottom of a topic, to the nebulous definition of "topic". So, either the site design is completely incapable of achieving the goals of writing documentation by example, or the goals need to be changed to fit the design. Which is it? Commented Aug 12, 2016 at 17:54
  • 11
    @Shog9: I think you're sort of missing the point. You want to have example-focused documentation, where you make people write code and explanations. Well, there's a word for that already: it's called a "tutorial". If you call it "documentation", people will expect something that's actual documentation, either reference or manual docs. If you call it "examples", people will expect something that's just copy-and-paste examples. If you want code+explanations, that's "tutorials". Commented Aug 12, 2016 at 18:31
  • 4
    Funny enough, the internal name for this was "Docu-toots". Perhaps we should've stuck with that...
    – Shog9
    Commented Aug 12, 2016 at 18:43
  • 15
    I agree with this, and naming is absolutely hard, but there is quite a bit of evidence that the name "Documentation" is causing active harm. That's a deal breaker for me. So maybe not "Examples", then, but some other name that causes less active harm? Commented Aug 12, 2016 at 20:36
  • 5
    I haven't read all the comments here, so this may've been mentioned, but reading your answer honestly confuses the living daylights out of me. As I've been working really hard to understand how Documentation is supposed to work, and communicating with other team members about it, I've been presented with a very strong and clear message that the purpose of it is essentially to provide a collection of examples that help get people started with using a language/API/feature. In contrast to assembling comprehensive documentation. This jives well with the entire UI, but conflicts with your answer.
    – Cody Gray Mod
    Commented Aug 13, 2016 at 11:57
  • 11
    This answer gives the impression that "Documentation" was chosen over "Examples" because marketing was more important than clarity, and now you're surprised that a bunch of programmers are confused because of your misleading variable name. This whole project belongs in a Dilbert story arc. Commented Aug 14, 2016 at 2:31
  • 4
    I think this post sums up the Documentation project nicely. People are desperately grasping for a use for this new XY feature, hoping to find a purpose for Documentation now that it is live. It can't be a code example site because then it is Github (but less practical). It can't be a Documentation site because then it is Wikipedia (but with far worse quality). The complete lack of rules or quality concerns for what or how to post says it all - it's a place that nobody knows what it's for - dump random stuff here.
    – Lundin
    Commented Aug 15, 2016 at 6:31

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