-3

There is too much stress on examples via documentation. Examples are put at the top as the first section when you click on a topic. To me when I ask someone to read documentation, I am asking them to understand something. To read the definition and have an understanding of how something works. Then and only then should they be presented with examples.

But documentation on SO seems to be quite the opposite - it seems to stress out that examples are far more important than the definition or how to of a language or a language feature. To me this seems to introduce problems because now we are giving answers (the example) before someone can even understand something.

Here's an example: https://stackoverflow.com/documentation/sql/280/example-databases/1014/auto-shop-database#t=20160725163945149134 there are plenty more where I think the background information - known as remarks (in which I hate to use that word but it is what it is), should be the first section / topic when clicking on documentation.

My proposal is to move the examples to the END, not the beginning. Closely related to what this user was asking: Documentation should have an initial section

16
  • Isn't the idea to put the explanation in the example? Examples don't have to be purely code Commented Jul 25, 2016 at 16:48
  • @MacroMan - True but I think people are using the tools in such a manner. Plus the wording "Examples" seems to give it a bad impression.
    – JonH
    Commented Jul 25, 2016 at 16:49
  • 4
    Probably needs more explanation in the editor - this is how I use it: stackoverflow.com/documentation/excel-vba/1576/common-mistakes/… Commented Jul 25, 2016 at 16:49
  • @MacroMan - That looks pretty good.
    – JonH
    Commented Jul 25, 2016 at 16:51
  • 5
    I think SO Docs is actually intended to be a cookbook rather than what (most of us) think of as documentation. Examples-first makes sense for cookbooks. Commented Jul 25, 2016 at 17:17
  • @JeffreyBosboom - I agree with your assessment 100%. But this could be confusing.
    – JonH
    Commented Jul 25, 2016 at 17:17
  • 1
    Quoting from the Documentation Tour: It's all about examples. Commented Jul 25, 2016 at 17:22
  • @ModusTollens - But it really shouldn't be...as mentioned thats a cookbook or cliff notes not documentation.
    – JonH
    Commented Jul 25, 2016 at 17:23
  • @JonH And that's the beauty of it. How many people read documentation? Commented Jul 25, 2016 at 17:24
  • 5
    A lot you'd be surprised. The ones who actually want to do things the right way..yes we read documentation.
    – JonH
    Commented Jul 25, 2016 at 17:24
  • @JonH I read documentation as well. But my experience on SO suggests we are a minority. Sadly. Commented Jul 25, 2016 at 17:25
  • 3
    A summary section above the examples would be nice. Right now it ends up in the remarks, buried at the bottom.
    – RubberDuck
    Commented Jul 25, 2016 at 17:38
  • 2
    Yeah, I'm still confused as to why they are calling it "documentation." This came up when it was announced, too: meta.stackoverflow.com/a/303981
    – Frank
    Commented Jul 25, 2016 at 17:43
  • @RubberDuck - That is exactly my tl;dr; move the remarks to the top so that people learn before they get the examples. It's quite the opposite right now.
    – JonH
    Commented Jul 25, 2016 at 17:56
  • 1
    @JonH I would actually like to see the Summary added. Then we could use the Remarks section for.. remarks.
    – RubberDuck
    Commented Jul 25, 2016 at 18:00

1 Answer 1

1

Unfortunately, this goes against the raison d'être for Documentation. Documentation on Stack Overflow is, to quote the site and the staff, "[...] all about examples."

From the Documentation Tour page:

Examples illustrate common tasks or solutions to common problems - remember "Show, Don't Tell". A good example is self-contained and succinct, and more often than not contains code. It is more important that code in examples be illustrative and focused than that it be copy/paste-able; leave out boilerplate when it distracts from the concept the example is meant to illustrate.

Because our goal is to ensure developers always have great examples, topics can't be created without at least one example.

In addition to examples, a topic has some optional sections. These serve to make examples more succinct, by allowing for documentation of common parameters, syntax, and other remarks that would otherwise need to be duplicated between examples.

To relegate Examples to the bottom of each Documentation page, you make the statement that they're not important, and run the risk of users not seeing them or only seeing the first one or two. It wouldn't make sense for the Stack Overflow team to design the layout of Documentation in such a way that sabotages its own prime function: useful examples.

1
  • 2
    Then they shouldn't of called it documentation - it should of been called cookbook or examples.
    – JonH
    Commented Jul 25, 2016 at 20:11

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