Skip to main content
7 of 7
replaced http://stackoverflow.com/ with https://stackoverflow.com/

Documentation Update, August 4th

This is the second post in our series of regular (roughly weekly) updates on the Documentation Beta. See also the previous post in the series.

Shipped Changes

Review Rules

We've just enabled an update to creating and review proposed changes, so that now:

  • Users with a silver or gold tag badge (from Q&A) will skip review when they make an edit to that tag's documentation
    • This include aliases, so a silver badge will work on 's documentation
    • If multiple tags are involved (because of moving examples, or submitting multiple topic changes as one) you must have a badge in each tag to skip review
  • Users with a silver or gold tag badge can one-click approve or reject a proposed change from another user to that tag's documentation
  • Reviews now take 4 "votes" to approve or reject, and how many votes a users approval or rejection counts for is based on their reputation
    • users with >= 10,000 rep get 3 votes
    • users with >= 1,000 rep get 2 votes
    • users with >= 100 rep get 1 vote

Rejection reasons

We have also added a duplication rejection reason, and the existing copied content rejection reason now asks for a URL (or comment).

Planned Changes

Review Queue

A traditional review queue for proposed changes, as announced last week, is still being worked on. Here's an updated mockup.

Updated review queue mockup

New "Focus" Section For Topics

We're also still working on the "Focus" section at the top of Topics, trying to determine the best length and guidance so that they're useful to both consumers and future editors.

Some attempts that have been done internally:

This topic demonstrates how to use generic types in class and method declaration, how to apply various constraints to those generic types, and how to instantiate types and invoke methods that meet those constraints.

(for Generics)

This topic covers what options are, how to create them, and how to consume them. Language features specifically for working with options are also covered.

(for Options)

This topic covers creating and modifying the built in array type. Common built-in operations such as searching are also covered.

(for Arrays)

We're hoping that this section will give a consumer a very quick idea of what they're going to find for the rest of the topic (so they can know whether or not to keep reading) and for someone reviewing a change to a topic to know whether the change is "in scope".

Template, guidance, other thoughts (or names) are all appreciated - we're puzzling this one out. I will say that we're trying to steer clear of "Summary" because we strongly believe in that summarizing a whole topic would produce overly large chunks of text which would be of marginal utility (compared to examples), quickly out of sync (due to other edits not correctly updating a summary), and push more useful content down in the page.

Example Limits

Because some Topics are growing larger than anticipated, we'll be adding soft and hard caps to the number of examples a topic may have. One of the goals of Documentation is to create concise content, and I think it's pretty clear that's not happening in a number of cases.

The soft cap will warn high rep editors after the 6th example, and prevent low rep editors from adding a 7th or greater example. The hard cap will prevent anyone from adding a 13th example. Existing content will be grandfathered in, we're not going to blanket delete anything.

The limits may be tweaked in the future. They're best guesses for "a topic with this many examples is unreasonably large, from the perspective of a consumer or reviewer".

Learnings

Reputation

We've been spending a lot of time internally finding and discussing problems with the current reputation system. Some of these thoughts have also ended up on MSO.

We don't have all the tweaks we want quite spec'd out yet, but I expect we'll have a plan together to share next week sometime.

To lay some groundwork, here's what the Documentation reputation system is intended to accomplish:

  • The creation of missing Documentation
    • "Missing" is sourced from individual contributors own knowledge or requests from the community
  • The creation of Documentation that is useful to real developers
    • This means documentation that is useful to read, and useful to cite
      • Citations in general are good, citations in Q&A are even better under the theory that answers are especially improved by having references for additional learning
  • Reinforce good editor behavior
  • Reinforce good requester behavior
    • There's value in "New To X"-users indicating the trouble spots they're encountering using X, so that more knowledgeable users know where to focus their efforts.

The current system (rewarding all substantive contributors to an upvoted example, all substantive contributors to an example cited in an upvoted answer, creators of approved changes, and requesters of created topics) has the following problems:

  • Too much reputation awarded for contributions to single popular examples
  • Too many edits are considered substantive when they are not really
  • Reputation generated is about the same for small and large contributions (especially true for edits) which feels out of whack
  • Too many examples created due to incentives
  • Examples being edited to be very large due to incentives

A related problem is too much dodgy content getting through review. Review changes, both completed and in progress, are meant to address that.

We are working on a new reputation plan (to be posted soon) that should address all of these issues.

Kevin Montrose
  • 22.6k
  • 24
  • 76
  • 74