27

Recently a limit to the number of examples per topic was introduced: 6 examples per topic for all users, 12 examples per topic for users with full editing privileges (2000 rep). I suppose that means that 6 examples should be enough in almost all cases, and in exceptional cases more examples can be added.

However, old topics with many examples were silently grandfathered: they keep all examples, you just can't add any more. Considering there're many of these topics and they're the most active, something must be done, because right now, they all are incorrectly organized, according to the current rules.

Some topics, like "Java Pitfalls", were already split (in this case into "Java Pitfalls", "Java Pitfalls - Exceptions", "Java Pitfalls - Language syntax"). Considering lack of cross-linking in any form (either traditional documentation hierachy (unsupported), or tagging with categories (unsupported), or even linking in the Remarks sections), I consider this counter-productive, as it's now harder to find all parts and read the whole topic, but I guess it's up for debate.

So, let's start doing something. Here're some of the topics which are considered incorrectly organized under the current rules (in order of popularity, which is a sum of upvotes I guess):

Okay, here is the list. What do you think should be done with these topics?

P. S. I included topics with 7-12 examples because there're a lot of them. Every second topic can't be an exception, so something needs to be done. In the current state, examples can't be added to most of the top topics, unless you have 2000 rep.

6
  • 3
    In some cases they should be splitted in more topics (just done for RecyclerView in Android for example). In some cases, for example Android for Gradle, Picasso the examples should be moved in the dedicated tag. In other cases same examples are duplicated or useless and we can do a pool to vote to remove them. Commented Aug 13, 2016 at 11:01
  • 6
    For some of these, it is obvious how they might be split up (like LINQ). But I would be very curious to see how, for example, someone would suggest splitting up a topic about the nameof operator. That already seems as narrowly scoped as can be. Now, if it were me, I'd just delete most of the examples because I can't see how they're useful. But I could say the same thing about everything on Documentation, so that isn't really constructive.
    – Cody Gray Mod
    Commented Aug 13, 2016 at 12:41
  • It would make a lot more sense to create separate questions about the worst offenders, instead of creating a single question that covers a wide variety of Documentation topics. Commented Aug 16, 2016 at 1:50
  • @KevinBrown I don't care about "worst offenders", I care about the rest of topics. 80% of active topics are above 6 examples per topic. This post isn't about exceptions with 25+ examples, it's about all topics which violate recommendations with 7+ examples. Considering there're literally hundreds of them (the list in the post includes only popular topics in top four tags), there must be some common problems and solutions, they can't be unique. Otherwise we're screwed.
    – Athari
    Commented Aug 16, 2016 at 4:17
  • The point that I was trying to make is picking 132 examples and saying "what can we do about all of these?" is not going to get very far. There are too many examples to look through and attempt to pick common issues from. People will inevitably look at this post, say "yup, you have a point", give you an upvote, and move on because they don't want to sink the time into digging in deeper. My suggestion was to split or reduce the scope. Commented Aug 16, 2016 at 12:24
  • @KevinBrown There're enough people who support the limit on examples, including those who decided to introduce it in the first place. I thought they will answer — surely they should have a good idea how to improve Documentation before declaring 80% of most popular topics are wrong. / If you have any ideas on how to approach fixing 500 topics, I'm all ears. If I had an idea how to fit topics into scopes, I wouldn't need any answers.
    – Athari
    Commented Aug 16, 2016 at 15:41

1 Answer 1

34

The number of examples in the largest Python documentation topic Compatibility between Python 2 and 3 was a symptom of far worse problems with the documentation system.

The current state of that topic was the result of merging very different topics into one (the topics were one that briefly explained the major differences between Python 2 and 3 for beginners, and the one explaining how to write Python 2 and 3 compatible code aimed at library developers, one detailing __future__ imports), thus creating this abomination. At first it was called Python 2 vs 3 but then again it was renamed into Compatibility, and that stuck. These merges could perhaps have been avoided if there were a properly written "Focus" section.

Afterwards, someone raised an issue with it having too many topics (IIRC it was at 87 at that time), and someone then removed the correct or thorough examples of everything from the compatibility topic, retaining the incorrect or superficial examples from the beginner topic, as the former had more upvotes than the latter. (So clearly now everyone should be happy as the number of examples was brought down).

And since this topic has been the most popular topic there, we've seen not only utterly useless edits usually with one rejection and one approval, but also people adding incorrect information to correct examples just to buy the ticket to the "internet-points train". As a result by now pretty much everyone who actually holds a gold badge in has lost all hope on the documentation ever being something sensible and doesn't even want to look into there, let alone fix any mistakes.

Thus, this is exactly how the current system was designed to work - lack on any limits on privileges, lax rules on approvals (if there is a pending edit on the example that you're going to edit, then better approve it now than risk your addition being rolled back when the other is approved), no structure in documentation, no focus section, "everything is an example", "examples are independent", everyone gets rep for useless edits - basically everything in the then system and how it rewarded its contributors create this mess. I hope that the review limits from Documentation Update, August 4th will help alleviate these problems.

However, even now, the Focus section is needed for this to not repeat. As it is now, even if I split these into separate topics, there is no way of telling others what examples should be expected under each topic. Additionally, the focus should be visible when approving any edit from the queue.

8
  • 2
    Wow, that's an epic story of a failure! Shouldn't it be possible to find major merges and removals in the edit history?
    – Athari
    Commented Aug 13, 2016 at 11:23
  • 26
    "pretty much everyone who actually holds a gold badge in python has lost all hope on the documentation ever being something sensible and doesn't even want to look into there, let alone fix any mistakes." That's very much how I feel about C++'s documentation. Commented Aug 13, 2016 at 13:23
  • 4
    I think the only sensible thing to do is to dump everything somewhere and start from scratch.
    – Braiam
    Commented Aug 14, 2016 at 22:11
  • 3
    Or skip the start from scratch part.
    – kjhughes
    Commented Aug 15, 2016 at 16:45
  • Suggestion: Delete the topic and have any "Python 2 vs 3" examples moved into the topics that they relate to. Commented Aug 15, 2016 at 22:28
  • @KevinBrown Your suggestion assumes that your topics hierarchy ("examples should be organized by language features") is superior to the existing one ("examples should be organized by use cases"). I disagree. Both are correct and both should exist in a well-organized documentation.
    – Athari
    Commented Aug 16, 2016 at 4:21
  • @Braiam We can't start from scratch. Both good and bad editors seem to have abandoned the ship...
    – Athari
    Commented Aug 16, 2016 at 4:23
  • @Squidward I actually agree that "examples should be organized by use cases" is superior, but unfortunately SO Documentation does not support that very well. The issue with organizing examples by use cases is that examples tend to fit into many use cases, and Documentation doesn't allow you to reference examples well (as you've noted). The other issue that comes up, which the "Python 2 vs 3" topic clearly shows, is that the examples tend to cover a wide variety of things, with nothing clearly bringing them together. That was addressed in this answer, with the "Focus section" being mentioned. Commented Aug 16, 2016 at 12:31

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