267

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.

49
  • 93
    Very glad to hear about the increased bar for getting edits approved. I'd still like to see a higher bar for having the opportunity to review in the first place, though. 100/200 rep is just too low.
    – TylerH
    Commented Aug 4, 2016 at 19:32
  • 11
    I'm hoping that that the feedback from meta.stackoverflow.com/questions/329528/… is heavily taken into consideration and retroactively applied. With the devaluation of what reputation represents, your "plan" will surely dictate if people contribute to SO going forward.
    – KreepN
    Commented Aug 4, 2016 at 19:46
  • 26
    So when is the "approve and reject edits with gold badge" and "votes count more with more rep" changes going to roll out to Q&A? :-) Seriously, that makes maintaining the docs a lot more convenient for me, thanks.
    – davidism
    Commented Aug 4, 2016 at 19:55
  • 9
    Is example limits something which must be hard-enforced? It definitely should be resolved… but hard-cap? I think it rather should be something like an (un-dissmissable) flag by Community on the topic. That way one can still contribute something, but it gives also a bit time for content to be aggregated first before being split up. Also, soft limit is (I know it can be tweaked, just suggesting) probably too low. PHP Types has one example per type. There are alone like 7 types. Bam, limit immediately reached. That 20 examples are too much, is understandable, 10 examples are not quite too much…
    – bwoebi
    Commented Aug 4, 2016 at 20:09
  • 10
    Nice thing about having a beta is we can test out all these crazy ideas that folks have been asking for for years without breaking stuff for thousands of people, @davidism.
    – Shog9
    Commented Aug 4, 2016 at 20:42
  • 30
    @Shog9 oh thank goodness! I was starting to worry that you guys were serious about Docs being for real. World makes sense again :-)
    – Rob Grant
    Commented Aug 4, 2016 at 20:47
  • 75
    Seriously? It would have taken me 5 minutes on a slow day to figure out that the reputation system for documentation is unbalanced, unfair and incompatible with SO (a.k.a. broken). I am convinced you have smart people working at SO, so I have a hard time believing it took you weeks to start suspecting as much. Looks more like you wanted to create a gold rush to push your new product disregarding collateral damage. It's the oldest dirty trick in the West. It should at least be a separate reputation system so the reputation of innocent bystanders is not devalued. Commented Aug 4, 2016 at 23:11
  • 11
    @Erwin, let's give the staff the benefit of the doubt (regardless of our personal beliefs:P). I'm pretty sure they saw that the reputation system is off; the hard part is rehashing it in a way that will fix it for good. Also, having a separate rep system is one among many suggestions that they received. Commented Aug 4, 2016 at 23:54
  • 25
    @knu any changes to the rep system will be accompanied by a rep recalc. We've already done one since launch. Commented Aug 5, 2016 at 1:10
  • 31
    @AndrasDeak: "the hard part is rehashing it in a way that will fix it for good" The problem is not that it's hard. The problem is that they're willing to leave the problem there, letting it fester until they find a way to solve it. Right now, there are quite a few people who have full Q&A edit powers because of Docs.SO. Very soon, there will be at least one person on SO who has close-voting powers solely because of Docs.SO's ridiculous rep gain. This is not a tenable situation, and every day it continues, it becomes worse. "Wait and see" is not something I want to see happen to Q&A. Commented Aug 5, 2016 at 2:49
  • 26
    Suppose the SO documentation for Java Generics becomes one of the top search engine results for "java generics". Yet, the topic starts with a "focus" of "This topic demonstrates how to use generic types in class and method declarations…" Readers still may not even know what generics are. Should the examples be structured so that "what is this?" is immediately answered by the highest-voted example? Should the section named "focus" actually provide a definition? Or should it link to external documentation? None of these seems to fit the purpose of examples or the "focus" section.
    – jtbandes
    Commented Aug 5, 2016 at 4:21
  • 9
    "Too much reputation awarded for contributions to single popular examples" It's easy to say it afterwards, but I really wonder what you were expecting how often popular examples would be voted on. Surely a hundred upvotes for at least 10 distinct editors resulting in thousands of rep was not unreasonable to expect even way before the launch. Well, you see the problem now and will surely find a way to fix it. Commented Aug 5, 2016 at 12:06
  • 15
    There are too many examples per topic because there is a need to make things organized. Some additional categorization of topics (maybe via tags) could help to alleviate this problem. For instance Android documentation has 146 topics and it is already unsearchable mess. And some topics have 20 or so examples. Splitting those would make even more mess. Other less popular tags will become just as messy as new content will be added.
    – Dalija Prasnikar Mod
    Commented Aug 5, 2016 at 12:42
  • 14
    Why would I want to cite Stack Overflow documentation? I cite official documentation because it is an authority - I don't expect readers of my answer to blindly trust me, so I try to evidence all my claims, sometimes by quotes from official documentation or the pronouncements of a language's or library's own developers. Stack Overflow Documentation simply doesn't carry that authority - there's no reason somebody reading my answer would think Documentation is in any way more trustworthy than I am, so why would I use it to back me up?
    – Mark Amery
    Commented Aug 10, 2016 at 10:02
  • 13
    Any news on when the next update will come? Closing in on two weeks now.
    – TylerH
    Commented Aug 15, 2016 at 15:46

16 Answers 16

169

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.

OK fine, but... there doesn't seem to be any examination of why some topics are getting lots of examples. Yes, I'm sure the rep issue is a problem. But that's not the main problem.

The primary reason that topics attract lots of examples is that we have no real idea what a topic is. Even 2 weeks after launch, we don't really know how big or how small a topic ought to be. Is "arrays" something that should even be a topic? By all rights, such a topic could contain dozens of examples, all without repeating each other. Is that too big of a thing? How small should a topic be then? How do you even know the size of a topic when you propose it?

Q&A maintains the scope of answers in a question by limiting the scope of the question itself. We've learned that only focused questions limit the scope of their answers, and we've come to understand what a focused question looks like.

What does a focused topic look like?

The problem with such a nebulous concept long-term is really simple. With Q&A, questions eventually go away. They fall off the front page, out of sight and mostly out of mind. A couple of broad questions, even if they're not closed, don't cause too much of a problem long-term.

Documentation doesn't go away; that's kinda the point. If a topic is broad, the only way to fix that is to move all of its examples to less broad topics and destroy the original. That requires conceiving of a number of topics that aren't as broad, which again requires understanding how broad a topic should be.

And of course, if you start removing examples from topics and so forth, you create pseudo-dead links. Oh sure, the link will link back to the old version of the example. But if the example has been moved and improved... the old link doesn't see it.

We've got topics like "keywords" in several languages, which are intended to have a separate example for every keyword in the language. Someone created such a topic because they thought it was a valid topic to have. Do we start deconstructing that work now?

When do we get to the point where we actually define what a topic is?

21
  • 3
    "But if the example has been moved and improved... the old link doesn't see it." This seems like it would be easily fixable. I say "easy" in a theoretical sense, not necessarily a technical one, of course. What I mean is, when you move a topic, there should be a way to track where it was moved to. Then you'd simply redirect to the new location for that documentation, rather than spilling you to a "content deleted; click here to see it anyway" page. We already do this for duplicates and merged questions; it only makes sense to do it for Documentation, too.
    – Cody Gray Mod
    Commented Aug 5, 2016 at 4:46
  • 6
    As far as defining what a topic is, I completely agree. But I think the stumbling block is that it is not necessarily going to be the same definition for all tags. Not that some broad guidance couldn't be written, which so far has been conspicuously lacking, but even then, it risks being so broad as to not be practically useful in helping people who are actually setting out to write the topics and examples. As others have argued in the past, we're probably going to have to hammer this out in a lot of specific cases, which will require an organized way to discuss it and reach consensus.
    – Cody Gray Mod
    Commented Aug 5, 2016 at 4:48
  • 23
    @CodyGray: "But I think the stumbling block is that it is not necessarily going to be the same definition for all tags." It's hard enough teaching people what is and is not a good question on Stack Overflow. Now, we're expected to have the definition of good vs. bad topics vary depending on what tag you're in? If there can't be a single, consistent definition across all tags, then the system is dysfunctional. Commented Aug 5, 2016 at 4:53
  • 2
    "What does a focused topic look like?" A topic that can be handled in a few examples?? Commented Aug 5, 2016 at 8:11
  • 22
    Hey, we've been clearly told what topics and examples should be: whatever the community decides them to be:P Commented Aug 5, 2016 at 11:30
  • 3
    A topic is what we make the topic to be. I do not think there is one true definition of topic. The topic is a flexible framework we can use the way it fits the needs. Sometimes it's a collection of examples, sometimes of one-example-per-thing of a specific subject (e.g. keywords, types, ...) and sometimes a generic introduction of large topics (i.e. "what is it", "how can I create it", "how can I inspect it", "how can I manipulate it" … the latter three with links to respective topics) … and it def. should not be a trashbin for everything related to a big super-topic (like in the Arrays case).
    – bwoebi
    Commented Aug 5, 2016 at 11:36
  • 10
    @bwoebi For such a flexible framework it has a surprisingly fixed structure, being listed in a single long list on the dashboard and having the example, parameters, remarks sections. If it can be almost anything, maybe we should better work with a wiki like structure where we define our own sections? Commented Aug 5, 2016 at 12:09
  • 57
    @bwoebi: "Well, it's basically wiki-like" Except in all of the ways where a Wiki would be useful. Wikis have arbitrary page structure; they're not boxed into "examples" and so forth. Wiki's have tables of contents for multi-section pages. Wikis have ways for users to decide what comes first, second, third, etc. Wikis have ways for users to set up redirects/link aliases. Wikis have ways of sharing content between pages. And so on. The only way in which Docs.SO acts like a Wiki is that it can be edited by anyone. Commented Aug 5, 2016 at 14:26
  • 24
    What good is an example cap when there is not character cap? People will just make longer examples, stuffing multiple examples into one.
    – Gordon
    Commented Aug 5, 2016 at 17:50
  • 2
    @NicolBolas Yep, already. I can't be sure it's why they're doing it, but it's happening. Example: stackoverflow.com/documentation/proposed/changes/78046 Commented Aug 5, 2016 at 17:59
  • 4
    There needs to be a tree-view of tags and examples or something. Examples might be relevant to multiple topics, and some topics may be "sub-topics" of others.
    – mpag
    Commented Aug 6, 2016 at 0:07
  • 10
    I think a hierarchial structure is needed.
    – Zaz
    Commented Aug 6, 2016 at 5:59
  • 1
    I think it would be useful to consider the idea of a topic as a guide - currently, documentation on the web has a distinctly inhuman, overtechnical feel. achieving understanding is secondary to cataloging. I believe if you looked at a topic in the context of using examples to guide a user to understanding - then this ultimately will provide a context for defining a clear set of rules. For example: I myself am interested in learning how to use newer ECMA syntax, lambda operators and so forth - and putting such information into a guided 123 I think is the nirvanna of dox
    – WlkrShrpe
    Commented Aug 8, 2016 at 18:50
  • 2
    Given the overall context of software tools, to me the obvious topic for anything is the answer to the question "What problem are you trying to solve?" In fact, I'd like to see a "What problem does this solve" section on every article. For instance: "Git: What problem does rebasing solve? When is this a better solution than merging?"
    – Hack Saw
    Commented Aug 24, 2016 at 0:14
  • 2
    @HackSaw That is a nice necessary condition for a topic. Every topic should solve a problem. But then there may be problems that are just too large to be fit into a topic. They need to be split and categorized somehow. Commented Aug 24, 2016 at 7:55
81

Apart from the discussing about problems with the current reputation system it’s time to reconsider the voting system for the documentation itself in my opinion:

Up-voting content you consider useful and down-voting content you don't consider useful – and displaying it "stack overflow"-style like – is pointless in some way for documentation because examples do not answer a specific problem, but rather provide information which could be helpful for you, but uninteresting for me …

As user @samgak pointed out that "the 'sort by most popular' functionality should be removed from documentation since the only purpose this serves for someone using the documentation is to find the best topics to edit for maximum reputation."

User @Squidward also mentioned in his answer regarding the adaption of our voting system for documentation examples "the longer it goes on like this, the harder it'll be to fix. You can't just reset votes, people will be annoyed. So it's important to fix sorting as soon as possible."

Do you and your team have any further plans to fix this?

13
  • 56
    Another thing is, you downvote a crappy example, the day later it is vastly improved by someone else, and yet it still has your downvote.
    – ken2k
    Commented Aug 5, 2016 at 9:47
  • 3
    @ken2k: that’s a good a point but this also applies to questions and answers – I just want to point out that examples of the docs are different to answers posted in the Q&A and therefore need another voting/sorting system :)
    – elegent
    Commented Aug 5, 2016 at 9:53
  • 41
    Yes it also applies on Q&A, but Q&A are not supposed to be edited by many people like topic/examples are. And when you edit a Q&A, you shouldn't change the meaning of it, while for example/topics, it might be drastically changed. This is another example about why the voting system of Q&A cannot be applied for topic/examples.
    – ken2k
    Commented Aug 5, 2016 at 9:58
  • @ken2k: Absolutely agree with you! Didn’t thought about the fact that examples are more alterable than answers. ;) If it is ok I would include this argument in the question about "adaption of our voting system for documentation examples?"
    – elegent
    Commented Aug 5, 2016 at 10:02
  • 13
    Additionally, this quite enforces that niche topics get less attention than elaborate explanations on very popular and basic topics.
    – bwoebi
    Commented Aug 5, 2016 at 10:47
  • @elegent Sure, feel free to include this comment
    – ken2k
    Commented Aug 5, 2016 at 12:06
  • I don't understand into what you want to change the current voting system? Somehow it makes a bit of sense to me. The most upvoted example is the most helpful for most of the users and therefore also might be very helpful for me. Commented Aug 5, 2016 at 12:12
  • 1
    @Trilarion when you get examples that are basically "new features of version X", I doubt so... remember, the most useful example is the one you have need for.
    – Braiam
    Commented Aug 5, 2016 at 15:10
  • @Braiam Maybe I could mix version and rating (for example by dividing the rating by the square root of the time the example is existing and order by that quantity, or whatever). I have nothing against this. Let's discuss an alternative voting scheme. Commented Aug 5, 2016 at 15:15
  • @Trilarion that sounds too complicated for something that should be straightforward.
    – Braiam
    Commented Aug 5, 2016 at 15:49
  • @Braiam So how do we find out which examples are the more useful ones on average if the number of examples can change at any time, possibly through some sort of voting? Commented Aug 5, 2016 at 21:01
  • @Trilarion I'm not sure what you are getting at? We have in-line versions if we need to.
    – Braiam
    Commented Aug 5, 2016 at 21:03
  • @Braiam Sorry, It's quite late here. I got confused. You're absolutely right in the comment above. There are topics possible where voting on the examples doesn't make much sense and a canonical order of the examples, given by the content creators would be much better. As for the versions, I still need to study that feature more, I largely ignored it so far. Commented Aug 5, 2016 at 21:06
48

Regarding content organization and quality ...

  • Too many examples [...]
  • Examples being edited to be very large [...]

A related problem is too much dodgy content getting through review.

Tweaks to the rep and review mechanisms can help, but part of the problem comes from a lack of consensus within each tag community about what the docs should look like. I think we need per-tag discussions for this, since the right length for an example, the right number of examples, etc. will vary from tag to tag and topic to topic.

An example from the R tag: We should discuss whether we need "data types" as a topic, and if so...

  • what relationship the topic should have with other topics
  • which data types should be included
  • what examples should look like
  • which example should be pinned
  • whether to split up existing examples (like "numeric" into ints and doubles)
  • whether to merge existing examples (like "numeric" with "int64")

Current tools:

  • The planned "focus" section sounds promising for clearing up ambiguity on a per-topic basis, but not for issues that span multiple topics. Also, disagreements over what the focus should be seem likely, and discussions about them shouldn't be buried in comments on edits.

  • Improvement requests presuppose that we've all agreed about how things should be organized. But I could request splitting up some examples, while someone else comes along requesting merges. We have no way of hashing it out nearby the doc itself, since improvement requests cannot be commented on.

  • With chat rooms, it's hard to follow a discussion and find it later; and chat lacks Q&A features that we probably want in such discussions (like comments, voting, and code blocks within a post).

  • People are using the Q&A format here on meta for this already. Wouldn't it be better to have that organized per-tag?

Anyway, I like all the changes so far and how y'all are approaching this.

3
  • 13
    In any case, we shouldn't let things get so large it crashes the page. Which is what I'm running into trying to edit Java's Arrays topic.
    – Laurel
    Commented Aug 4, 2016 at 23:26
  • I think questions on meta are a good way of having this conversation every time a consensus needs to be reached. Are you suggesting adding a link from the tag page to that discussion in a wikipedia-"This article needs additional citations for verification"-style banner? Or adding tags on meta for each documentation tag?
    – Cimbali
    Commented Aug 5, 2016 at 21:05
  • 1
    @Cimbali Thanks for the comment. I am suggesting that something along those lines needs to be set up, yeah. If I had a specific feature request, I would link to it here. I like the mini-metas idea, which should make sense if you've used area 51 much (but might not otherwise): meta.stackoverflow.com/q/329686 For what it's worth, if you think meta is adequate, I think you underestimate the number of discussions we need to have and the extent to which people (including me) are avoiding docs because of how messy it is.
    – Frank
    Commented Aug 5, 2016 at 21:19
24

Review now take 4 "votes" to approve or reject, and how many votes a users approval or rejection counts for is based on their reputation

That's all very nice, but what is going to happen to less popular documentation tags, for example https://stackoverflow.com/documentation/batch-file/topics.

At the moment there are only a handful of people contributing to batch-file.

None of us have 100 rep in that tag but we are still producing high quality content (IMHO).

Now there is nobody active in batch-file (with enough tag rep) to approve any of our changes (there is not one person never mind 4 people).

As a result of these changes I'm going to give up on Documentation and wait for it to be released on SU where I have more than enough rep to contribute in a sensible way.

21
  • Well, you may not have to wait so long as that; this is a beta after all.
    – Frank
    Commented Aug 6, 2016 at 14:48
  • 8
    @Frank All very well. But these changes have prevented a lot of people from contributing to less popular tags. If I didn't have experience in the tag I wouldn't have "sponsored" it in the first place. I feel like I've been "kicked in the teeth". Coming from SU, where I have 56K rep and have answered many batch file questions (there are only 2 bronze batch-file badges (one is mine) and there are no silver/gold tag badges) that make me particularly sad :/ Commented Aug 6, 2016 at 15:03
  • 5
    Fully agree with this answer. Approvals should be allowed to Bronze tag category holders in low traffic tags.
    – sambul35
    Commented Aug 6, 2016 at 15:24
  • @sambul35 Unfortunately I don't have even the bronze tag on Stack Overflow, only on Super User. Thanks for your support :) Commented Aug 6, 2016 at 15:30
  • I suggested in my Answer to sum up rep count earned in the same tag class on various SE sites for the purpose of editing & approving Doc changes.
    – sambul35
    Commented Aug 6, 2016 at 15:34
  • 3
    @sambul35 Unfortunately in the world of SE the same tag on different sites doesn't always have the same meaning. Commented Aug 6, 2016 at 15:41
  • 6
    Wouldn't be very hard to have a rep threshold instead of a badge threshold, though there may very well be a reason for preferring badge that I don't yet understand. If this change were made, a very simple algebra could be created: take all rep in a tag by all users in last x months (6, 24?), the rep threshold is now minimum of [y percent (.1, 1, 10?) of that total or z total rep (1000, 5000, 100000?)]. Recalculate daily, display inside tag wiki. If batch-file only has 1000 rep in the last 6 months, then 10% is 100, and anyone over 100 rep met the threshold.
    – CWilson
    Commented Aug 6, 2016 at 15:48
  • 2
    @CWilson Thanks for your support :) The problem with low traffic tags is not just rep, it is getting 4 people with enough rep - who actually care about the tag - to approve anything. Commented Aug 6, 2016 at 15:51
  • 4
    @DavidPostill number of people "who actually care about the tag" is inherently a different problem, and we may not need those docs. If too few people care about it (this is only beta still, may unfortunately happen to useful tags), then speed in approval of content isn't really a priority. Not saying batch is like that... it could be that the people who care don't get enough questions. Personally, I write a new batch file weekly, and use each of them daily, but I go from my memory of the late 80s early 90s. I don't ask questions, therefore I don't give you and your buddies any rep :)
    – CWilson
    Commented Aug 6, 2016 at 16:04
  • @Frank Namely for that reason suggestions are posted here.
    – sambul35
    Commented Aug 6, 2016 at 16:08
  • 2
    @CWilson Thanks for the comment. IMHO we need the docs - judging by the poor quality/duplicate batch file questions that get asked every day. But that's a different issue ... Commented Aug 6, 2016 at 16:10
  • I think this point will become moot once the review queues are implemented.
    – Braiam
    Commented Aug 7, 2016 at 17:39
  • 1
    Please flesh this out as a feature request. This is a really good suggestion Commented Aug 9, 2016 at 0:10
  • 1
    @DavidPostill I have one from end of last month. Hence my suggestion to just give up. Missing documentation is missing because nobody cared to write it, SO docs suffers the same fundamental problem: it's tied to activity and popularity.
    – null
    Commented Aug 9, 2016 at 17:57
  • 1
    That would explain why the last example I submitted has been in limbo for four days. At first I found this whole idea a little exciting (what does that say about me?) but this really sucks the life out of it. I didn't just pull the topic out of thin air. It's something real that I occasionally need to demonstrate. But why should I spend my valuable time writing something up for nothing when I can just put it on my own blog instead and link to that? Commented Aug 15, 2016 at 13:27
15

"max 13 examples" may have a point, but I'm wondering about a particular case.

"What are the new features in version X of a language", where there are about 50 of them. This is a useful thing to document. A single example per feature (or, in some cases, an example for 2-3 features that work together) is useful.

I guess the solution might be to create a version-specific tag on the main site, then document each new feature (or set of closely tied features) under that version-specific tag as its own topic?

This doesn't seem like the obvious best plan, because the core language tag already has a versioning system. But having the "new features in version X" clumped together is a very useful feature.

14
  • 2
    Yeah, it's not clear if this is an oversight on their part or they just don't think "features of x" is a good topic. And it's not clear because, as Nicol pointed out in the top answer, there has been no guidance on what a topic, as they see it, can or should be. In their defense, at least they've said they from early on that they imagine ~6 examples per topic.
    – Frank
    Commented Aug 5, 2016 at 14:17
  • 4
    ""What are the new features in version X of a language", where there are about 50 of them. This is a useful thing to document." consensus is that we shouldn't have those kind of topics Should we be making documentation topics for new features in a specific language version?
    – Braiam
    Commented Aug 5, 2016 at 14:44
  • 16
    For some reason, people really like creating topics in Documentation that consist of lists of new features in version X of a language. I'm not really sure why, exactly. It is not clear to me how this is useful. I guess it's just something that we couldn't do with Q&A, but Documentation is just anything-goes at this point. I wonder if the system is subtly hinting that this kind of thing doesn't belong?
    – Cody Gray Mod
    Commented Aug 5, 2016 at 14:57
  • 4
    it isn't useful, but, it's easy.
    – Kevin B
    Commented Aug 5, 2016 at 15:01
  • 9
    @CodyGray To someone who knows Java7 and wants to know if they should upgrade to Java8 at whatever cost, how is the list of new features in Java8 not useful information? (Modulo any prejudice against Java) Especially if the list came with examples of each feature in use, so you can learn how to use them? Commented Aug 5, 2016 at 15:03
  • 4
    By that definition it's also useful to have a "jQuery vs PHP" topic. I'm sure there's some missguided dev out there who wants to know the differences.
    – Kevin B
    Commented Aug 5, 2016 at 15:04
  • 1
    @CodyGray I think Shog's argument about "Tips and Tricks" topics should be used here: Rather than throwing them all into a massive, impossible to navigate "new features" topic, if you write such an example try to find or create a topic where it can live comfortably. (I changed "tips" for "new features")
    – Braiam
    Commented Aug 5, 2016 at 15:05
  • 5
    @KevinB That implies that someone who is an expert in Java7 is misguided in wanting to learn Java8 or upgrade, or misguided to want to have documentation describing what happens to code in the upgrade, or even that such a dev is a rare bird and not a common case? I'm puzzled by your analogy. I don't think I'm a misguided dev, and I'd love if someone wrote a list of every new C++17 feature with use examples attached to each. (I spent time building such a list without examples already.) Commented Aug 5, 2016 at 15:13
  • 4
    @Yakk Maybe they'd type "new features in Java 8" into a search engine and find the new JDK 8 features page or this page specifically about Java language features. The latter even has a couple small examples and links to the official Java Tutorials (with more examples) on those topics. I see no reason to duplicate that in SO Docs. Commented Aug 5, 2016 at 15:53
  • 4
    @JeffreyBosboom I type "new features in C++14" and I get incomplete blog posts, some before C++14 was finalized, none with extensive examples. There is one half-decent one, but it is a blog post on a dead site. So you have put forward an argument that "new JDK 8 features", assuming it has solid examples for every single new feature, would duplicate information elsewhere. You have also put forward an argument that it is widely desired and supported in other sources of docmentation. So you are in favor of having such lists here when they are not found elsewhere? Commented Aug 5, 2016 at 16:04
  • 5
    @Yakk: Why would someone want a list of cardboard examples of random features for a language version? If examples are going to mean something, then they should be able to do something useful. And a random example of a generic lambda is meaningless. What is meaningful is using a generic lambda to do something. Examples should focus on doing something, not showing off features. Commented Aug 6, 2016 at 3:23
  • 4
    To expand on what Nicol said, it is unlikely I'm going to invest time and energy in upgrading my tooling and knowledge just because I see the new version has some neat looking features on a showcase list. What's really going to persuade me to update (barring some kind of show-stopper bug) is seeing a practical demonstration of something I want to do now being made possible or being made significantly easier. Lambdas, for example, sound cool in abstract, but are not a particularly compelling reason to update unless I see how they make my life easier in a concrete fashion.
    – Cody Gray Mod
    Commented Aug 6, 2016 at 13:52
  • @codygray I presume readers of documentation are capable of extrapolation, not just copying the example with variation. I can see a how a lambda works, and look at my code where there are (for example) function objects I wrote manually, and work out from a simple example that I could replace said objects with a lambda. Now, this is likely to mostly expose first-order effects: taking existing code and improving it, as opposed to writing different kinds of code. As an example, C++17 has a std filesystem library. Even a cursory description of what it does, is useful information. Commented Aug 6, 2016 at 14:35
  • @Yakk The information is already available in release notes. Repeating it here is just an error-prone waste of time. I would never look anywhere but the release notes for information of this kind, and if I encountered it here I would view it with grave suspicion. And I can hardly remember an occasion on which I actually needed that kind of information.
    – user207421
    Commented Aug 29, 2016 at 1:05
11

Users with a silver or gold tag badge (from Q&A) will skip review when they make an edit to that tag's documentation

Doesn't appear to work for me. I just made an edit to a piece of documentation, which I have the gold badge for, yet it created a review which is Awaiting Approval: https://stackoverflow.com/documentation/proposed/changes/77556.

4
  • I can't see what tags were present just from the link, but you do have to have the gold/silver badge for every tag on the documentation - could be why.
    – Jeutnarg
    Commented Aug 5, 2016 at 15:39
  • 3
    @jeut I don't understand your comment. How would there be more than one tag present "on the documentation"? Documentation is for a single tag, in this case, [jquery]. (Also, where did you get the idea that you need to have a tag badge for each tag? Tag badge holder privileges don't work that way for Q&A; why should they work that way for Documentation?)
    – Cody Gray Mod
    Commented Aug 6, 2016 at 13:54
  • 1
    @CodyGray Doesn't apply to the edit linked in this answer, but Kevin Montrose explained the multiple tags thing in the question: "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" Commented Aug 7, 2016 at 1:22
  • ^^ that's what I was referencing
    – Jeutnarg
    Commented Aug 7, 2016 at 18:34
9

Other than the conceptual critic that Nicol points in his answer, I have my reservations about the planned "review queue". Everyone on meta.SO knows the robo-reviewer problem.

Yes, I know that now the approval is a weighed-vote like system, where you need 4 votes, and higher reputation means that your votes weight more, yet we've found that 3 2k users are more than happy to approve anything, I doubt that finding 4 100 rep users is more difficult.

I propose a modification of another FR of mine, where we need two clicks to actually review anything, the first is to get into /review/proposed-changes and the second is to select the filter. The objective is that reviewers don't get a mixed bag of stuff to review, like a change in python, then jsoup, then vim, etc. Optimize the reviewer view for the tag they are most likely to do an informed review and for what is most loved and sweet (aka, waffles and unicorns), make the skip button very prominent.

8

Review now take 4 "votes" to approve or reject, and how many votes a users approval or rejection counts for is based on their reputation

Are these votes allowed only to Silver or Gold tag badge holders in a relevant tag category? Of course it makes sense to show competence in the subject tag if you are allowed to vote on others proposals, with some caveats... Would it make sense to make this criteria more flexible depending on the tag popularity? For some C++ or Javascript related tags, there will always be plenty of gold and silver reviewers.

For other low traffic tags like Batch the "Edit without approval" and "Approve" threshold may need to be lowered to Bronze, otherwise the review queue won't move. Respectively, if "Edit without approval" threshold on low traffic tags is lowered to Bronze tag badge, then the Bronze tag badge should count as 2 votes in the review queue.

Another issue is counting rep earned on other sites like Super User. If a user has high rep count in that broader tag class on another Stack Exchange site, it makes sense to sum up all relevant rep on several sites when allowing to approve edits in Stack Overflow Documentation. The definition of tag class may include a group of tags users often chose together when posting questions. A tag class would include the main tag that defines the class, and child tags frequently mentioned jointly with the main tag. Tag class grouping may be a subject to Tag Queue and vote approval by experts in that tag.

Improving reputation awarded for Documentation is the good reason to look again at reputation awarded for other activities like answering questions. It may benefit from some differentiation too. Look at this answer for example. It gave the author 3000+ rep points for merely copy-paste of a Help document section easily found by Google search. No effort in writing and debugging code, no personal experience or knowledge shared. Yet the empty answer delivered the author a host of top privileges, while demonstrating no skills in anything other than a basic Google search that was rather expected from the asker.

Now look at this answer, which delivered 4000+ rep to its author - almost the entire his rep and therefore the entirety of his (undue) privileges. The answer doesn't seem to make any sense. First, as the above Help copy-paste shown, a number of processing symbols can be used to post several commands on the same line. Second, posting a group of commands on the same line often totally alters their output, and may require enabling extra features like DelayedExpansion etc, or won't work at all, so its command specific. Thus, the above answer is grossly deficient to the point of requiring its delete. Yet it gave the author absurd rep count, despite its obvious he has no competence in the tag.

The above 2 examples show, primitive answers are more easily understood and readily upvoted by larger number of users regardless of their quality, since most (at least novice) users simply don't have qualifications to assess the answer quality, and rather driven by "So simple", "Like it" and "Me too" crowd instincts. Therefore, the rules need to change. Once ANY answer reaches a certain upvote count threshold like 10 times, the answer must be auto added to Answer Queue and voted on by the tag experts similar to a Doc Example to approve upvote quota increase on that answer, or edit it with further upvote rep assigned to the editor or shared proportionally to contribution, or delete.

Otherwise, current upvote and rep gain practice on answers severely compromises Stack Exchange in many cases as the professional competence portal. Note, simply editing or flagging such answers is not enough, as the editor competence is unknown either, and the answer doesn't seem to grossly violate the rules, so no mod would delete such highly upvoted answer if flagged. In addition, a completely re-written by an editor answer would still deliver undue rep to the original author. Only Answer Queue can adequately address such popularity contest of trash answers.

6

Attempting to eliminate:

Examples being edited to be very large

and

Too many edits are considered substantive when they are not really

May work against themselves. For example the automated system we currently have across SO to check for substantiveness is meeting a minimum character count.

In the case where an correct example is incorrect by some small detail such as a missing ; or a variable declared with an incorrect type, etc, then an edit to correct this may have too few characters to be deemed substantive. Which would lead to people adding more to an example than is strictly needed simply to correct a minor detail.

I have no solution to this atm other than to note that the more advanced contributors are currently doing a fairly good job of proposing edits or reviews that solve these problems - But that as SOD grows, relying on this will likely not be enough.

1
  • My solution. Everything that survives the evolution of many edits is substantial. If you change a single character that changed the code from non-working to working it will stay in for sure. So in the final version you will have a percentage of the authorship and given that not every line is equally important even a higher percentage of impact (which of course we cannot really measure accurately with the unicorn points). Commented Aug 24, 2016 at 8:00
6

I think a hard limit of 13 examples is a bit low. Take .NET's Enumerable class for an example. There are dozens of methods to be documented, and that's before you consider all of the overloads. Yet, having a single topic for this class makes a lot of sense, doesn't it?

Just my $0.02, for whatever it's worth.

0
4

Not sure if this the right place to ask but ... are there any thoughts on the fact that tons of topics are being opened under language tags instead of api/library tags?

I'm only asking because you didn't bring it up. I see "Java" was changed to "Java Language" and "JavaScript" to "JavaScript Language" and "C#" to "C# Language" etc... which I guess was a hope to get people to stop posting API/Library docs under those but so far no action has been taking to remove the existing API/Library docs to the correct tags nor is there a way for editors to do it.

Is that in the works or have you come to some other decision about it? (or maybe I missed it in which case sorry for bringing it up here)

Just to be clear I'm really hoping for an official answer on this topic

I need to know how to proceed. I can start adding library example to every language tag or I can add them to library tags or both.

I don't want to waste my time if they're all going to be deleted if I put them under language tags. I also don't want to waste my time putting them under the library tags if the current momentum of putting them under language tags means again I'd be wasting my time since if the majority of library docs are under each language tag then users are going to ignore examples under the library tags.

1
3

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.

Is it reasonable to create a dedicated tag to avoid this issue?

For example the gradle topic in Android tag has a lot of examples.
Since it is a "big" topic it is reasonable to use the dedicated android-gradle tag to create more subtopics with exhaustive examples.

Hovewer it not currently available a feature to move the example between tags, but only between topics of the same tag. Since it is not possible to do it, I don't know if it is a good practice.

4
  • 1
    I've come across similar problems within the C tag where new contributors wish to add documentation for GCC because that is how they compile C. But GCC, like gradle, is just a tool - it is not the language. While I agree that this is a slightly more nebulous idea for android that is not a specific language, the fact is that unlike the Android IDE, gradle is simply another tool that android programmers can chose to, or not to use - the deciding factor eing that gradle can be used with other, non-android, systems. So it should def be its own tag - maybe with some topics on android related use.
    – Toby
    Commented Aug 6, 2016 at 12:31
  • 1
    So yes the move between tag is really required! :)
    – Toby
    Commented Aug 6, 2016 at 12:32
  • This discussion about libraries about might be helpful: meta.stackoverflow.com/q/329707 @Toby I don't think it matters whether a tool is nested under another or not. If it's big enough to fill out its own docs, it is enough.
    – Frank
    Commented Aug 6, 2016 at 14:46
  • 3
    We also need to figure out how to ensure people don't re-create topics under Android if all examples in a topic are moved. As soon as the main Android tag doesn't have a Gradle topic for example, people will be racing to re-create it every hour, every day.... It will be a massive moderation effort to make sure it all stays clean, if not implemented correctly.... Commented Aug 6, 2016 at 16:26
2

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.

Again, these are just suggestions, and I understand why these boundaries were set, but I believe they should be modified.

Thanks!

0

I feel like everybody is trying to fill documentation with good content, which is of course great, and that the main obstacle is that we're slowly converging towards a set of rules of how documentation should be structured.

The two most upvoted answers here literally deal with what the scope of a topic should be, and what the tools are to agree on such consensuses.

And of course it's frustrating right now to not know what the rules exactly are, especially with the gamification that reputation brings in. We need more rules than a normal wiki (which is the model for documentation) because of this.

The rules will end up being defined, with time, but mostly through usage. And that's why I would like to stress again that it's not only important to improve the system for people who write documentation, but also for people who want to use it. Only that way will we collectively gain the experience needed to know what is good documentation -- and what isn't -- and thus how to best structure it.

14
  • 1
    Regarding search (your link), SO staff have said every time that they won't put much energy towards it because they can piggyback on real search engines (like google) and expect most visitors to arrive that way. Internal search is pretty much just for us editors, not visitors.
    – Frank
    Commented Aug 5, 2016 at 21:27
  • Regarding rules, I really don't think we need more rules, per se. Wikipedia is entirely consumed by its rules and the bureaucracy and thousands of fiefdoms that come with it. Right now, we need to arrive at a vision for what Docs can be used for... after that, we'll know if we need rules to enforce that vision that go beyond the mechanics for editing, review and rep.
    – Frank
    Commented Aug 5, 2016 at 21:30
  • 4
    @Frank I'm not sure where you heard that for Docs, but that's incorrect. We do expect most readers to come from Google, but the current state of search in Documentation is pretty bad (not even on par with Q&A for usefulness) and we'll be putting more work into it once other, more pressing issues are resolved.
    – Adam Lear StaffMod
    Commented Aug 5, 2016 at 21:36
  • @Adam Okay, that's good to hear.
    – Frank
    Commented Aug 5, 2016 at 21:37
  • 1
    @Frank Plus I only suggested very trivial things (that would imho make a big difference already). But I also really think that we won't be definitively sure of what Documentation really should be until people start actively using it.
    – Cimbali
    Commented Aug 5, 2016 at 23:04
  • @Cimbali I upvoted your question long ago and think your ideas there are good and reasonable. What I was trying (very poorly) to get at -- more than how much SO cares about search results, topic ordering and other internal navigation -- was that you characterize internal search as helping "people who want to use" docs, while the refrain I have been hearing is that all such people will arrive from external search...
    – Frank
    Commented Aug 5, 2016 at 23:37
  • 5
    @AdamLear Per Shog9: so you just mentioned that you don't really browse MDN. Same here. Google or links from other topics (that I find via Google). Browsing is for when you're stuck in 1999 and have just installed MSDN from CD. on SOD chat - as one example of where Frank and others are getting the "we don't care about anything besides Google search" Commented Aug 6, 2016 at 0:03
  • 8
    @Frank: the problem with outsourcing search to Google is that Google is search for English, but Stack Overflow is Programmerese, not English. In Programmerese, -> is a word, not punctuation, and and is not a stop-word. But I already argued this (and was shot down) "6-8 years ago"™ during the private beta when Meta was still UserVoice, so I'm not holding my breath until search gets fixed. Commented Aug 6, 2016 at 0:28
  • 5
    "I feel like everybody is trying to fill documentation with good content" – You must look at different tags than I do. Ruby is abysmal, IMO. I am so overwhelmed, I don't even know where to start. stackoverflow.com/documentation/ruby/3464/comments Really?!? Commented Aug 6, 2016 at 0:30
  • 1
    @JGreenwell Eh... I can't speak for Shog, but that reads to me like "we care about search, not browsing experience". Google, site search, (if you really must) Bing, etc are all potentially an option.
    – Adam Lear StaffMod
    Commented Aug 6, 2016 at 0:32
  • @AdamLear I read it as "Use Google" - the browsing experience is a separate issue (and definitely an issue) Commented Aug 6, 2016 at 0:39
  • 1
    @JGreenwell "Google" is effectively synonymous with "search" at this point. :) Either way - we'll be putting more work into search in Documentation.
    – Adam Lear StaffMod
    Commented Aug 6, 2016 at 0:41
  • @JörgWMittag Right, I'm not very active on documentation. I meant here, on meta. Everyone seems concerned about how we get better content, which is great. Or more often, trying to figure out what content we want or how it should be formatted. I don't think we can hope to find the good way of doing things before actually starting to use Documentation.
    – Cimbali
    Commented Aug 6, 2016 at 1:50
  • 4
    No one "browsed" MSDN after installing it from CD, either. Even back in 1999, the big important feature of WinHelp was built-in full-text search.
    – Cody Gray Mod
    Commented Aug 6, 2016 at 13:56
0

Author was trusted to make this change without review

Big Thumbs up for this feature. When User click review badge they get all review currently in the queue. So some of they don't know whats better even.

A few seconds ago I got a proposed change mail to my Inbox. At that time I couldn't make online Cz of some works. When I came back It was accepted By 3 and rejected by 1. pacanga Rahul Khurana David and Nicholas (names are added not to insult them. Its just a Proof)

Among those 4, only 1 answerd in codeigniter tag. And Review approved. But when I check it, it is not common method. Its user based opinion. It can be different with user to user. So I'm able Delete it with my privilege.

If there was another aprove method it will be queue again n again.

A change is being rolled back due to introducing incorrect information: This will give the wrong understanding of Codeigniter Framework. This is not a common method. It's user based opinion. Rolling back to version as of Jul 24 at 4:50.


Just appreciating this feature.

Drawing of a thumbs up gesture

-1

As a target for the rep system changes, I would suggest the following metric: it should take someone with my level of knowledge as much time and effort as I've put into Q&A to earn my current Q&A rep on Documentation. I haven't contributed to Documentation yet and don't have any current plans to do so, but if its rep system renders my Q&A rep meaningless, I will probably stop contributing to Q&A too. No great loss to StackOverflow, perhaps, but sad for me.

Maybe this sort of inflation is unavoidable at the start, just like in the early Q&A days when you could get rep for knowing what a null reference is. Maybe it'll take a few months for Documentation to get "full" and then it'll be just as hard to earn rep there as in Q&A. But that's plenty of time for the introduction of Documentation to devalue my meager 6k. If that's how it's going to work, I think the two rep systems should be separated.

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