68

Documentation has finally reached public beta, and it looks quite good, but (there's always a but) there are some things wrong with it.


Duplicated content

We have quite a few canonical (general) answers here on SO, and instead of moving them over to documentation they're just getting c&p'ed, which is wasting resources. Not to mention that it's going to be quite confusing to see the same exact answer twice on search engines (one from main, one from documentation).


Rewards

I fully agree with the perspective that people participating in Documentation should be rewarded, I just disagree with adding documentation-rep to your main-site-rep. That just devalues your initial reputation and will indefinitely lead to an inflation of rep over the next couple of days/weeks/months. That's bad.

As far as I understand it Documentation is meant to be an addition to Stack Overflow. Granted, it's a lot bigger than the other additions we have, but still, it's an addition, same as the review-queues, and as such badges would - in my opinion - be enough as reward.


Reputation cap

As you probably all know by now: We have a reputation cap for Stack Overflow (200 rep daily). The problem now - reported by Sam - is that documentation does not care the least about this cap (possible bug, see comment by Adam Lear), resulting in people being able to get far more reputation.

I'd like to hear your opinions!

41
  • 7
    Hmm. Rep cap should be respected still. I'll check.
    – Adam Lear StaffMod
    Commented Jul 21, 2016 at 12:06
  • 51
    I completely agree that doc should not grant rep on the main site. It will lose its current meaning
    – Tim
    Commented Jul 21, 2016 at 12:06
  • 49
    @DavidG right now people are flooding documentation with content that is already easily available on the main site. If you are quick to post about some popular topics, you can easily farm a bunch of rep without having to do a lot for it. You don't even have to be proficient in the topic, just find the copy/paste buttons and bring content over to documentation
    – Tim
    Commented Jul 21, 2016 at 12:10
  • 5
    @TimCastelijns That's a problem with people, not with functionality or rep. Also, this is day 1, it will calm down.
    – DavidG
    Commented Jul 21, 2016 at 12:11
  • 7
    Is there any clear anti-plagiarism policy in place?
    – Kyll
    Commented Jul 21, 2016 at 12:11
  • 19
    People should al least get the credit for their work a lot of stuff that is posted to documentation is not the work of the person that posted it to documentation, but work of the person who originally posted it on the main site, where it was then copied from
    – Tim
    Commented Jul 21, 2016 at 12:25
  • 4
    @Alon we are not even able to monitor all incoming traffic on the main site, and now we have to monitor the documentation site as well. On documentation, privileges are not based on reputation, which makes moderating it a bit harder
    – Tim
    Commented Jul 21, 2016 at 12:32
  • 3
    I still think that this problem should be handled with moderation solution (Only allow uses with 10,000+ rep. to contribute to the Documentation for example), denying uses from their credit is not right - And if the Documentation is on SO, the rep should be reflected in the total SO rep.
    – Alon Eitan
    Commented Jul 21, 2016 at 12:37
  • 42
    I agree on both problems. Especially on rep inflation. How do you like +560 rep for mere edit with minor comment added? It's not bad. It's badly broken.
    – saaj
    Commented Jul 21, 2016 at 13:12
  • 4
    @saaj Now at ~725 rep.... I agree, it's getting silly.
    – Seth
    Commented Jul 21, 2016 at 13:18
  • 8
    @uzaif Good job! Looks like you doubled your rep with a minor edit.
    – 2501
    Commented Jul 21, 2016 at 13:25
  • 37
    Honestly, this rep stuff is soo broken. I really hope the devs redact all the gains that have come and figure out a way to seperate it, as we are about to get a flood of low-rep users with high-rep privileges...
    – RGA
    Commented Jul 21, 2016 at 13:40
  • 4
    Somehow the post has disappeared from "Hot Meta Posts" on SO. Now the side block has posts with less votes. Seems like it sounds undesirably annoying in a glorious release day...
    – saaj
    Commented Jul 21, 2016 at 14:10
  • 3
    Cure for paranoid tremors: how are community bulletin items selected? Since 2 slots are taken up by the docs announcements, only 2 meta posts can fit in the bulletin (cc @saaj) Commented Jul 21, 2016 at 14:31
  • 8
    @Thomas trust is part of the meaning it currently has. I trust people who earn rep by posting quality answers. I do not trust people who earn rep by copying things over to documentation
    – Tim
    Commented Jul 22, 2016 at 9:29

8 Answers 8

20

The rep cap thing was, indeed, a bug. It's been fixed, and we're going to run recalcs shortly to correct earlier over-awarding.

In terms of rewards in general... you're right in saying that Documentation is an addition to Stack Overflow. It is, however, not nearly in the same league as review queues or any other feature. It is the first (and so far only, but who knows) completely different type of content that can now be created. Writing documentation isn't the same as reviewing Q&A posts. Reputation rewards make sense here for the same reason they make sense for Q&A posts.

Having said that, it's entirely possible that we're currently running with wrong thresholds and amounts. This is literally day 1 of public beta. As much as it'd be nice to think that we got it all right from the start, Stack Overflow Q&A had several rep revisions over the years, and there's a good chance we'll need to make tweaks for Documentation as time goes on as well. We are monitoring usage and rep changes. And we're discussing potential changes as I write this, before we run the first (of probably several) recalcs.

8
  • 2
    Whaat? You mean all the bellowing about the rep cap was the result of a mistake?! This is unconscionable! Unfix it right now so that we can be indignant again!
    – jscs
    Commented Jul 21, 2016 at 18:34
  • Can you please explain the nature of the rep recalc? What type of extra reputation will be reverted? It seems like i'm the only one here that got only +50 on examples I created
    – Alon Eitan
    Commented Jul 21, 2016 at 18:34
  • 3
    @AlonEitan Any reputation that was gained over the daily max of 200 will be reverted. So basically people with > 200 rep for today will be brought back down to 200. There may be other changes depending on what/if we change the reward values to.
    – Adam Lear StaffMod
    Commented Jul 21, 2016 at 18:38
  • 7
    If this is completely different type of content wouldn't make sense to keep completely different reputation system?
    – zero323
    Commented Jul 21, 2016 at 18:50
  • 1
    @zero323 It's still part of Stack Overflow.
    – Adam Lear StaffMod
    Commented Jul 21, 2016 at 18:52
  • 4
    Well... In the same way one could argue that community wikis are part of Stack Overflow as well so should be covered by similar rules. Yet we acknowledge that this is fundamentally different type of contribution. How for example can we deal with voting irregularities?
    – zero323
    Commented Jul 21, 2016 at 19:10
  • @zero323 Same way we deal with them in Q&A, presumably.
    – Adam Lear StaffMod
    Commented Jul 21, 2016 at 19:11
  • 3
    "...completely different type of content..." I don't really believe in that. It's not the same than Q&A but it's not completely different either. Soon we will see a lot of overlap. In the best case, some quite basic but popular Q&A can be made obsolete by referring to Documentation and we end up with real tough questions in Q&A. In the worst case we will just have produced lots of duplicated content. Not sure if this is a good idea. Commented Jul 21, 2016 at 19:39
18

Another aspect of duplication is within Documentation itself. I have seen several examples or requested topics being created in one tag that have their own dedicated tags and documentation.

For example, there was a requests for pandas and flask and requests in the Python group. All three of these have their own documentation group. I can't close the topic request as "already exists" though without selecting a specific topic within the other tag. pandas is a big topic. I should be able to close it as the entire pandas documentation tag.

1
  • 2
    I feel like the problem is that, it is in-obvious that a more dedicated topic or tag exists. One of the arguments I've heard is that a user would find the topics and tags through search engines, so something like a "related topics/tags" section is not needed. But does that mean that contributors are also expected to use search engines to verify that information doesn't exists elsewhere? Commented Jul 22, 2016 at 15:58
12

Issue 1: Undocumented Code

Another issue I see is ironically undocumented code examples. While such code will be edited over time to include comments and surrounding annotation, I don't see a flag beyond "unclear" that addresses it. Undocumented code may become such a common problem that a specific flag may be needed:

This example is code-only and lacks explanatory comments or documentation.

Issue 2: Aliasing and Linking

A second issue that occurred to me is aliasing, as brought up by others.

Qt and PyQt are good examples here. Someone looking through the PyQt examples may not find what they need, get the answer elsewhere, and make a new doc entry. Unfortunately, their subject is thoroughly addressed in aqt tagged entry. If the subject is conceptual enough (i.e. not language-specific, e.g. "Using Layouts"), we now have two docs on the same subject.

Aliasing would help with this: allow linking doc entry foo to doc entry bar with a note after redirect, or perhaps a note in the link that it is a redirect.

An alternative here is to encourage linking to other doc entries for the basics. In the Qt/PyQt/"Using Layouts" example, the entry would begin with a link to the Qt entry, then provide PyQt-specific code examples.

7

Regarding duplicated content, you mention canonical-style answers being copy-pasted over to Documentation.

This is not necessarily a bad thing. Some canonical-style posts really might be a better fit there. This was even mentioned in the original Documentation annnoucement: "There are Questions that come up repeatedly whose root cause is poor documentation. [...] mitigate a source of repetitious (often exact duplicate) Questions."

For some good examples, have a look through the FAQs in the Javascript tag wiki. Most of those strike me as perfect fits for Documentation; simple-sounding questions about common tasks, often at the language level. They generally admit some depth in answering, after getting past the bare "Here's how you do it: $SNIPPET". But the shortness and simplicity of the questions themselves can provoke Help Vampire allergic reactions.

Also, many canonical answers are Community Wiki already, or are treated as such by tag regulars, which fits right in with Documentation.

I do agree that these posts should not exist in two places at once. If they are brought over, I'd figure they should be mved, not cped, i.e., removed from Q&A. On the other hand, that brings up two problems: first, that (in the case of non-CW posts) the reward structure for the originals is disrupted, and second, that canonicals are often used as dupe targets, to address "Ugh, not this problem again" burnout.

Ideally, the people who are currently involved with the canonical on Q&A would also be recognized/rewarded when its new life begins on Doc. I don't know that there's any mechanism for that, aside from just making sure that the Q&A-side author does the actual copy-paste job.

The dupe-target issue is more serious, since the idea of using individual Docs as question dupe masters got mentioned repeatedly but never really addressed in the formational stage, and is officially "mmmmmayyyybe...." as of now. Moving canonicals is a bad idea if it leaves a functional hole on Q&A.

1
  • I'm not sure we can avoid duplication. Every example you can possibly post in Documentation can also be asked for in a Q&A. Just look at the topics' titles of the curent Documentation. It's basically a top 10 Q list of the Q&A part of SO (Just add "How to"). The only way to avoid duplication would be to give Documentation priority and close every Q&A that is answered by Documentation (hopefully that can be done automatically at some point). Commented Jul 21, 2016 at 19:43
6

Linking Parameters to an example is not well done. Take this proposed change as an example.

The example includes a block of code and a short description of a function used within the code. At first glance, the example looks incomplete. There isn't a description of what the parameters are or do. However, further down, we can see the user took the time to fill out the Parameters section with a description of what everything does.

The problem is two fold:

  • The example and parameter descriptions are physically separated, with the "Syntax" block between them.
  • Additional examples may require other parameters. How do we separate these parameters so that it's obvious which example they belong to?
4

I encountered this Extensive Edit, which may have given the author some reputation (125+115+80+5, probably limited by 200 daily limit). The topic happens to be the first one in Java. After Lambda expressions the up-voters seem to lose their interest in voting.

I doubt this kind of reputation gain is intentional. Does everyone who has done an edit gain +5 for each upvote?

reputation gain

2
2

Consistent formatting will also be of great help as more examples are added, because having to read multiple different styles for the same programming language in succession can be tiresome. Of course, this isn't something that can be enforced so much as conforming the generally "stable" body of examples one things settle down for particular topics will likely be an indicator to future documentation adders. To not start formatting wars, I don't think style should be conformed across topics in a language, just within the topic itself, so everything on the same page looks the same.

2

I cannot open a tab of documentation in Chrome without getting massive CPU spikes. It looks like the client SO page initiates multiple extra requests and Chrome (probably other browsers too) gets overloaded within a minute or two.

This forces me to copy a portion offline to a plaintext editor, make changes and paste it back into a newly opened tab of SO that hasn't yet had - with the result that I don't enjoy a lot of goodies - like comments on a draft, simultaneous editing and live previews.

I've just started contributing to Doc and I know I'm not a massive contributor, but there might be others with the same issue. I'd be happy to contribute more info on the bug if someone could direct me on where to look.

P.S: I know this isn't a problem regarding the administration/guidelines of Documentation, but it is still technically a problem with Documentation... and if this isn't the right place, please feel free to reparent.

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