106

It is time for 2017's first major upgrade to Stack Overflow Documentation — a new Discussion feature plus some other improvements to menus, spam-prevention, review audits and the ever-popular vote split view.

View Previous Update

Shipped

Discussion

Every topic now has a discussion page.

Discussion tab

The discussion tab aggregates all the different things that are happening or have happened to a topic, and provides a way to discuss them.

  1. Each Example on a topic gets its own entry. Example comments remain open as long as the example is undeleted.

Example Discussion Item

  1. Comments on Changes are also surfaced. Once a change has been reviewed, its comments are closed.

Change Discussion Items

  1. Likewise, Improvement Requests are surfaced along with their comments. Once an improvement request is handled, its comments are closed.

Improvement Request Items

  1. The original Topic Request, if any, along with any comments on it is also included. By the time a topic request appears on a discussion page it's already been handled, so its comments are closed. It's surfaced because some relevant discussion may have occurred on it.

Topic Request Item

  1. General Discussions entries (created via the New Discussion button) - for anything not covered by the automatic discussion items. General discussion comment threads close 14 days after the last comment was made.

General Discussion Item

You can filter and sort at the top of the discussion page.

Filtering and sorting

Watching Discussion and Managing Notifications

Discussion item comment notifications work how'd you expect, the owner is always notified and the first participant @mentioned, if any, is also notified.

But, we have these eyes all over the page.

The Eyes Have It

They let you opt-in to additional notifications.

If you subscribe to a particular item, you'll be notified of all new comments on that one item.

If you subscribe to all discussions on a topic, you'll be notified of all new comments and all new discussion items (proposed changes, improvement requests, and general discussions).

All vs One

Based on the number of requests we've seen for ways to monitor a topic, we've also decided to opt anyone who makes a non-trivial change (read: has the potential for rep gain) into watching the topics they edit. These opt-ins have been backfilled.

You can manage all of your documentation notifications (including those from subscribing to a tag's documentation dashboard) through the new "watching" tab on your profile.

Watching tab on user profile

Text Menus

As announced a bit ago we've replaced the icon menus and removed the default collapsing of examples. This was originally planned due to confusing resulting from the placement and meaning of certain icons, but we also ended up needing additional room to add a link to each example's discussion and the whole topic discussion tab.

Top of topic menu:

Topic menu

Example menu:

Example menu

This took a surprising amount of work, and lots of changes to some very old assumptions in the editor code. We expect there to be some bugs that slipped through, so do please report any you find.

General spam improvements

Behind the scenes, we've hooked Documentation into most of the anti-spam systems that we're originally developed for Q&A. It's unlikely you'll notice anything in particular change, but it does mean that spamming Docs will now result in a Q&A ban (and vice versa).

One visible change is a new dismiss reason for topic requests.

Spam or offensive dismiss reason

Additional Penalties for Failed Review Audits

Failing audits will now undo some recent reviews, in addition to the existing temporary ban.

Show Vote Split

A privilege from Q&A has been implemented in Documentation: the ability to see the breakdown of up and down votes on an example.

Vote splits

Planned

Moving Topics Between Tags

This is still planned. We've been hung up by issues with how search works, but we're making progress. This option will be a tab under the existing Move Examples dialog.

More Spam and Moderation Related Features

We're continuing to work on spam and moderation tools. We'll be rolling out more updates on this in the coming weeks.

37
  • 1
    so... discussion is per topic? you can't just say, watch all discussion on tag foo? or am i missing something
    – Kevin B
    Commented Feb 6, 2017 at 19:03
  • 2
    @KevinB Discussion is per topic. Subscribing to all discussion on a tag is kind of a lot of notifications - akin to subscribing to all comments in Q&A. You can subscribe to all changes, improvement requests, and topic requests on a tag's dashboard (as has been the case for a bit). We may tweak the dashboard a bit to account for general discussion items existing in the future, which might include new tag-level watching options. Depends how discussion watches end up used. Commented Feb 6, 2017 at 19:11
  • 5
    The problem i see with that is if i wanted to find what discussions are going on in, say, the javascript documentation, i'd have to dig through each topic, one by one, there's 100 of them (currently)... If you subscribe to the dashboard's all changes do you get notified of a discussion starting?
    – Kevin B
    Commented Feb 6, 2017 at 19:26
  • 60
    "Failing audits will now undo some recent reviews" - are there any plans to work something like this back into Stack Overflow proper? This could help undo damage caused by new reviewers who spam reviews until they hit their first ban.
    – Brad Larson Mod
    Commented Feb 6, 2017 at 19:53
  • 12
    @Braiam Unless the comment was edited, that appears to be exactly what Brad L said...? Commented Feb 6, 2017 at 21:10
  • 3
    Seems like it's migrating toward a Wikipedia-style interface. Only for documentation
    – Cullub
    Commented Feb 6, 2017 at 21:16
  • 5
    @Knu: It seems like your feature request (which I upvoted last year sometime) would be mostly covered by watching the entire topic. You'll see new discussions, proposed changes and improvement requests. Maybe try it out and see how it goes? Notifications are obviously something we are prepared to change if needed. (I'm sorry we didn't respond to your request at the time. It's sometimes hard to prioritize when there's a lot of obvious problems happening at one time. The early beta was overwhelming, I'm afraid.)
    – Jon Ericson StaffMod
    Commented Feb 6, 2017 at 23:40
  • 2
    Happy with the spam flag. Can we also flag examples now? Last time I tried to flag something for moderator attention, it turned into an improvement request, for all the world to see. Flag != improvement request; the ability to discreetly flag problematic content is essential for quality control. Commented Feb 7, 2017 at 7:59
  • 2
    This is the first "Documentation Update" that I have upvoted. Some really nice improvements being made here, most of them long overdue, but better late than never, I suppose. I'm thrilled the inscrutable icons have been replaced with text labels, I'm glad our pleas to have a "discussion" page have been addressed (and am excited to see how that works), I'm very glad to now have a central place to manage Notification Overflow, and I'm hopeful about the changes that have been made to better handle spam (which…has been a serious epidemic).
    – Cody Gray Mod
    Commented Feb 7, 2017 at 9:24
  • 13
    I'm still very concerned about robo-reviewing, though. The vast majority of the proposed changes that I've seen have been accepted. Most of them shouldn't have been. By the time I get to the notification and look at the page, it's too late—my vote doesn't count for anything. I have to undo the changes, which is a very cumbersome two-or-more-step process. I still think the reputation level required to approve changes needs to be reconsidered. It should either be raised or some trivial amount of tag-specific knowledge should be required. (Though I do appreciate gold-badge holder's privileges.)
    – Cody Gray Mod
    Commented Feb 7, 2017 at 9:26
  • 2
    @NathanTuggy with the next build, the watch icons will only be displayed if you are already subscribed to an item or it remains open for comments. It is by design that subscriptions "survive" the closure/deletion of an item - it's so delete/close followed by an undelete/reopen doesn't reduce future scrutiny. Commented Feb 7, 2017 at 17:53
  • 7
    Whoa, whoa, whoa. We all know how bad the audit system is. Are you telling me one failed audit will make it so that my last three normal reviews (let's say 3) never happened? Do I get those reviews back to my # of reviews I can perform? This seems way too severe.
    – TylerH
    Commented Feb 8, 2017 at 18:16
  • 2
    I find it funny that the days after this docs update, I've gotten some rep again from my topics - after a few weeks of basically nothing. Now its +- 10 rep per day again. Huh? :D People visiit it more actively again-
    – Mafii
    Commented Feb 9, 2017 at 16:13
  • 4
    Is there a way to just turn off all notifications - I really don't need to be notified that someone, without any python rep, made a change to something I did which was approved by someone else with no python rep. Or to put it simply: I just want to ignore Docs as failed and do not need notifications about anything. Commented Feb 10, 2017 at 0:07
  • 2
    @dorukayhan that only works if you did not try and work with it in the beginning. I seem to be locked into getting notices about documents I edited when still trying to improve Docs in the beginning. Which makes it hard to ignore. I simply want to be able to turn off Docs notifications (which you can do with Jobs, as I did when I got a job) and can make that a full answer if I don't get any response but wanted to see if there was a way and I was just missing it in the post - hence comment. Commented Feb 12, 2017 at 15:42

5 Answers 5

40

I'm glad the discussion feature is in, but my use cases are almost all at the tag-level. Some examples:

  1. Should we split this topic up? Should we merge these 2+ topics?
  2. Should we have have both R "tool" and "task" topics, and how do we want those linked?
  3. How do we want to handle R packages? One topic each, linked to the package's tag (if any)?
  4. Do we need "X" as a topic, and if so, how will it be linked to other topics? How do we want to generalize this to our treatment of other topics in the tag?

Interest in per-tag discussion was apparently from early on, so I'm guessing this is .


I also have a few smaller gripes:

  • Deleted examples (like Utilities here) should (i) still be comment-able and (ii) be greyed out and moved to the bottom of the list so as not to be confused with active examples. Ditto for handled improvement requests.
  • Examples should link to or be threaded with their improvement requests and changes.
4
  • 3
    I don't know that we've declined tag-level discussions just yet. A workaround might be to use the intro topic. The pressing need, I think is for lower-level discussions that simply won't happen unless we created a space for them. Some of the tag-level discussions you mentioned could happen on meta.
    – Jon Ericson StaffMod
    Commented Feb 6, 2017 at 23:56
  • Could you expand on why you want comments on deleted examples? Seems like once an example is deleted there wouldn't be much reason to discuss it. What sort of interactions are you picturing here?
    – Jon Ericson StaffMod
    Commented Feb 6, 2017 at 23:58
  • 5
    @JonEricson Ok, thanks for the ideas for workarounds. Re deleted examples, if my example gets deleted and I come back a month later and want to say "hey, this shouldn't have been deleted. can we talk about this?" it seems natural to comment on the example's thread. I suppose a general thread could substitute, though, especially if this sort of convo is rare or typically unconstructive.
    – Frank
    Commented Feb 7, 2017 at 0:03
  • 2
    Mostly there needs to be a place to discuss which categories there should be and how they should be organized.
    – Lundin
    Commented Feb 9, 2017 at 11:58
12

I like how the documentation tag shows. However, in the topic requests section it would be useful to show what tag it belongs to.

See it in my profile:

enter image description here

In here, the first one belongs to "grep", while the others (regular expressions and printing output) belong to "awk".

Since we do have space for that, adding the tag would make the information more useful.

0
8

Bug in Firefox:

Bug in Firefox

Those two tabs should be next to each other.

I can fix this by setting the max-width of the h1 element to 80% (instead of 81%).

4
7

Two points:

  1. I immediately missed the ability to collapse all topics, this was really very handy on longer topics. It was especially helpful while editing, as the edit box reduces the vertical space available to see the current state of the text you are working on, or might select to work on next, as part of an edit that covers multiple examples within a topic.

  2. I note that the click-to-show-vote-split has copied the Stack Overflow fault of not being able to click the numbers again to go back to the un-split vote view. I can't remember why this was left like this on Stack Overflow, but it still seems inordinately ridiculous.

Bonus third point and likely bug!

  1. When clicking on an Improvement Request Comment notification within the inbox, it links to the discussion page... but the improvement request thread isn't there, it's on the improvement request on the actual example (i.e. the orange-y box thing). So basically it takes you to the wrong place!

Update: Beginning to really miss the collapse-examples button...

3
  • 1
    Re. point 2: "inordinately ridiculous"? Really? At worst it's slightly inconvenient. That's a bit hyperbolic.
    – DavidG
    Commented Feb 7, 2017 at 12:00
  • 5
    Ha ha, you caught me! Yeah its mildly annoying. But in terms of UX this is something I can't imagine a user not expecting to work.
    – Toby
    Commented Feb 7, 2017 at 12:15
  • 1
    Also note that you can vote up/down and then retract your vote to go back to the total score from the upvote-downvote split. Commented Feb 9, 2017 at 21:38
-3

Could any documentation be tagged / linked with stackoverflow to projects on GitHub issues as being work in progress or being resolved, mind you I was thinking after a review. So any bugs 🐜 reported by SO could have providers on GitHub to resolve, vice versa.

2
  • This might make some users misuse Documentation as an issue tracker. Commented Apr 3, 2017 at 22:41
  • Okay then, I hadn't considered this. No problem Commented Apr 3, 2017 at 23:27

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