Timeline for answer to Warlords of Documentation: A Proposed Expansion of Stack Overflow by Andy
Current License: CC BY-SA 3.0
Post Revisions
22 events
| when toggle format | what | by | license | comment | |
|---|---|---|---|---|---|
| Mar 20, 2017 at 9:34 | history | edited | CommunityBot |
replaced http://meta.stackoverflow.com/ with https://meta.stackoverflow.com/
|
|
| Sep 7, 2015 at 12:34 | comment | added | Tro | This is the best suggestion in my opinion, as I would be very cautious about trusting reference material from anything but the official docs. Stack Overflow exists to educate and guide, and examples would definitely compliment this site. | |
| Sep 7, 2015 at 11:13 | comment | added | JsAndDotNet | @Plutonix (+78 at the time of writing) seems right for .NET. +1 for making Experts Exchange your enemy though. Glad not to see much of that these days. | |
| Sep 6, 2015 at 14:48 | comment | added | Sorrel Vesper | Instead of Documentations, Examples and Tutorials are a better choice, IMO. Because we don't come to SO to read a lot of documents, we just want precise answers and solutions. SO was meant to provide solutions and not the background history of why and what. | |
| Sep 4, 2015 at 8:51 | comment | added | Gimby | @AdrianHHH we're on the same page, lets just say that the only thing I'm rebelling against is calling it a "tutorial" as you can right now find them all over the net ;) What is proposed here is the replacement and banishment of the shitty tutorials, and I for one love it. | |
| Sep 3, 2015 at 21:42 | comment | added | J.D. Ray | @KevinMontrose - Trying to balance between snarky rhetoric trying for witticism and an actual question, how well documented do you expect Documentation to be? Well-written documentation should have a good style guide; something better than "put examples here". How do you plan to address that, if at all? | |
| Sep 1, 2015 at 19:04 | comment | added | Zeus56 | I applaud this effort, and have often wondered why there weren't more substantive usage examples available. I also realize this is not just for one language, but as a concrete example the major problem i find when consulting Google's Android SDK docs is the abysmal lack of usage examples. My searches almost always necessitate locating a suitable reference elsewhere to see and understand what should actually be done. | |
| Sep 1, 2015 at 18:59 | comment | added | NoDataDumpNoContribution | @KevinMontrose I see. It might not be what we others here envision. Tutorials are often long. Short tutorials might only be examples. Even good examples might become several pages long. Something that is shorter might be typical use case of a function instead of full blown examples. Maybe that is what you mean? I will certainly follow further meta posts. | |
| Sep 1, 2015 at 15:17 | comment | added | Kevin Montrose StaffMod | @Trilarion and many others. So, we've envisioned Documentation as containing several different "sorts" of pages (all in the same style view, with required examples and optional sections); including short Tutorials (and things like "Getting Started" or "Hello World"). Short Tutorials fit in this model, though long ones (several pages) don't really. I think we'll be expanding upon this, and a bunch of other stuff, in a follow up meta post. | |
| Sep 1, 2015 at 11:31 | comment | added | AdrianHHH | @Gimby Quite right on some tutorials. But good tutorials can be written to include the whys and the why nots and the alternatives. | |
| Sep 1, 2015 at 11:22 | comment | added | Gimby | I have one major problem with tutorials: they're tutorials. They end abruptly, are full of holes and tend to tell people where to click but not why, or perhaps even more importantly why click there and leave out the part that explains why not to click somewhere else. The people who read tutorials are generally the people who need far more than tutorials (and end up on SO), and the people who can benefit from tutorials generally don't read them because they only actually need a tiny subsection of it that they didn't commit to memory yet. Lets write guides instead. | |
| Sep 1, 2015 at 3:27 | comment | added | Asad-ullah Khan | @Trilarion Yes examples and tutorials are probably a better way to approach this. Documentation is not very helpful without a code structure to go by | |
| Aug 31, 2015 at 20:36 | comment | added | levininja | Examples may be the best thing about this, but I think it should in no way be limited to examples. If the developers of the product didn't bother to document HOW something works, and someone can provide that based on their understanding of the source code, it would be better to have that than not. | |
| Aug 31, 2015 at 20:36 | comment | added | Monica Cellio | Good examples are essential. Not every piece of working code is a good example, so we'll need peer review and editing. An example should be the smallest body of (realistic) code that demonstrates the feature, and everything important should have inline comments. In my experience the push for this comes from two places: trying to actually use the example (and realizing it's lacking in some of this) or trying to *explain the topic in words" (write documentation). We shouldn't be writing tons of text, but we probably don't want "none" either. (And yeah, then there are tutorials.) | |
| Aug 31, 2015 at 17:35 | history | edited | Peter Mortensen | CC BY-SA 3.0 |
(its = possessive, it's = "it is" or "it has". See for example <http://www.wikihow.com/Use-Its-and-It%27s>.)
|
| Aug 31, 2015 at 16:38 | comment | added | JackArbiter | Agreed AdrianHHH - Starting out on Microsoft products without examples and guidance, and just straight up nearly-meaningless (for a noob) documentation on MSDN, is harder than it should be. | |
| Aug 31, 2015 at 16:32 | comment | added | AdrianHHH | Some of the MSDN I use has lots of detail, but no examples and no guidance on how to use the software. So I support examples and tutorials. | |
| Aug 31, 2015 at 16:25 | comment | added | Shawn Mehan | So I was thinking along these lines as well. It's the examples that will add true value. But that means that the examples need to be peer-reviewed (duh) but also complete and self-contained. What needs to be there to make the example work needs to be there, or it's not really useful to the person that needs the example. So, there must be enough sample data provided to make that algorithm function, not just the mathematical markup of the theory. | |
| Aug 31, 2015 at 16:06 | comment | added | NoDataDumpNoContribution | So maybe just examples instead of full documentation? And the next step would be tutorials... | |
| Aug 31, 2015 at 16:00 | comment | added | Gabriele Petronella | totally agreed. When I google a class or a function, what comes up is often an official reference followed by a stackoverflow question. Most of the times I click on the question looking for a usage example. | |
| Aug 31, 2015 at 15:59 | history | edited | C. K. YoungStaffMod | CC BY-SA 3.0 |
edited body
|
| Aug 31, 2015 at 15:56 | history | answered | AndyMod | CC BY-SA 3.0 |