Documentation Issues

Issues we have with documentation.

  1. Users plagiarising content from other peoples' work and being rewarded rep for it.
  2. Typo corrections to examples only contributed by me need reviews
  3. Change control is not per-example but per-topic
  4. In Python there are multiple topics with the same name Exception, and several other duplicated topics. Takes ages to move these around.
  5. No way of penalizing users who make it harder to review - no, they just gain more reputation.
  6. Even elected moderators do not know what they can do in the documentation site.
  7. Flood of incorrect examples; if I “fix” them, the original user gets reputation; if I do not fix them and instead post my own one, then there are too many examples for it to be useful to anyone
  8. The interface is very messy, it is very difficult to navigate between dashboard and review requests and what not.
  9. People posting to wrong tags altogether, and there is no way to deal with them
  10. There is seemingly no reputation limit for approving change requests
  11. The accepted way of displaying code is the Python interactive sessions. However people tend to prefer a way that would be “copy-pasteable” directly to Python interpreter. IPython has a paste mode wherein you can paste interactive sessions and it just executes the actual code parts.
  12. Cannot navigate to the proper topic page from drafts
  13. Comments seem to be restricted to change requests currently in review. For instance, there’s no way to communicate with someone who rejected your change, or to leave a note to a submitter after rejecting their change.
  14. There’s no “Improve edit” functionality: a change request with some simple yet clear issues (typically typos, or misleading phrasing) can either be rejected (–> need to leave note, see previous point), approved (–> need to submit a subsequent minor change request fixing the issue, to be reviewed again), or not handled while trying to coerce the submitter to fix their submission themselves prior to approval.
  15. Censorship of the Anti Documentation Party team which just wanted to express disappointment but got deleted instead.
  16. No way of commenting on an incorrect improvement request, or requesting clarification
  17. Editing a topic will only notify you if somebody has a draft of the same topic; submitted changes are not shown. This is especially fun because conflicting edits nicely roll back each other, see also point 3.
  18. There is no button for version tagging in the example editor, you need to know the syntax by heart
  19. It is possible to do edits on a couple dozen examples at one go which either needs to be rejected or accepted fully
  20. There is still no “focus section” for topics
  21. There are no notifications for edits to an example. One would want to get notified on edits to a single example
  22. There is no discussion per example
  23. There is no topicwise discussion anywhere
  24. There is no tagwise discussion anywhere
  25. The more editors on an example, the more reputation generated to the system by a single upvote.
  26. There is no way of putting two sets of versions on one example except the undocumented <!-- if version <Python 2.x> [gte 2.3] --><!-- if version <Python 3.x> [gte 3.0] --><!-- end version if --><!-- end version if -->
  27. Anyone can add versions with one approve, even those that do not have any significant use at all.

Examples

  • Good content from great existing answers (e.g. as collected in our canon) on Q/A are used to create documentation entries. Because it’s not the users who wrote the original answer that create the docs, other users are effectively receiving work for answers that existed for a long time on SO.
  • Lots of people copying examples from the official Python documentation. That takes no effort but still rewards lots of reputation. The easier and more basic the example, the more reputation they will end up getting.
  • http://stackoverflow.com/documentation/proposed/changes/27581 – Adds content from a book. Has proper attribution but is still receiving rep for something that isn’t their own.