23

My colleague, JNat, has been posting regular updates about feature requests that we are working on. That's been working out pretty well and we've undertaken a major new direction in Documentation, so I thought now would be a good time to do the same thing.

You'll notice I refer to a few different phases for each task. This comes directly from the way we talk about product development internally:

Strategy - Discovery - Build - Delivery

  1. Strategy: Set goals & agree on project stages and milestones
  2. Discovery: Iteratively discover requirements, create & validate the proposed solution
  3. Build: Implement—or finish implementing—the final product & test it
  4. Delivery: Communicate & ship the product, post-launch follow up

Projects can go through several iterations within a single stage, or iterate on multiple stages before reaching delivery. Documentation, right now, is largely in the Discovery phase.

2 Answers 2

22

May 2017

Much of May was dedicated to rethinking our strategy which culminated in the Tearing Down the Structure of Documenation meta post. Vasudha also began the Discovery phase by asking What T-SQL documentation has helped you? Most of June will be taken up with Discovery tasks such as gathering input from developers within the company, Stack Overflow users and technical writers.

That said, we did wrap up two quality-of-life features that ought to improve Documentation no matter how it looks in the future.

Redesigned review page

One persistent problem we've seen from meta reports and user interviews is reviewers not knowing exactly what they are approving or rejecting. We think part of the problem is the somewhat disjointed layout of the review page:

Old review top

Among the issues we identified:

  • diff view controls were widely separated from the content itself
  • reviewers sometimes overlooked revision comments
  • automated summaries of changes could be unclear
  • the possible plagiarism warning didn't have a logical place to be displayed

Our newest designer, Aaron Shekey, worked with Adam Lear to rebuild the page:

New review

There's still some work to be done (including something Aaron calls "polish"), but we think this already makes review more useable and understandable.

Flag all the things!

Meanwhile, Jarrod has been making it possible to flag all types of Documentation content for review. For a long time we assumed/hoped proposed changes would allow us to avoid moderator flags. But after adding discussion, it became clear we'd need some way to signal serious problems. As of June 9th, you can flag comments:

Flag that comment!

Topic requests:

Flag that Topic Request!

Examples and Topics:

Flag that Example!

For the moment, these flags are only visible to employees while we work out any problems.

16
  • "For the moment, these flags are only visible to employees" - Not sure I understand, do moderators count as employees?
    – Alon Eitan
    Commented Jun 10, 2017 at 16:31
  • 11
    @AlonEitan: No, moderators aren't employees. What I mean is that we aren't inflicting these flags on volunteer moderators immediately. Once we are confident the flags work, we'll see about exposing them to elected moderators. Commented Jun 10, 2017 at 16:34
  • 2
    For the review page I would really like to see an increased text size for the tag. For me the tag is as important as the title, because if I am reviewing Collections in Java or Python does make a huge difference.
    – Nef10
    Commented Jun 10, 2017 at 20:41
  • 20
    "inflicting" Excuse me?
    – BoltClock
    Commented Jun 11, 2017 at 1:14
  • 7
    Speaking of flagging, can we get a way to just say that the example is wrong? Improvement request only offer rude/abusive, unclear, VLQ, or mod. There is no clear wrong content option besides just the down vote. Commented Jun 12, 2017 at 16:09
  • @NathanOliver Why would a moderator need to intervene on wrong content? Isn't that what editing is for? Commented Jun 12, 2017 at 20:14
  • @NathanArthur If I do not want to edit, but want others to know it should be edited, what do I do? Just down vote and move on? Commented Jun 12, 2017 at 20:16
  • @NathanOliver IMO, yes. That's the way it is everywhere else on SO. Edit, downvote, and/or leave a comment in the topic's discussion. Commented Jun 12, 2017 at 20:17
  • 4
    @NathanArthur It's just weird that we have "Improvement Request" but those don't handle wrong content. Commented Jun 12, 2017 at 20:18
  • @NathanOliver I wasn't thinking of improvement requests as being a part of flagging. You might have a point about needing a new improvement request option. I see I misread your first comment. My bad. :) Commented Jun 12, 2017 at 20:21
  • @NathanOliver: We definitely need to refactor the options. There's been at least one full circle on whether improvement requests are more like flags or more like GitHub issues. At one point "in need of moderator intervention" was a generic "other" option. I'm a little reluctant to include "wrong content" or some such as it might result in improvement requests for simple typos rather than edits. Or requests instead of deletions for examples that are catastrophically wrong. Commented Jun 12, 2017 at 20:48
  • @NathanArthur There's a big difference between documentation and answers. You don't want incorrect information in documentation at all; it's not enough to simply downvote it. It should be fixed or removed entirely.
    – Rob Mod
    Commented Jun 13, 2017 at 4:22
  • @JonEricson Hoe about factually incorrect and we say in the text that this does not include typos. I just think we need something stronger than a down vote for actually wrong documentation. We want people to know it really does need to be improved, not that there was something we didn't care for. I get where you are coming from though. This whole thing is going to take a while to get everything ironed out. Commented Jun 13, 2017 at 14:16
  • @Nef10 I agree. Aaron's mockups included a more clear breadcrumb-style display for the topic under review (e.g. i.sstatic.net/2PwaG.png), but it got tricky to make right with the reviews for changes that move examples or topics and multiple tags are involved, as well as when someone's just viewing the queue and filtering by more than one tag. We abandoned the idea for now, but emphasizing the tag(s) in a specific change is still something we'd like to address.
    – Adam Lear StaffMod
    Commented Jun 16, 2017 at 5:18
  • @NathanOliver I agree with you as well. Part of the issue here just phrasing... Flagging means something very specific in the context of Q&A - typically it's "a diamond mod needs to look at this". This sort of thing does not scale to "a diamond mod needs to be able to vet the validity of this content". That doesn't work in Q&A and it sure won't in Docs. Having said that, I agree that some sort of an alert to others would be good. Right now, it's just improvement requests. Down the road, it might become a different type of request or an "alert" (just to avoid saying "flag" :)) or something.
    – Adam Lear StaffMod
    Commented Jun 16, 2017 at 5:22
3

June, 2017

Most of June was dedicated to the various aspects of discovery around our T-SQL Experiment. We identified our panelists (internal and external) and set about getting a better understanding of -

  • What does the existing landscape of T-SQL Documentation look like?
  • What do existing resources lack? What do they excel in?
  • What are the largest pain points?

And the findings got even more insightful when we grouped users with varying degrees of T-SQL familiarity (novice all the way to expert) together and discussed existing documentation.

A lot of recurring themes and patterns emerged. A few of the highlights -

  1. Official documentation excels in reliability and depth. But none of our panelists were particularly happy with it. It tended to be too complex, confusing and difficult to navigate. Assumptions seemed to be made about the skill level of the user, making much of it unhelpful to those trying to learn. Even expert users found the content to be much too verbose and "unnecessarily complicated" for their purposes. The syntax was described as a "wall of text".

  2. Sidebars, breadcrumbs and outlines are the secondary ways people look for information. Once people find a site they like, they seem to prefer using categorical browsing cues if they exist, and find it hard to navigate if these controls are broken.

  3. Ability to both skim and go in depth as needed - Users expressed the desire to be able to easily jump to parts of the content that they cared about - be it examples or code snippets or syntax or related topics. They also want the ability to logically progress through the content, in depth, when they aren't in immediate need of help.

  4. 'What', 'How', 'When' and 'Why' is never found in one place. A majority of users mentioned the need to have these points early on and in one place.

  5. Content that can only come from experience is hard to find. Expert tips, Best Practices, Common gotchas, Pitfalls, Performance implications... Folks seem to resort to blog posts or SO answers (from Google) to try to find this today.

  6. Lack of Examples - Still a consistent theme but we got a lot more insight into the types of examples people gravitate towards. Users want the ability to view examples based on complexity, seeing them with inputs (database table in the case of T-SQL) and the resultant output when possible, queries for practicality and performance, and just lots more of it.

As you can imagine all of this was great food for thought for us and it got Aaron, our designer for Docs, excited and sketching! We now have early sketches that we are starting to share with our panelists for feedback. Depending on how close we are to being in the right direction versus needing some more iterations, will determine how quickly we might be able to prototype an early version of the product.

If this wasn't enough data, we also kicked off a round of research with technical writers. We have 6 already under our belt with 9 more interviews this week and those are already proving to be very interesting. We're seeing a lot of similar findings which is great! But we're also hearing about deficiencies in the tools/platforms for technical documentation creation - and none with an awesome developer community behind it.

Stay tuned to this post for more updates as we progress with this experiment and poke you again for feedback and thoughts on specific parts of the experiment.

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