77

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

Shipped Changes

Reputation

As announced elsewhere, Documentation's reputation system has been updated. Lots of time since then has been spent on bug fixes, and we're still crushing a couple of outstanding ones.

Retract proposed changes from dashboard

It's in the cog menu

It is now possible to retract a proposed change (allowing edits to the draft) without revisiting the topic involved.

A similar option is on its way to the review queue.

Topic Outline

The first parts of the Topic Outline have shipped.

Enter image description here

Side-by-side view (where examples were displayed on the right) has been removed as part of this.

Topic Outline sizes itself at page load to keep other sidebar content visible if possible, so community bulletin (and related content, and eventually ads) aren't pushed too far down the page by its addition.

Planned Changes

Review Audits

Audit tasks will start showing up in the Proposed Changes review queue in the next week or so.

Additionally, we're going to start consuming more history to trigger those audits, as well as restrict access to review (and potentially proposing changes in the first place). We're still analyzing various cases, so expect to hear more about these changes even after audits ship.

Discussion

We've started recruiting users for (very early, mockup based) testing of the previously announced discussion feature. If you're interested, hit up Jon in chat.

Here's an updated mockup:

Discussion v... 4?

Focus section

Work has begun on the focus section, expect to see it in the coming week or so.

Improvement Request changes

We're going to be making some changes to Improvement Requests to clear up some confusion around them.

First, we're going to only allow a single active improvement request on a topic or example per type of request. Each active improvement request will allow comments for further discussion, elaboration, or concurrence.

Improvement request display

Second, the post-downvote prompt is being redesigned to make it clear that your downvote can have an improvement request attached.

New downvote prompt

11
  • 13
    Now to see how effective the review audits are!
    – Kevin L
    Commented Sep 29, 2016 at 20:38
  • 6
    If the outline is to replace the side-by-side view, it should probably be sticky so it’s always in view. See this example for what I’m thinking.
    – Jed Fox
    Commented Sep 29, 2016 at 21:01
  • 4
    I think that the audits should take their material from changes rejected as copied content or factually incorrect information.
    – RamenChef
    Commented Sep 30, 2016 at 2:52
  • 1
    So "Make an Improvement Request" is essential in case of down vote, If so, its amazing. Commented Sep 30, 2016 at 10:10
  • 2
    This makes me sad :(
    – m4n0
    Commented Sep 30, 2016 at 18:36
  • 1
    @ManojKumar How so?
    – Adam Lear StaffMod
    Commented Oct 1, 2016 at 5:44
  • 1
    @InzimamTariqIT Kinda. Right now, when you pick a reason for downvoting an example, we automatically create an improvement request that matches that reason. The idea here is to make that step more explicit since the current implementation has caused some confusion on a number of occasion.
    – Adam Lear StaffMod
    Commented Oct 1, 2016 at 5:45
  • Glad to see the draft editing bugfix, and the topic outline looks nice! I'm still hoping "dismiss" gets replaced with "decline" or "reject" before Google starts indexing Documentation, but I suppose that's minor in the greater scheme of Doc's concerns.
    – Thriggle
    Commented Oct 2, 2016 at 20:23
  • 2
    Frankly I'm no longer interested. It has become union nr 2 no more.
    – Bookeater
    Commented Oct 4, 2016 at 20:24
  • What about multi-language examples?
    – Zev Spitz
    Commented Oct 7, 2016 at 10:50
  • Wut?
    – user4639281
    Commented Oct 16, 2016 at 22:39

1 Answer 1

15

Topic Outline

Looking good, I like the side bar topic outline. As I use a smaller resolution screen (it is on a projector), the size issue before was problematic (lightly) but now with this iteration I can really tell an improvement. From a UX standpoint this helped me.

One small aspect that would be a nice addition would be to include the vote counts for examples in the side bar, similar to how related and linked counts are shown (except without the coloring to indicate accepted answer).

For example (from Promises - JavaScript):

enter image description here

Here is a small userscript that can be used to see what this would look like as well

$('.topic-outline-example-link').each(function(){
 var id = $(this).data('example-id');
 var vote = $('.example[data-example-id='+id+']:first').find('.example-score.vote-count-post').text();
 var title = $('<span>').text(' '+$(this).text());
 $(this).empty().append($('<b>').text(vote)).append(title);
});

Review Audits

Review is an aspect of Documentation that has become a problem in my opinion. Audits may help, but as alluded to in your post here, perhaps there should be more barriers to accessing the review queue for Documentation (500?), or to even proposing changes at all.

  • With regards to access to the queue, in my opinion the bar must be raised.
  • With regards to proposing changes, it is a little harder to determine, but it seems to me that if a 1 reputation user is first using the site, they may not fully understand the scope and design of Documentation to properly use it even if they are experts in their field.

I am not sure where the balance should be though. Should it be that the barrier is lower for access to the queue, or for access to proposing changes, or perhaps they should have the same barrier? Unsure, I think it may make sense to have the barrier for proposing at 150 (just above the association bonus), and the review at 500 (standard for review queues).

It is nice to see that this is a source of concern for the team though, because it is an important aspect of quality control in Documentation.

9
  • 11
    That would help to understand the ordering too... Commented Sep 29, 2016 at 20:37
  • 25
    The ordering is broken anyway. There doesn't seem to be a real correlation between the number of up votes and the quality of the documentation. The documentation which was created soonest and has the most edits are the ones with the most up votes. Last time I looked there was loads of good documentation with 0 upvotes
    – rdans
    Commented Sep 30, 2016 at 8:25
  • @rdans - The masses haven't arrived yet.
    – Travis J
    Commented Sep 30, 2016 at 8:43
  • 11
    "they may not fully understand the scope and design of Documentation to properly use it even if they are experts in their field." - I wonder about that. I am confused and dazed about Documentation and have no idea what I would feed this hungry monster - lurking on meta seems to only make that worse with all the walls of text that are being written about it. Maybe the 1-rep users who are not hindered by meta-overload actually have a chance to do it better :)
    – Gimby
    Commented Sep 30, 2016 at 11:43
  • 3
    @Gimby - Of the things to wonder about, 1 rep users not understanding how to use SO features should not be one of them.
    – Travis J
    Commented Sep 30, 2016 at 18:40
  • 7
    @TravisJ .. "The masses haven't arrived yet" ... what makes you think they ever will?
    – charlietfl
    Commented Oct 1, 2016 at 19:10
  • 1
    @charlietfl - Google isn't allowed to index docs at the moment as the feature is still in beta.
    – Travis J
    Commented Oct 1, 2016 at 19:57
  • 4
    @TravisJ yup..that will help when someone searches "[languageName] hello world". Still seems to me that 90% of what's there is already documented in already indexed and trafficked resources
    – charlietfl
    Commented Oct 1, 2016 at 20:35
  • 7
    Documentation is essentially a Wiki. 100 rep is needed for editing a community wiki on Q&A, the same bar can be used here.
    – Daniel M.
    Commented Oct 3, 2016 at 21:23

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