23

This post is 4 examples in one - and they seem unrelated. It all comes under the topic banner, but there is no good reason for them to be together.

So I edit 3 out, and go to add a new example but this happens:

Now I know why this example is 4 smushed together. There's a cap. I can't see any way this topic could be sensibly split - it's the "Changes between Python 2 and Python 3" topic, so this limit is really making it harder to browse.


What can be done about this?

1

3 Answers 3

34

What can be done about this?

Simple: get rid of such "list of stuff" topics altogether. They tend to be problematic for reasons discussed here. Google can find the changes from Python 2 to 3 just fine on its own, so we're just duplicating stuff that has been adequately documented. Such topics make a mockery of the example voting system, and they cause topics to be needlessly huge.

We don't allow list questions; why should we allow list documentation?

32
  • 2
    Sure. :-) See Drawing common complex shapes. This Topic contains some of the many shapes that users may need when creating Charts, Diagrams, Image Annotations, Game controls, etc. The shapes are not exclusive. Any shape might be used when creating multiple apps. And there are many more "everyday" shapes that we might add if allowed the space. Originally we thought to make each type of shape an Example (for easy searching). Any suggestions now that the Example limit applies?
    – markE
    Commented Aug 15, 2016 at 17:27
  • 4
    @markE: Each of those is a separate task. Someone who wants to know how to draw arrowheads doesn't necessarily care about drawing stars. Someone interesting in drawing stars doesn't necessarily care about drawing a pie chart. And so forth. Those things out to be separate topics. There needs to be a distinction between "topic as categorization" and "topic as thing to do". The former is a misuse of topics. The only reason we do it is that it's the only form of categorization we have. Commented Aug 15, 2016 at 17:57
  • 1
    Granted, stars & pie-chart are an unlikely pairing. But many of these elements are daily used in combination. Frankly, I stopped adding elements to this Topic when the Example limit was imposed, but there are many other common shapes that could be categorized under this (too broad?) Topic. So if the Topic is being misused (too broad) and yet if it's the only form of categorization we have, how should I proceed: 1. Elevate each shape to a Topic with 1 or 2 examples, 2. Continue to group shapes in larger, general Topics. 3. Something else?
    – markE
    Commented Aug 15, 2016 at 18:22
  • 2
    @markE: I don't really see how having a bunch of random diagrams under one heading is helpful to anyone. Do you really expect people to sift through 20 examples of stuff they don't want just to find the one example that they might be interested in? Commented Aug 15, 2016 at 18:49
  • 1
    Well, yes -- that's what I thought when I set up the Topic! I think it's marginally better to sift through one Topic with 20 related shapes and pick the 3-4 that you need rather than to search for the 3-4 shapes individually. BTW, I'm not pushing an agenda here...I honestly want to know how to handle the question of "Example limit inspires all-in-one smushed Examples". I really need some guidance that I haven't found yet. :-)
    – markE
    Commented Aug 15, 2016 at 19:00
  • 5
    @markE: "I think it's marginally better to sift through one Topic with 20 related shapes and pick the 3-4 that you need rather than to search for the 3-4 shapes individually." Examples have titles, and even the Godawful search system in Docs.SO can search based on those. If someone needs to draw a pie chart, they'll find the example for it no matter what its topic is. The question is, do we want a big topic of random drawing stuff, or do we want to put "draw a pie chart" inside a task that's about... drawing pie charts. There's more than one way to draw a pie chart, after all. Commented Aug 15, 2016 at 19:06
  • 3
    @markE: "How do you suggest I handle related non-homogenous elements." It all depends on how you define "related". I disagree that the topic you showed had elements that were "related" by anything meaningful. The only relationship was that they all involve drawing stuff. And that's not the kind of relationship that the current Docs.SO system effectively handles. Even without the example limit, I would argue that Docs.SO works better with focused topics. The kind of relationship is not entirely unimportant, but Docs.SO has no mechanism to support it. Commented Aug 15, 2016 at 19:40
  • 1
    @markE: Think about it this way: what would you do in Stack Overflow if tags didn't exist? Well, you'd still answer questions as you always did. It would simply be harder to find questions that have similar aspects. Commented Aug 15, 2016 at 19:41
  • 1
    @markE: "Topic=*Simple Pie Chart*, Topic=*Simple Donut Chart*" Why only "simple"? Why should the topic forbid more complex examples? You seem to be thinking too much in terms of "how to find a place for the code on the site" and less in terms of "what are good tasks that users want to do?" Commented Aug 15, 2016 at 20:23
  • 2
    @markE: You can answer questions however you like. But you're talking about documentation. That's a community issue. The last thing Docs.SO needs are a bunch of "beginner" topics. Commented Aug 15, 2016 at 21:00
  • 2
    @markE actually it doesn't need them, because most "beginner" stuff already exists. Focus on documentation that we don't have anywhere, instead of documentation we ought to have.
    – Braiam
    Commented Aug 16, 2016 at 19:02
  • 4
    @markE: "Is uniqueness really a primary criteria for Docs?" "If a project already has awesome documentation that's easy to search and cite, then there's no need to duplicate it on Stack Overflow. We're interested in fixing what's broken with documentation" That sounds like a "yes" to me. "I think we're failing" Throw it on the pile of other things Docs.SO fails with. Commented Aug 16, 2016 at 19:45
  • 3
    @markE: "So would your ideal Docs === "Unique Advanced Topics"" ... where are you getting this "advanced topics" stuff from? My point is that there shouldn't be beginner or advanced topics. Topics should be based on what you want to do, not how you want to communicate with people. There's no such thing as an "advanced" way to do a find/replace in a string. There's no such thing as a "beginner" way to search through a filesystem. Topics do not need to have a skill level on them. Specific examples might be easier for some than others, but the topic itself is what it is. Commented Aug 16, 2016 at 19:59
  • 4
    @markE: "I just remain confused about what I should be submitting to Documentation." Everyone is. Nobody knows what it should be, least of all the Powers That Be. They've decided to take a "wait and see" approach to deciding how Docs.SO should work. I'm merely trying to catalogue the only effective way where Docs.SO as it is currently designed can achieve the goals that they claim to want. Commented Aug 16, 2016 at 20:03
  • 5
    This is really a very bad use case for docs: Python (and most of its most popular libraries) has notoriously good official documentation, so most of SOD is pointless for that. Whoever is willing to google can already find virtually everything (especially with the crutches of SO main). This also explains why there's an insane amount of plagiarism in this SOD tag. Commented Aug 16, 2016 at 23:13
0

What can be done about this?

In general, make the topic smaller. If you define a topic as anything that can be comprehensively treated in not more than 3-12 examples, then topics with a scope greater than this must simply be split. Don't allow different, unrelated parts in an example. Although an example can be somewhat complex, all the parts of an example must relate to each other.

2
  • This doesn't really answer the question, IMO, since the topics listed do relate to one another, they're just better suited as footnotes in other topics (probably). I feel like this is a noop answer.
    – ssube
    Commented Aug 15, 2016 at 20:10
  • @ssube If the examples relate to each other than combining them in one example is fine. However OP wrote that they do seem unrelated. If they are unrelated then splitting the topic looks like a good idea. Having footnotes in other topics is fine with me too (it's kind of a splitting). What exactly would you like to have from this answer? A specific proposal what to do for the mentioned topic in the question? Commented Aug 15, 2016 at 20:49
0

This is an attempted solution that failed miserably.

Say your car has a broken engine. So you go up to the mechanic (the Stack Overflow dev team) and say "My car has a broken engine. Can you fix that?". After a few minutes of waiting, the mechanic comes back and says "Your car no longer has a broken engine." You thank the mechanic and start the car. But it doesn't start.

You ask the mechanic why the car won't start. S/he says, "because I removed the engine".

I hope you've learned the moral to this "fable". Instead of fixing the actual problem, the dev team just limited the number of examples per topic.

Really, this should be a comment. But it doesn't fit in a comment and deserves more attention than a comment.

3
  • 1
    I don't think it does. This is speculation and doesn't actually help anyway. Also, it doesn't fit in the comment area because you added a fable for some reason, instead of just saying what you wanted to say (one sentence). Commented Aug 16, 2016 at 23:17
  • @AlbeyAmakiir a lot of meta posts start with a fable. Commented Aug 17, 2016 at 0:09
  • Actually, this fable would be more applicable if the dev team had removed Documentation altogether. And such a move would have been widely celebrated.
    – Cody Gray Mod
    Commented Aug 17, 2016 at 14:34

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