126

This is the third post in our series of regular (roughly weekly) updates on the Documentation Beta. See also the previous post in the series. Yes, it’s been three weeks since the last update, but at Stack Overflow all numbers less than 6 are basically 0.

The big news is that we've got a lot numbers about reputation, and have hashed a new model we'll be implementing in the coming weeks.

But first...

Shipped Changes

Improvement Requests

We’ve been making improvements to improvement requests:

  • improvement requests now require 2 votes to dismiss.
  • you can now handle improvement requests submitted by others on a topic or an example even if you also put in a request of your own.

Other changes currently being considered include:

  • only allowing one improvement request of a given type (e.g. "missing example") - additional requests of the same type would be converted into upvotes on the original request.
  • improving the UI to make it clear that when you pick a reason for a downvote on an example, that reason is actually converted into an improvement request.

Example Limits

There are now two rules in place to keep the number of examples on a topic in check.

  • Users with less than 2,000 reputation cannot propose creating a 7th or greater example
  • No users can propose creating a 13th or greater example

These limits do not apply when proposing a roll back, and existing topics retain however many examples they had before these changes.

The intent of this change is to encourage very large topics to be broken up, and to discourage overly specific examples. We don’t think this change by itself is sufficient to accomplish all that, but it’s a step in the right direction.

Planned Changes

Proposed Changes Review Queue

It’s still coming. Adapting review to handle Documentation is pretty complicated it turns out.

“Focus” or “Introduction” Section For Topics

Also still coming. We won’t be introducing this until the review queue is shipped, since it has significant implications there.

Topic Outline

Based on feedback, we're going to be making some changes focused on making it easier to scan and navigate individual topics.

We’ll be adding a topic outline in the sidebar, here’s an early mock-up:
Topic outline

As part of this, we'll also be removing example collapsing, and the side-by-side view.

Both of these features were meant to make it easier to see more of a topic at a glance, but ultimately proved too confusing (in the case of example collapsing) or saw little use (in the case of the side-by-side view).

Reputation

Now for what most of the last few weeks have been spent producing, a planned update to Documentation’s rep system.

In the previous update, we laid out some things that the rep system was supposed to encourage:

  • Creation of missing Documentation
  • Creation of useful Documentation
  • Good editor behavior
  • Good requester behavior

While digging through the data, we’ve added some more things we think are important to encourage:

  • Correct choice between creating and editing
    • A user should be fairly rewarded for making the right choice, whether that is creating new examples or improving existing ones
  • Review independent of potential rep gain
    • “Trivial changes” shouldn’t be rejected because they’ll earn rep and don’t deserve it
  • Predictability
    • The rules should have an obvious logic to them, and behave “as expected” once learned

The System

A few notes to start off.

Anything below that counts characters or diff lengths ignores whitespace and formatting. Nothing in the system is going to treat "foo", " foo ", or "foo" differently, for obvious reasons.

All reputation figures are given as if the daily rep cap did not exist. This let us focus on the potential reputation from Documentation, but naturally the daily rep cap is not being removed.

We’re not making any changes to rep from citation in upvoted answers at this time. Right now there isn’t enough data to justify changes.

Changes to what earns +2 when it is reviewed

Overall this part of the system is mostly working, but we’ve got a couple of changes to address some issues we found.

  • If a change rolls a topic back to a previous version, that change will not earn +2 upon approval
    • Rollbacks should be proposed and judged independent of rep rewards
  • If the user who proposed the change to a topic was also the last editor of that topic, that change will not earn +2 upon approval
    • While it is acceptable to make several changes over time, there should be no incentive to break up an edit you could have made in a single change

Changes to who earns rep when an example is upvoted (ie. who is a “substantive” contributor)

This is the largest source of rep right now, and is seeing the most changes accordingly.

  • Example creators will continue to earn +5 reputation per upvote
    • It makes sense that the first contribution is “substantive”
    • A new example must stand on its own, and we see that in how much larger (3x to 4x) they are the the typical edit
  • Changes that remove more characters than they introduce will never be considered substantive
    • Sometimes examples and topics are improved by removing content, but it both feels unfair to reward it and incentivizes some destructive behaviors
  • Changes that add fewer than 20 characters will not be considered substantive
    • Most of these changes are minor copy edits, grammar or punctuation fixes, etc. that don’t merit recurring rep rewards
    • These changes will still receive a one-time +2 upon approval per the previous section
  • Changes of more than 20 characters will be considered substantive, but only earn the editor +1 reputation per upvote (instead of the +5 they get today)
    • Around 20 characters, changes start making a real difference in a typical example
    • However, a 20-character change doesn't deserve as much reputation as the creator the vast majority of the time
    • This does not stack. Making two 20-character edits to an example does not mean you’ll earn +2 from subsequent upvotes
  • If a user ends up contributing more than 350 characters to a single example, they will earn +5 reputation per upvote
    • Edits this large are almost always major, impactful contributions
    • 350 characters is close to (about 3/4ths) the same size of the typical example's first revision
    • These characters can be split across multiple changes (though see below)
    • This does not stack, no matter how many or what size edits are made to an example; a user can never earn more than +5 per upvote
  • For both the +1 and +5 levels...
    • Edits smaller than 20 characters are ignored when summing "total characters contributed": you can't change enough punctuation to become "substantive" logically.
    • Moving up a level is not retroactive: editors are judged on their contributions at time of upvote, not their total contributions to date

Removing reputation

  • In keeping with the current system, deletion of a topic or example will remove all rep awarded from it
  • Rollbacks will remove the +2 awarded on approval from the changes that were undone
  • Rolled back changes will be removed from “substantive” calculations, and upvote rep adjusted accordingly

As with Q&A, if reputation is live on the site for 60 days then deletions (and rollbacks) will not remove it. This doesn't apply to changes to the rep system, so the re-calc that accompanies this new system will affect all Documentation sourced rep no matter how old.

Notes

  • This system will remove about 50% of all Documentation sourced reputation
  • The most impacted examples are the giant “Java Arrays”-ish ones, which end up awarding about 70% less rep
  • The daily rep cap remains in place for example upvotes
  • The +2 rep on approval will not be subject to the daily cap
  • We selected the various character limits based on aggregates and hand auditing. Some additional statistics:
    • About 20% of all additive edits add less than 20 characters (and will earn no recurring rep)
    • About 80% of all additive edits add less than 350 characters (so ~60% will earn +1 recurring rep, and ~20% will earn +5)

It’ll probably take us a week or two to get this system implemented; expect an announcement when the rollout begins.

27
  • 5
    @JoshCaswell there's a lot of discussion about commenting (on topics, examples, requests, drafts, etc) and general "talk" functionality happening, don't worry. Just don't have anything concrete to share yet. Commented Aug 29, 2016 at 18:37
  • 74
    "This system will remove about 50% of all Documentation sourced reputation" Great! A large recalc will be good for getting things back in balance. Now excuse me, I need to go review and try to help keep the site clean that way before my rep drops below 500 again... (Really, I'm liking this update. Keep up the good work, folks!)
    – Kendra
    Commented Aug 29, 2016 at 18:47
  • 31
    How does moving code around in a single example affect the diff? I.e. moving a code block a section higher inside an example will easily trigger the 350 rep threshold? Do you only check the pure diff (as we see it the inline diff viewer) or also how much actual new content is introduced? Also "Changes that remove more characters than they introduce will never be considered substantive" is a good idea, but this encourages splitting a change up into two revisions, first rev removes the content and second rev adds the new content.
    – bwoebi
    Commented Aug 29, 2016 at 18:56
  • 6
    This looks great! Having small tweaks give less rep than big ones makes intuitive sense, and will stop me looking askance at people who correct typos. Commented Aug 29, 2016 at 21:57
  • 5
    Still nothing about moving topics :( "JavaScript Language" topic is still full of API examples and AFAICT no way to move them under their respective API tags
    – user128511
    Commented Aug 30, 2016 at 2:16
  • 54
    "Changes that remove more characters than they introduce will never be considered substantive" Going strictly for the length is probably the simplest measure which still makes some sense, but often enough removing content is as important as adding content. Shorter texts conveying the same information are often better than longer texts. Here I think you are actually incentivizing bloat. By going for length of edits you clearly want that people spread their arguments over more text. I mean that for a substantial edit it's not enough to change the sign, better also add a line explaining it all. Commented Aug 30, 2016 at 7:59
  • 4
    From another comment. What if somone effectively removes more than 20 characters? Why cannot this also be substantive? Should it be a substantial improvement? Or what if some add 40 characters but then removes 20. Should he/she split the edit or should we count characters changed instead (and make the limit 30)? Commented Aug 30, 2016 at 9:29
  • 20
    @KevinMontrose It's only rep in the end but maybe we should also think ahead. At some point we don't want the content grow in length anymore but improve the quality. Then a length based rep criteria will break down somewhat because there will hopefully many substantial edits which do not increase the length of a contribution but improve the quality. Not sure what is the best. Maybe don't subtract the deletions and only count the additions and mark as substantial if there are at least 20 added characters. Commented Aug 30, 2016 at 18:44
  • 9
    "Changes that remove more characters than they introduce will never be considered substantive" I have a book for you. On that note, can we get a style guide? I've stopped reading examples because I lack the patience to fix the incessant switches among 1st, 2nd, and 3rd persons in every single one.
    – alistaire
    Commented Sep 1, 2016 at 4:56
  • 5
    This update balances reputation quite a bit. I still think documentation should have its own reputation and privileges, just like the various *.SE sites. Would be much clearer. Commented Sep 1, 2016 at 11:54
  • 4
    There should be something between +1/upvote and +5/upvote. Maybe something like 50 chars = +2, 100 for +3, and 200 for +4. Each successive "bump" is harder to get.
    – Daniel M.
    Commented Sep 4, 2016 at 19:23
  • 3
    I feel my documentation rep gain and fairly received and not excessive, and now I am going to lose half of it? Commented Sep 5, 2016 at 9:37
  • 12
    So in essence that means it will net me absolutely nothing to entirely rework an example to be better unless I also make it substantially longer
    – Magisch
    Commented Sep 6, 2016 at 8:40
  • 16
    That also means that someone who posts a horribly bloated mediocre example will ensure he gets continous reward if people fix it and it ends up nothing like the original, while editors fixing it mostly get nothing. Together with the example cap, this makes for a situation in which FGITW is not just encouraged, but a sure-fire way to ensure all future user effort to a topic rewards the FGITW person rather then the real contributors.
    – Magisch
    Commented Sep 6, 2016 at 8:58
  • 3
    @Trilarion Thats just a recipe for ginormous amounts of drama and vote-fixing.
    – Magisch
    Commented Sep 8, 2016 at 17:10

6 Answers 6

61

only allowing one improvement request of a given type (e.g. "missing example") - additional requests of the same type would be converted into upvotes on the original request

When you "flag" for improvement, you're prompted to enter a brief explanation or description:

Description field of Improvement Request dialog

I find that when looking over improvement requests, later requesters have often added useful information over and above the original requester. Currently these are displayed as additional points in the improvement request banner:

Improvement request banner showing descriptions from multiple flaggers

Please preserve the ability for the later requesters to add commentary in some way.

5
  • 36
    Yes, absolutely.
    – Adam Lear StaffMod
    Commented Aug 29, 2016 at 19:01
  • 14
    I've found out that many improvement requests themselves are incorrect, yet I have no way of telling them and other reviewers why I consider them incorrect (including adding links to other documentation sources). Commented Aug 30, 2016 at 4:53
  • @AnttiHaapala I've been idly thinking about introducing dismiss reasons for improvement requests, but I'm not sold on that being anything other than "too complicated for its own good". We're also exploring some ideas for improving discussion around topics (nothing solid enough to present yet), and keeping improvement requests in mind for that as well.
    – Adam Lear StaffMod
    Commented Aug 30, 2016 at 5:14
  • 3
    I often find that I would like to comment on an improvement request. Either because I disagree or because the request is unclear. I think it would be very helpful to have a mechanism to discuss potential changes before proposing an edit. Commented Sep 3, 2016 at 6:05
  • At the bare minimum, I would suggest adding at least two dismiss reasons: "Request is factually incorrect", and "Request is unclear". Commented Oct 19, 2016 at 21:42
50

Example creators will continue to earn +5 reputation per-upvote

If a user ends up contributing more than 350 characters to a single example, they will earn +5 reputation per upvote

I disagree with this if it means that an example author and editor will always receive +5 until an example is deleted - it seems that there should be a limit to this if the majority of an example (say 60 or 70%) has been changed by a single person or group of people. My reasoning behind this:

  1. Currently, there are examples which are a good idea to have but end up deleted instead of edited simply because the changes needed are too substantial to warrant the original author getting credit

  2. In computer science, especially with programming languages and computer systems, it is common for the lead author to be the person who contributed most

  3. This seems like it will lead to a FGITW race to create examples (with only minor explanations like those in the os module topic) due to the chance for rep gain - even if only <1% of the example is from the original author

So if a person edits a post (not at the 350 character count but at say the 70% level) would it not be better to shift the authorship to this new author or at least off the old author (or authors in the case of multiple edits being changed by a single edit* or just later edits)?

* Post now deleted as dupe so no chance of meta-effect


Update/Note: Going through the chat log, I found that @JonEricson basically gave an answer on the thought process for SO employees when it came to instances where an example needed completely rewritten, in chat, such that:

If you are rewriting the example, the incentive is to create a new example (and optionally remove the old one).

This answers the question of what to do when it is a single person making a large change (one which deletes 500 characters and adds on only 480). Though I would point out that the coordination for an effort like this would require a "talk page" or some other way of having a cooperative conversation within the example in order to delete and then recreate - particularly in topics that are at the example limit.

Also, the fact that it is optional to delete the old example is part of the point - what if the premise was correct but needed a lot of work? Then an edit, to me, would make more sense.

Further, it does not address the problem of multiple edits changing or removing a large percentage of the Original Author's example. Nor the need to remove or shift authorship when it gets to this point (with a suggestion of using a diff ratio since suggestions are required to be actionable) so that the OP just gets no points if there is less then 350 of his own characters left or just the standard +1 or +2 as a substantial contributor if there are.

5
  • 24
    Currently, if I understood it correctly, "Changes that remove more characters than they introduce will never be considered substantive" … you might rewrite the whole text but not be rewarded at all, except if you make the example even bigger by 350 chars. Ideally, docs become more concise and helpful at the same time when possible. Especially, later on when curating the docs (rather than mainly adding), many significant contributions will not be rewarded at all, I fear.
    – bwoebi
    Commented Aug 30, 2016 at 8:55
  • 1
    @bwoebi Maybe it should better go both ways. Changes that either remove or add more than 20 characters must be substantive and below they might be. Commented Aug 30, 2016 at 9:27
  • 1
    @bwoebi That's a good point, my first review or edit to a draft is usually more about deleting then adding information and I could (and have) see this happening in SOD Commented Aug 30, 2016 at 11:49
  • I do share your concerns. But I think a scheme that accounts for how much content was removed from an example and removes some or all of the credit is functionally the same as allowing editors to remove duplicate examples while creating their own. The goal of reputation is to be "vaguely right" about who gets credit and how much. We think the proposed system is a lot closer to being right without getting so complicated nobody can predict what they might earn from an upvote. It's certainly worth trying.
    – Jon Ericson Staff
    Commented Sep 1, 2016 at 1:07
  • 5
    @JonEricson the proposal is better then what we had but its weaknesses also need to be pointed out. If only so that later down the line this can be brought back up as a feature request - if needed once many of the other major concerns have been addressed. Not trying to beat up on you guys just your model - cause that is the only way to ensure it is true (or valid or actionable or what-have-you) Commented Sep 1, 2016 at 3:34
41

I like the updates, it looks like progress.

One aspect that I did not see here was any reference to breaking examples apart. I know that you can move a single example. However, certain examples that would benefit from being broken apart (i.e. java array) cannot at present because of the issue with author ownership of the content (for example, if one user were to move the example and then copy paste it into several others they would become the sole owner of every copy pasted example).

Was the structured reputation change intended to solve this problem by allowing it to remain with a lesser overall impact?

If the outlook for large examples with large authorship is that the current reputation scaling removes any negatives overall, does that mean that the Java Arrays example is actually the type of content now being encouraged?

If that is not the outlook, what type of plan is being considered to break apart authorship of examples which need to be moved to multiple places?

27

Changes that remove more characters than they introduce will never be considered substantive

While I can see why it makes sense to only count additions as substantial, deletions may just as useful maybe even more useful. From my experience I have seen many examples that just grow over time as people add more or less related stuff to them (possibly just to get their slice of the rep stream on a popular example). To keep examples focused on just one thing it's important to clean them up from time to time and remove all the unnecessary stuff that's been added. Shouldn't this count as substantial as well?

As documentation matures and most of the topics already exist and have appropriate examples doesn't this "only additions get rewarded" rule penalize the people how are actually putting an effort into maintaining the existing topics while still allowing other people to tap into the rep stream even if it's just +1 instead of +5? I fear that this might lead to examples always growing over time since additions are the only way to be actually rewarded for an edit - regardless of if the edit is useful or not.

At least part of the rep system should be geared towards maintaining topics and in that sense ignoring deletions seems kind of weird. While I am the first to admit that I don't know a real way this could be fixed without also rewarding possibly destructive behaviour I feel that it's still important to find a solution to this. Once a topic has been appropriately covered people can still continue to edit it and somebody in one form or another has to maintain these topics by for example removing or fixing the odd crap edit that makes it through review once in a while. Over time this work accumulates and these people might eventually be doing the bulk of the work to keep the content at high quality.

Example creators will continue to earn +5 reputation per upvote

Should the original creator of an example really always receive rep from it? Does that at all make sense for documentation? Up until this point I have never considered any example to be owned by a single person - like an answer in Q&A would be - and the way documentation works definitely doesn't promote that idea. I have seen many examples that originally were quite terrible, but then have been improved and cleaned up by the collective efforts of a bunch of other people. And even if the original example was great introducing the concept of ownership - which this reward implicitly does - at least in my opinion doesn't make any sense at all. If basically nothing of the original example still exists - besides what the example is about - I see no reason to reward the original editor.

Upvotes should reward the people who have made the current version of the example what it is - not the people whose contribution has long since been removed. Does the change to the documentation rep system take that into account at all? Or will someone forever receive their +1 rep for each upvote even if their contribution is long gone?

In any case I am very happy with all the changes to the rep system. Definitely a step in the right direction!

3
  • 1
    While I fully agree; just to add to the second last paragraph: the contribution is perhaps long gone, but maybe the initial contributions compelled people to even replace it by the content it currently has. So, maybe the original contributions aren't visible anymore, but have had a lot of influence on the current content. Trivial "rules" we can implement in code just cannot be smart enough to distinguish whether a contribution is or isn't actually helpful in the long term.
    – bwoebi
    Commented Aug 31, 2016 at 22:53
  • 1
    @bwoebi Agreed. I guess it is just that the original contributor continues to get +5 that throws me off. it just seems weird to me that everybody else get +5 only after contributing at least 350 characters, but the first person get +5 even if the post is really short. Should the rep system really make a distinction between the first or the tenth contributor? As you say rules in software can hardly pinpoint which edit actually added the most value. Commented Aug 31, 2016 at 22:59
  • At the very least, the primordial example contribution defined the point the example is about - finding the right topics/points to show (assuming the example is not rejected/immediately deleted, in which case it's not relevant anyway) is also some worthy contribution. Sure, you could call that a FGITW problem, but … uh … Providing some impulse to improve something, i.e. providing the basic basis is worth something in most cases.
    – bwoebi
    Commented Sep 1, 2016 at 0:49
4

There are now two rules in place to keep the number of examples on a topic in check.

  • Users with less than 2,000 reputation cannot propose creating a 7th or greater example

  • No users can propose creating a 13th or greater example

I generally agree with this, but with this the Keywords-topic will get into problems. If an update to .NET adds new keywords, nobody will be able to add it (the topic currently has 60+ examples).

Of course it is debatable if a topic like this should exist, since there are official sources which describe all keywords. On the other hand, it provides a way to show caveats or tricks regarding this keywords, which don't really have a place anywhere else. And this doesn't only concern the C# topic. I proposed the Keywords topic for Delphi, too (but it got rejected), and it could be useful for other tags too (at least in my opinion).

That's why I'd like to request an option, e.g. for gold badge owners or mods, to release the example count restriction on topics. Alternatively, adding a 13th or higher example could get a message telling the user the change needs additional approvement by high rep users.

31
  • 10
    I think the whole point of limiting the number of examples in a topic is to prevent people from creating broad, unfocused topics like this. The existing ones are grandfathered in, but the system really wants you to break them up into more sensible pieces.
    – Cody Gray Mod
    Commented Aug 30, 2016 at 13:57
  • 4
    @CodyGray but how do you break Keywords in "more sensible pieces"? As I said, most of the valuable information there doesn't really have a place somewhere else - at least nowhere, where you'd expect it. I do understand the aim of these restrictions, but I don't think they should be inevitable Commented Aug 30, 2016 at 13:59
  • 3
    Maybe categorize similar keywords into (combined) examples?
    – Cerbrus
    Commented Aug 30, 2016 at 14:11
  • 2
    @Cerbrus This is no different to many examples, just with worse structuring. This just tries to avoid the restriction of the example count Commented Aug 30, 2016 at 14:17
  • 15
    @FlorianKoch: "but how do you break Keywords in "more sensible pieces"?" You don't have a topic about keywords. It's that simple. Presenting a list of keywords, or any other arbitrary list of stuff, is not a thing that is topic-worthy. You flush the whole thing. Commented Aug 30, 2016 at 14:39
  • 5
    @FlorianKoch: No, it's still an arbitrary list of stuff. The only thing each example has in common is that they show off a keyword. That's not a useful categorization of examples. If a user needs to find out how a keyword works in a language, Google help them. Docs.SO doesn't need to replicate that, and Docs.SO is not good at replicating it. Commented Aug 30, 2016 at 14:45
  • 9
    @FlorianKoch: Why do they have to go anywhere? If all an example demonstrates is the syntax for using a language feature, then we don't need that example. An example ought to demonstrate something practical that you can do. And if it has a practical purpose, then the example can be moved to a topic about that particular purpose. Commented Aug 30, 2016 at 14:49
  • 1
    @FlorianKoch: You're not really understanding my point. If an example is just an abstract demonstration of how a keyword's syntax works, it should be removed, not transferred to some random topic. I don't see any examples in that Keywords topic that need to be saved. Being "useful" is not enough. On SO, we don't allow overly broad questions even though they can and have produced useful information. So to on Docs.SO we shouldn't allow overly broad topics, even if they produce useful information. Commented Aug 30, 2016 at 14:54
  • 7
    @FlorianKoch Why should it be preserved? It's just a demonstration of how the keyword works. There's nothing you would learn there that you wouldn't on MSDN. Commented Aug 30, 2016 at 15:00
  • 3
    It wouldn't be the first time legacy content that didn't fit on SO any more got deleted. And it's not like deletion makes in unavailable -- links to it will still work if anyone wants to migrate the content somewhere more appropriate. We're in a beta and so shouldn't be surprised if on-topicness changes.
    – Frank
    Commented Aug 30, 2016 at 15:20
  • 2
    Hmm... honestly, I think an ideal solution to this type of problem would be either a topic hierarchy (where a parent topic can have child topics, which are linked to from the parent topic and link back to it; child topics are listed on the tag's main index as being part of the parent topics) or nested topics (where a parent topic can have a child topic inlined as a single example; nested topics aren't shown on the tag's main index). Either of these solutions would help to both decrease the number of examples on the parent topic, and logically group sub-examples things for easy access. Commented Aug 31, 2016 at 1:08
  • 2
    @JustinTime That looks long enough to be its own answer or a new question. My opinion/approach: Make links both ways, and lobby for UI that lists backlinks within Docs automatically. chat.stackoverflow.com/transcript/117558?m=32193436#32193436 I don't think hierarchy/structure has a real shot at happening for the reasons given here: meta.stackoverflow.com/questions/303865/…
    – Frank
    Commented Aug 31, 2016 at 2:05
  • 2
    Git Branching stackoverflow.com/documentation/git/415/… has hit the 13 limit and it's a good example of a really complex topic that shouldn't be broken up into separate topics and can't have fewer examples. Should this (can this) be broken up and if that's a bad idea then should we have flexible example limit caps?
    – Boggin
    Commented Aug 31, 2016 at 12:50
  • 6
    @Boggin: I see no difference between that Git page and a FAQ page on Git branching. It's just as highly unorganized as a FAQ (though moreso since Docs.SO's voting is negatively useful for such things). If you have a problem, odds are good that the solution will be buried under layers of stuff you don't care about, just like a FAQ. And so forth. There's plenty of help documentation on Git's commands for playing with branches. I don't see the point in duplicating that here in Docs.SO. Commented Aug 31, 2016 at 14:02
  • 5
    @Boggin: You can't really separate Docs.SO from the "documentation" hosted on it. There are lots of FAQ-style topics on Docs.SO. This is the fault of the powers-that-be not giving us a good idea of what a "topic" should be, thus leading to people doing whatever they think is appropriate. That's the fault of Docs.SO's structure and the guidance of its makers. Commented Sep 1, 2016 at 14:56
0

Okay, three things:

  1. This is a suggestion that I posted on the last documentation update, but it hasn't gotten much attention, so:

Maybe this is just me, but I think the number of people to approve an edit is going to be a problem.

Where it makes sense

On the more busy/commonly used documentation pages this makes sense. In fact, I'd even say increase the number of people necessary to approve an edit. The better the documentation has to be to be posted, the better. However...

Where it does not make sense

On the less busy/commonly used documentation pages, there is less traffic, therefore making it difficult to allow edits to get approved, especially as people are trying to create whole topics and establish pages that will be the foundation of that documentation section. This makes the whole experience more difficult for those who are trying to write the documentation and slows down the whole process.

My suggestions

In the humble opinion of this low-rep user, I think a few things should happen:

  1. There should be a review queue connected to the main site. Not only would this speed up edits, it gets more users on the main site involved with or aware of the documentation project.
  2. The number of users it takes to pass an edit should increase as a documentation section gets either a. more busy, or b. more "full" - as in, more pages.
  1. One thing that I think would be really helpful is a button you can use to automatically split up examples. You should be able to edit the example body and title, the overall new topic it should be moved into (with an option to move it to an already existing topic), and it should "delete" the previous location of the example, if that makes sense. With the limits on examples, I think this would be incredibly helpful.

  2. The final suggestion (okay, this is more a discussion starter, but) is this: do we really want to the rep for good documentation to be less then the rep for good answers to questions? I think it should be 10 rep for upvotes for the original poster and the editors get rep as described.

    To go more into this, I think that saying other people can significantly improve documentation is true, but not fair to the original poster. What if it is originally very good? Documentation should operate off of similar principles as those of the main site. If you were able to flag examples as very low quality or for deletion, and then write your own example to replace it, that would be clearer than fixing a terrible example or even a mediocre one. The other point of view is like saying that one should edit a terrible answer to make it wonderful instead of posting your own. (Maybe an "obsolete" flag should be added so when a better example comes up, the old one can be deleted?) Edits have their place, but at some point it is better to post your own answer.

    Also in this vein, number of characters is, I think, a subjective way to do it. I get edits will be reviewed, but there is always the possibility of junk somehow getting in if it looks good enough. Besides, good edits could add images, or delete unnecessary bits, or split up an example, and this is not recognized by the current system. Jeffrey brought up a good point in the comments; that'd be an interesting way to do it, but it might also have similar problems. I do not have a good suggestion for a replacement, but I'm bringing these up as things to consider.

I'd be interested to see what people think of this.

7
  • 1
    Re "the rep for good documentation": How should a computer decide good from bad? Are you proposing to make upvotes worth more once some threshold has accumulated (say, 10 rep once an example reaches +10)? Commented Sep 5, 2016 at 18:21
  • @JeffreyBosboom, I have edited my answer for clarification.
    – auden
    Commented Sep 5, 2016 at 22:18
  • I sort of think that each of these should be its own question... better place to start a discussion than in the comments on an answer to an old question. Also, if the (mostly unrelated?) suggestions are split, we can reasonably vote on them independently.
    – Frank
    Commented Sep 6, 2016 at 15:08
  • 3
    Better tools for splitting up topics and moving examples are in the early discovery phase and you should expect updates some time in the near future. Also, a global documentation review queue is in the works and will be rolling soon.
    – Kurtis Beavers Staff
    Commented Sep 6, 2016 at 19:00
  • @Frank, okay, would you suggest I post each of the suggestions independently as their own new meta question? Or how exactly do you mean?
    – auden
    Commented Sep 6, 2016 at 20:27
  • Yeah, that's what I meant. Of course, you'd want to check if the idea has been brought up already (like the Docs review queue and, I think, splitting examples) and prepare for a tough audience. While the audience is tough, you'll get more feedback and discussion by posting that way, I'm guessing.
    – Frank
    Commented Sep 6, 2016 at 20:45
  • 1
    @Frank, okay, thank you, I will be posting the first (discussing reputation gains) soon!
    – auden
    Commented Sep 6, 2016 at 20:46

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