27

Someone will probably point me to a readme/blogpost, but I don't really understand Stack Overflow documentation. Maybe it should be renamed Stack Overflow Examples?

Documentation usually has a table of contents. It's organized. Documentation usually has an introduction. Documentation usually progresses from simple topics to complex ones built on the foundations of the simple ones.

Stack Overflow documentation has examples first and foremost. I get you want examples, but where is a user unfamiliar with the topic supposed to start?

Maybe the problem is the topic I'm contributing to started with "Introduction to X". I have no idea who requested that or if it's the default, but an introduction to X (let's assume X windows) would not start with an example. It would describe what X is (it's a windowing system). It would probably also describe a few basic things about it (it's a client/server architecture unlike most local windowing systems). Until the user has some concept of those things the example isn't going to make much sense. But, there's no place to put that information. All you can do is add an example as the very first thing under the topic "Introduction to X".

I'm sure there's plenty of topics that need some kind of description before the example an plenty that need to start with baby steps and build up.

Am I missing it? Am I not supposed to explain those fundamental things? As it is, the hints seemed to suggest I was suppose those details in "remarks", but looking at the page created it seems unlikely any user is going to read the "remarks" section buried at the bottom of the page.

Am I just not understanding?

9
  • 2
    "Maybe it should be renamed Stackoverflow Examples?" Are you sure you didn't read the blog post about this? (That's a joke, clearly you didn't or you wouldn't ask. They do touch on that/a similar name on the blog.)
    – Kendra
    Jul 26, 2016 at 18:39
  • 15
    Yea I read it. I get that examples are important. I just don't get how that fits with documentation as a whole. Ok, documentation would be better if it was 90% examples and %10 explanation. But I'm not sure it's best with 100% examples and 0% explanation
    – gman
    Jul 26, 2016 at 18:42
  • 1
    @gman The explanation is alongside the examples though. Example: stackoverflow.com/documentation/php/617/json Everything about JSON … What the correct functions are, what the pitfalls are, everything. The only thing lacking a bit here is when to use JSON on that page. But that can be improved. in general, there's quite a lot of text … just subdivided in examples, which are some sort of sections without order (well, the votes are the order...).
    – bwoebi
    Jul 26, 2016 at 18:45
  • 2
    Related: meta.stackoverflow.com/questions/329179/…
    – Sumurai8
    Jul 26, 2016 at 18:47
  • 21
    You're thinking of Docs like actual documentation. Docs is actually an art project. It's not for you
    – Machavity Mod
    Jul 26, 2016 at 18:47
  • 9
    It should be renamed StackOverflow Copy-Paste.
    – TerraPass
    Jul 26, 2016 at 19:11
  • 2
    It's a cookbook. Physical cookbooks need organization, but the Stack Overflow Cookbook relies on Google search. Recipes ("examples") probably should explain things, but if people will just copy-paste the code, it's hardly necessary. Jul 26, 2016 at 19:31
  • 4
    Cookbooks often have chapters on technique. Recipes are only part of it. If a recipe says "blanch the asparagus" or "sous vide the steak" it often needs to explain what those techniques are.
    – gman
    Jul 26, 2016 at 20:21
  • 3
    I don't understand it either... Jul 27, 2016 at 4:31

0

Browse other questions tagged .