Skip to main content
49 events
when toggle format what by license comment
Jun 3, 2020 at 15:29 history edited CommunityBot
Commonmark migration
Mar 17, 2017 at 8:26 history edited CommunityBot
replaced http://meta.programmers.stackexchange.com/ with https://softwareengineering.meta.stackexchange.com/
Aug 15, 2016 at 19:49 comment added Shog9 Sorry for the confusion, @CodyGray - your impression is exactly correct. The critical part of that is that the purpose of examples is, as you succinctly state, to "help get people started with using a language/API/feature". Which is much less broad than "any bit of useful code someone has ever written" and much different in its aim from "let folks ask for bits of code that do something specific" - although the system certainly could be used for either, those were never the reason for its design or construction and probably aren't something we'd want to encourage.
Aug 15, 2016 at 6:31 comment added Lundin 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.
Aug 14, 2016 at 19:15 comment added user128511 How about "Documented Examples" then 😇
Aug 14, 2016 at 2:31 comment added TigerhawkT3 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.
Aug 13, 2016 at 16:47 comment added Bill Woodger "SOooo Documentation..."
Aug 13, 2016 at 11:57 comment added Cody Gray Mod 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.
Aug 13, 2016 at 0:10 comment added JonH @JeffAtwood it wouldnt cause any harm if we stuck to the definition of documentation and stopped the focus of examples. If we do that its the perfect word to use.
Aug 12, 2016 at 20:45 comment added Jeremy Banks Null Reference has vague enough connotations that it could be applied to whatever Documentation is or becomes. ;) (I appreciate why this might not really work branding-wise, but... I do like it.)
Aug 12, 2016 at 20:36 comment added Jeff Atwood 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?
Aug 12, 2016 at 18:47 comment added JonH Docu-toots - that sounds horrible...our firewall would block it for some reason. I'm glad you didn't stick with it and what Nicol Bolas mentioned above your comment is exactly my point. The focus is on examples hence the reason this meta question came up by Pekka. And he's right the word for what you are after is tutorials...if you want to make this documentation you need to match the definition of documentation...and I'm sure that word has some reference to reference or manual in it. Please consider my suggestion at least so I can have a nice weekend?
Aug 12, 2016 at 18:43 comment added Shog9 Funny enough, the internal name for this was "Docu-toots". Perhaps we should've stuck with that...
Aug 12, 2016 at 18:31 comment added Nicol Bolas @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".
Aug 12, 2016 at 18:05 comment added Shog9 The former, @Nicol. In particular, it is waaay too easy to earn rep by writing useless examples right now. Kevin's working on a fix for that. Kurtis is working on UI changes to make topics more usable.
Aug 12, 2016 at 17:59 comment added JonH @NicolBolas - Let me guide the ship - 1)Keep the name documentation. 2)Stop focusing so much on examples (they are complimentary, sometimes they are there other times its okay if they aren't). 3)Change the UI such that documentation is actually that...it should start with the remarks section or a new summary section defining the actual documentation. 4)Move the examples to the bottom...end result. We really have documentation and no one can raise the question about changing the name because we no longer have the focus of examples.
Aug 12, 2016 at 17:54 comment added Nicol Bolas "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?
Aug 12, 2016 at 17:41 comment added Shog9 ...And if it's white then it's cooler in the summer, and if it's black then it's warmer in the winter... Yeah, every color has some advantage or disadvantage, @Frank. But mostly, we just need a roof over the bikes.
Aug 12, 2016 at 17:39 comment added Frank @Shog Yeah, the analogy isn't perfect, but to extend it further ... If a bike shed is green it doesn't make you wonder "Is this really for bikes or is it for cars or perhaps horses?" I think this is all a symptom of the lack of clarity on what the site is for. In my opinion, "Documentation" is responsible for a lot of the confusion.
Aug 12, 2016 at 17:38 comment added Shog9 If we end up with examples demonstrating how to use a menu API to include icons, that's great @Thriggle - and probably will help reduce dups. But we don't need to encourage, for example, topics that consist of nothing but hundreds of menu implementations without actually demonstrating the use of anything.
Aug 12, 2016 at 17:35 comment added JonH Frank my quote was rightfully written because the focus was on examples - here is the difference.
Aug 12, 2016 at 17:35 comment added Frank @JonH Sorry, I'm not sure what you mean about conspiracy bs. We can take it to chat if there's some misunderstanding chat.stackoverflow.com/rooms/117558/documentation-public-beta
Aug 12, 2016 at 17:34 comment added Shog9 The problem with the bikeshed wasn't that it could be painted any color; it was that the color didn't really matter very much but everyone has an opinion anyway, @Frank. If this particular shed was green instead of yellow, we'd be having this exact same discussion...
Aug 12, 2016 at 17:34 comment added JonH @Frank - Right please understand I said that quote above because THAT IS WHAT THEY FOCUSED ON...stop the conspiracy bs. If you focus on examples such as cookbook examples it should be called examples - but what I am proposing is to stop focusing on examples and look at the big picture of documentation as a whole.
Aug 12, 2016 at 17:33 comment added Frank @JonH And also to quote you: "Then they shouldn't of called it documentation - it should of been called cookbook or examples." meta.stackoverflow.com/questions/329478/…
Aug 12, 2016 at 17:32 comment added Frank Sure, @JonH, but another perspective is: we're getting exactly the site that we expected based on what they have been saying all along, while you are commenting entirely because they chose the wrong name. Calling it Docs led you to believe they were building something entirely different. And calling it Docs is why some folks want to fill it with the paint-by-numbers stuff Shog says he wants to avoid; and why others think it's a great place for tutorials; and so on. "Documentation", like the famous bike shed, is far too open to different interpretations; that's why we have this question.
Aug 12, 2016 at 17:30 comment added SierraOscar Can we have another poll or something to look at potential names? I realise we had one previously, but this was before docs was actually released and no-one really understood the purpose. Now that it's in the wild we could get some very good ideas for a better name.
Aug 12, 2016 at 17:30 comment added Thriggle One of the benefits I perceived to SOD was that having a repository of "canonical" community-edited examples might reduce the flood of case-specific "plz send teh codez" questions on Stack Overflow. Teach a man to fish and all... If renaming "Documentation" to "Examples" drives such questioners to look at the existing body of "how to do x" example snippets before asking questions on Stack Overflow, that seems like a good thing to me...?
Aug 12, 2016 at 17:29 comment added Alon Eitan So what exactly is the difference between Documentation/Tutorials/Guides/Examples in the context of the Documentation area? What is the best word that can unify and describe the content there (and that will also give a clear guideline when one should decide if to reject or approve a suggested edit)?
Aug 12, 2016 at 17:22 comment added Wayne Werner @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?
Aug 12, 2016 at 17:17 comment added JonH @Frank - Hence this question on meta right? You are getting questions by OTHERS not me about the validity of the name...changing docs to examples is coming up why? Because people have read the quote you quoted and focused on garbage examples.
Aug 12, 2016 at 17:16 comment added Frank @JonH Apart from the name, I don't know what led you to think it wasn't essentially example-driven documentation. The announcement said things like "We're putting [Examples] at the top of the page because we believe they're the most important - the information you desire is likely within them." And the fact that SO didn't cave to your demand to put Examples lower down on the page (or whatever you're asking for) doesn't mean it isn't community-driven... There are others in the community, too.
Aug 12, 2016 at 17:15 comment added JonH @Shog9 - this isn't and shouldn't be about a name change. That is out of the question - Kevin Montrose got it right when he said we'd call it "Documentation" what I am "pushing" for is the end to the focus of examples - that is what got you in this mess.
Aug 12, 2016 at 17:14 comment added Shog9 Community-driven is using the thing such that it pushes it in the direction you want to see, writing up your findings here on meta for others to learn from, @JonH. That's how we all pushed Q&A to where it is today. Community-driven naming is a non-starter; everyone has an opinion on the bikeshed color, we'd be changing the name every week.
Aug 12, 2016 at 17:11 comment added JonH I give up (again)...Documentation is the same experience with Jobs - this is not community driven anymore.
Aug 12, 2016 at 17:10 comment added Shog9 That said, I think we'd all be quick to admit this is a gamble, a leap of faith: you can fill in that boilerplate and still call it documentation and folks will let you get away with it even if it's crap, but if you write a dozen examples and then don't fill in the boilerplate, then... Even if those examples cover every use-case and explain every parameter... Is that really documentation?
Aug 12, 2016 at 17:10 comment added JonH @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".
Aug 12, 2016 at 17:05 comment added Shog9 So, here's the problem, @Wayne: you call it Documentation, a tremendous number of people won't read it unless it pops up in search. You call it Examples, and a tremendous number of people will read, "plz send teh codez" and behave accordingly. Both are problematic, but I'd argue the latter is a much harder problem to solve.
Aug 12, 2016 at 17:03 comment added Shog9 I've used MSDN docs since they came in a binder full of CDs, @JonH. There's a lot of useful info in them, but... Good examples have had a tendency to lag behind the boilerplate by several years, and getting things like parameter docs that reflect those examples is extremely hit and miss. MSDN is good for what it does, but there's a lot that it doesn't do.
Aug 12, 2016 at 17:01 comment added Wayne Werner 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.
Aug 12, 2016 at 17:01 comment added JonH @Shog9 - That is fine and you follow that up with examples - or in your case - example driven documentation (whatever that means). The point here is yes you still get the boring stuff about what the method does but immediately after that examples...I dunno like successful sites like MSDN does?
Aug 12, 2016 at 16:59 comment added Xiong Chiamiov If the goal was example-driven documentation instead of an examples snippet site, then perhaps that's what should have been created!
Aug 12, 2016 at 16:58 comment added Shog9 The problem is, that stuff is trivial to auto-generate in most popular languages @JonH - IOW, I don't need documentation to give me a list of methods and parameters for C++ / Java / C#; I need some explanation of what the method is actually for and how those parameters should be used... Things that have traditionally been done poorly, because writing examples was an after-thought. So we get paint-by-numbers documentation, full of things like, "hModule is the handle of the module to search" without any information on which modules I should be searching or when.
Aug 12, 2016 at 16:53 comment added JonH 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.
Aug 12, 2016 at 16:50 comment added JonH 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.
Aug 12, 2016 at 16:49 comment added Shog9 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".
Aug 12, 2016 at 16:48 comment added JonH 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...
Aug 12, 2016 at 16:46 history edited Shog9 CC BY-SA 3.0
added 97 characters in body
Aug 12, 2016 at 16:41 history answered Shog9 CC BY-SA 3.0