4

The new documentation section of SO is cool. It fills a needed gap.

However, we need some sort of mechanism for adding comments to the user-contributed examples.

Here's why:

In the section on the Swift programming language, there is a subsection on closures, and a sub-subsection called "Passing closures into functions"

That sub-subsection has a sub-sub-subsection titled "@noescape parameters". That bit is correct for Swift 2. However, with the release of Swift 3, the semantics of closures have changed. Now, instead of closures being escaped by default, they are not escaped by default, and you have to mark escaping closures using the new "@escaping" tag.

I'd like to add a comment to that section so the author can update it to reflect the new semantics and syntax of Swift 3.

Also, a question:

How do you gain edit authority for documentation posts? And for those who don't yet have edit authority, shouldn't there be a mechanism to submit a proposed edit that gets reviewed and approved or denied, just like there is in the SO questions and answers section?

EDIT

I just found the edit controls in documentation. They are different than those for the SO question and answer section (and small and subtle controls) so i guess my suggestion is to either make the editing controls the same as those for SO questions and answers, change the editing controls for SO questions and answers, or create a meta documentation ReadMe that explains the differences.

3
  • 1
    The "comment" thing is being worked on. (Scroll down to "Planned Changes" and check the "Discussion" heading.) As for "edit authority" do you mean the right to edit without review? Because that was implemented back in August and you'll find the rules at the top of that post.
    – Kendra
    Nov 15, 2016 at 16:30
  • @kendra, thanks for those links. I found the editing controls after posting my question, and edited to add a suggestion to normalize the editing controls with the rest of SO, or document the differences clearly.
    – Duncan C
    Nov 15, 2016 at 16:35

1 Answer 1

1

We are building a discussion tab for topics. Currently, I'm conducting usability tests on a static prototype our designers built. (Feel free to contact me if you want to help out.) This month (which is a bit shorter for us due to holidays) is dedicated to building a working prototype on a development instance. It's too early to indicate a possible release date, but I'm hoping for "as soon as possible".


I recently did some thinking about how Documentation has gone and now is as good a place as any to write those thoughts down. I agree that we need some way to coordinate activities and talk about content on a higher level. We've known about this for a long time. And we built several mechanisms for solving that problem:

  1. During the private beta, there was a mechanism for entering a dedicated chat room when two or more people were working drafts to the same topic. For a variety of reasons, that feature didn't get much use.

  2. Improvement requests are designed to be a lightweight issues tracker. We've reworked them several times and they more or less do the job. However, they don't cover all the use cases on their own. (Though, it does seem like an improvement request would satisfy your particular need.)

  3. Similarly, topic requests allow users to suggest missing topics to people who might be interested in writing them. Again, it's a narrow use case.

  4. There are comments for both types of requests. They're fine, I guess.

  5. Coming soon: the topic introduction will allow editors to explain the purpose of a topic to readers and other editors.

Then, since we didn't have enough structure around meta conversations on Documentation itself, conversations leaked onto this meta site and chat. When the community is small and the feature is new, this worked alright. But as the feature matures, we are seeing problems that we hope to address with the discussion tab. With the existing meta features, it's just not possible to dig into the inner workings of every language feature in order to document them well. So people are either struggling alone or giving up.

It's tempting to assume coming late with meta discussion features is a failing of the development process. But there's a very good reason why meta features built early in a project's life become sore points later on:

Anyway, my point is that meta isn't just a social software problem. Meta is a social problem, period.—Jeff Atwood, Meta is Murder

The difficulty with pre-building meta features is that there's no way to guarantee the community will use them or use them as intended. Once people start getting used to a discussion feature, it can be hard to sand off rough edges later. So we really did need to hold off on spending too much time building a discussion feature before there were people ready to use it.

5
  • 4
    Did you take advantage of the client side grace period to post an answer 52 mins after the post was closed, or are employees allowed to do that or did you use some weird magic? Nov 15, 2016 at 19:35
  • 2
    @BhargavRao: I started this answer when there were 4 close votes. The grace period is one of my favorite features since it's so frustrating to be halfway through an answer and not have a place to post it. Nov 15, 2016 at 19:41
  • Haha, I guess the SE Dev team has left the grace period only to tend to your frustration, especially after annoying you with the revenge hat ;) Nov 15, 2016 at 19:44
  • @JonEricson so if you start answering when questions wasnt closed, so you were able to post an answer, that is what you mean right?
    – JAAD
    Nov 15, 2016 at 19:44
  • @ColdFire: Correct. Nov 18, 2016 at 20:04

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