50

It bugs me already a long time. There's inconsistency in what is called "examples". In the documentation section I was originally willing to find many examples for some topic, because this is how things are called there - Topics & Examples. But we don't create alternative examples which we could upvote/downvote and choose from. We call the example that we create some "sub-topic" and it is exactly it - a sub-topic, containing 1 or 2 examples by the guy who created the subtopic under the "examples" section.

This opens problems. By creating an "example" we "occupy" that. There is no space for others to suggest their own alternative examples of the same sub-topic! I mean, if you create another example - that is duplicating, but that is the only way to receive feedback by votes! On the other hand, if you decide to edit the original "example" by posting your own code as an example - then you must decide where to put it, as the last example? or as the first (because you think your example is better)? or maybe to delete the original code example? Then you cannot receive feedback by up/down votes. So users of the Documentation are not always seeing the best examples of topics, simply because actual code examples are not up/down voted. Only the sub-topics (so-called examples) are voted on depending on their usefulness, basically. However, the actual examples within that sub-topic might not be clear enough.

Does anyone else see this inconsistency? What if we just rename the "example" to e.g. "sub-topic"?

Take a look at this, which I ran into recently (which I found useful, but it clearly illustrates my doubts about the structure/naming):

  • within the "example" we see syntax, while there is also a separate place for syntax;
  • within the "example" we see another example;
  • there is only one actual example on this Convenience Functions sub-topic, which in some cases might not be good enough. It would be much easier to up/down vote alternative actual examples and not to start discussions over how to design a good example or unilaterally delete something.

Example is not example

19
  • 28
    I vote that the Documentation team comes up with a format of what this stuff is actually supposed to look like.
    – user4639281
    Feb 24, 2017 at 4:41
  • 54
    As it's standing now, documentation is not documentation.
    – GOTO 0
    Feb 24, 2017 at 6:33
  • 4
    The ability to get feedback by votes is the crux of the matter, I guess. I just realized I never thought about that. Maybe if Documentations had started with this kind of community feedback in place, it wouldn't have failed so miserable like now... or not.
    – justhalf
    Feb 24, 2017 at 6:57
  • 1
    @GOTO0 that is somewhat a tradition for Stack Overflow. For example, SO is stated to be "not a forum" but actually is. And yes, Documentation is not documentation. i think it's coming from constant changing minds and uncertainty, what Documentation actually should be. Feb 24, 2017 at 7:28
  • 12
    @YourCommonSense: "SO is stated to be "not a forum" but actually is." No, it isn't. Forums have discussion threads of arbitrary length and complexity. SO questions involve a specific question, and all "responses" are focused on that question. The closest to a forum we get are comments, which are deliberately limited to 600 characters. Feb 24, 2017 at 14:02
  • @NicolBolas in the sense of Docs.SO, it's a forum. A loose forum, but a forum dressed with "discussion".
    – Braiam
    Feb 24, 2017 at 15:06
  • 14
    Agree very much with this. I originally was pro-"Documentation" and intended to contribute to it, but the lack of clarity around the structure, what it's supposed to be, and what should go where has really put me off. SO itself has a pretty clear use case, even if you have to dig around and spend time on MSO to fully understand it. Documentation lacks even that; in fact, reading MSO posts about it just leaves me more confused about what it's supposed to be! Feb 24, 2017 at 15:13
  • 2
    @NicolBolas just because we try to keep it from becoming a forum doesn't mean that people don't thrash against the bars and make it as much of a forum as they can within those confines. :P
    – canon
    Feb 24, 2017 at 15:14
  • 2
    @NicolBolas so my eyes are betraying me. Gonna visit a doctor. Feb 24, 2017 at 16:19
  • @canon: Sure. But we throw them out. Feb 24, 2017 at 16:25
  • 3
    there's not much room for alternative examples anyway, considering there's a limit of 13 per topic.
    – Kevin B
    Feb 24, 2017 at 16:38
  • 4
    I was also excited about Documentation in the beginning because one thing official documentation is missing are lots of examples. But like you said, you can't add lots of examples any more because "examples" are really just subtopics and voting just creates a kind of meaningless topical sort order. I tried adding a different competing example once but it got deleted. I'm not giving up on documentation, but I'm also not contributing much any more.
    – Suragch
    Feb 25, 2017 at 14:56
  • 3
    @Shark: MSO is a perfect example of how bad SO is at being a forum. Feb 25, 2017 at 15:18
  • 2
    Documentation is a failed experiment not worth getting worked up about. Soon it will be put out of its misery (I hope). SO itself is all the evidence one needs that the efforts of 1,001 individuals all working to slightly different understandings of what is required and of what is desirable, with wildly different interpretations of what constitutes good (enough) English, let alone different interpretations of what constitutes good (enough) coding, all of that will not produce a coherent, well-structured collection of topics or series of examples. Feb 26, 2017 at 20:04
  • 1
    "Does anyone else see this inconsistency? What if we just rename the 'example' to e.g. 'sub-topic'?" I'm starting to feel really sorry for Jon Ericson et al. They've tried their darnedest to drill the concept of Examples into people's heads, but still practically no one understands and the ones who do understand have no idea how to incorporate the concept into the vast majority of popular tags.
    – BoltClock
    Feb 27, 2017 at 8:32

1 Answer 1

10

Looking at the OP's example, these are my thoughts.

TL;DR: Don't hesitate to make good edits, even though the rep and vote feedback systems are bad. Split Examples up as new Topics where appropriate.

Non-example content in the Example

  • within the "example" we see syntax, while there is also a separate place for syntax;

Remove it.

I removed many markdown tables here, for example. It's just unhelpful duplication of official docs, requiring very little effort from those who edited it in, so you shouldn't feel hesitant about removing it.

The number of examples in the Example

We call the example that we create some "sub-topic" and it is exactly it - a sub-topic, containing 1 or 2 examples by the guy who created the subtopic under the "examples" section.

Within the Example there should be only one example. Maybe it will be multi-part (looking at a single problem a few different ways), but it should not be a list.

If it's turning into a list, then the sub-topic is clearly too broad. You can split it up, leaving just one example, and moving the others to a new Topic, linked to the current Example. If you don't want to get the rep for creating those derived Examples, file an improvement request and let someone else do it. Here's an example of creating a Topic out of a sub-topic and then linking to it.*

Where to put new contributions related to the Example's sub-topic

There is no space for others to suggest their own alternative examples of the same sub-topic! I mean, if you create another example - that is duplicating, but that is the only way to receive feedback by votes!

As mentioned above, I think the Example should only have one example. Don't hesitate to overwrite the current example if you think it can be improved, since...

  • You shouldn't feel guilty about the rep consequences. The person who wrote the current example isn't going to lose rep thanks to the edit. And you aren't going to gain rep, since SO decided rep is awarded only for edits that add to bloat.
  • You can use the discussion tab afterwards to start a conversation like "This is better, right?" Alternately, I suppose you could make a draft of the edit and link to that for discussion.

    This is a much worse system for feedback than voting, since only a few editors will take part, but it's better than never editing this supposedly collaborative content.

If you regard your contribution as a variation of the current example, spinning off a new Topic (as mentioned above) seems fine and allows for somewhat better up/downvote feedback.


* I'm moving Examples instead of splitting one up here, but it's the same idea.

1
  • 1
    I like this advice overall, though I would still prefer to see a variety of examples.
    – Suragch
    Feb 25, 2017 at 15:02

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