80

So I see something I feel strongly about in a Documentation example - a bad practice.

My first instinct would be to add a comment to discuss this with the author.

But that's not possible.

No, I don't want to edit it myself right now

  • It's not a grossly unsafe practice, it's just a smelly one that no one in a high-performance environment would want to have in their code base.

  • Bad practices are grey areas. I may not necessarily be in possession of the one holy truth on the issue. I would like to be able to discuss them with the author(s) and others, rather than just override them.

  • A comment about a bad practice can be valuable even when I'm too lazy/busy to fix the contribution myself.

What I ended up doing was downvote as "not helpful". But that is in itself not very helpful. Most of the example is ok, it's just one bit that isn't great.

It seems like there should be a comments section.

Just like it works on SO.

Why has this been made so difficult?

Can it be changed?

Edit: now the example I flagged was nuked by another veteran user in response to my downvote. Which in hindsight was probably the ok thing to do and I could have done myself, but I can communicate neither with that user to discuss whether maybe parts of it could be preserved, nor the author of the contribution to tell them what they did wrong. That seems insane.

15
  • 1
    Currently the only way to do that is to request improvement and add your comment there, but that shouldn't be used for discussion. Comments under examples will clutter the page even more. I think Where to discuss how to organize documentation for a tag/topic? kinda covers this as well. If banners like "bad practice" or "needs improvement" are going to be prominently displayed, it'll look like lots of Wikipedia pages ("Needs clarification [may 2013]"...
    – CodeCaster
    Commented Jul 22, 2016 at 9:17
  • 11
    @CodeCaster I'd prefer to just have a good ol' comments section that can be hidden by default. It is one part of the power of SO. I'm sure they had their reasons for not implementing that, but I'd like to hear them as it seems like such a huge impediment to participating.
    – Pekka
    Commented Jul 22, 2016 at 9:20
  • 3
    Comments are the last thing that will be read, if ever. People are going to copy-paste the code from examples anyway, and if it works, they'll be happy, even if they just introduced a bad practice or security vulnerability. We need stronger quality control than just votes and comments (actually just as we do need that on on SO Q&A), for example banners ("bad practice") or reviews ("This code works, but ..."). But let my opinion not digress from your question: yes, we could certainly use comments.
    – CodeCaster
    Commented Jul 22, 2016 at 9:23
  • 11
    We need stronger quality control than just votes and comments oh, I don't necessarily disagree. But comments seems like an obvious first step.
    – Pekka
    Commented Jul 22, 2016 at 9:24
  • 4
    I absolutely agree on hidden comments. Commented Jul 22, 2016 at 11:10
  • 17
    "communicate...with...the author of the contribution to tell them what they did wrong" This seems like the biggest selling point to me. Sure, I could fix the issue myself, but being able to contact someone and give them some tips on how they could make higher-quality contributions in the future is really important. Especially in the early stages of documentation, when people are still learning how to use the feature effectively.
    – Cody Gray Mod
    Commented Jul 22, 2016 at 11:12
  • 3
    This documentation effort feel a lot like Wikipedia. There is a discussion page there. If I disagree with something in an article, I usually add a discussion item; after a whlie, when no-one convinced me not to do it, I go forward and actually change the article. Works quite well, I believe. Commented Jul 22, 2016 at 11:24
  • 3
    I would also like to see something like comments. I came across an example that had an error. But I'm not able to correct the example myself. It was a topic I have no experience in. (The error had nothing to do with the topic.) Correcting the Error would change the meaning of the example. I would like to post something like "your assumption is wrong because...". The Author or someone else could correct the example then without making it worse. Commented Jul 22, 2016 at 11:29
  • 1
    @lokimidgard, I feel the same, although I can correct topics. Sometimes it is up to the original author to edit because editing it myself could either make his example look worse (not enough experience in the subject) or his example could be changed into something he did not mean. Commented Jul 22, 2016 at 11:33
  • That moment when you see the notification pop up, for a comment that asks a question and you realize: it's made to an edit on documentation and there's no way to respond, ARGL!
    – null
    Commented Jul 22, 2016 at 11:34
  • 1
    Can flag for "needs improvement" but flag choices for actual improvements aren't intuitive for these cases either
    – charlietfl
    Commented Jul 22, 2016 at 11:34
  • 6
    I'm definitely running into similar situations where it feels like a comment or two would clarify, or lead to iterative progress.
    – Jaydles Staff
    Commented Jul 22, 2016 at 12:56
  • 3
    How about a wiki-style "Talk" page per topic, instead?
    – TylerH
    Commented Jul 22, 2016 at 19:37
  • Comments below the topic, just like comments below the questions and the answers is much better than a Talk page ala wikipedia: the context is more obvious, the issue can be solved quickly and the comment removed. I do this all the time on SO to get authors to improve theirs answers.
    – chqrlie
    Commented Jul 25, 2016 at 0:18
  • Please add this +1.
    – JonH
    Commented Aug 15, 2016 at 19:18

2 Answers 2

5

To start off - we are paying attention to the feedback loop in Documentation, and I do think there's considerable room for improvement still. Some of the features we have for it are subtle, accordingly underutilized (like inviting folks to chat about a draft) - and thus aren't working out like we'd hoped. We also definitely have a "what's this topic/example's history"-problem to solve.

That said, there are reasons that there is no commenting on examples.

Reading comments shouldn't be necessary

Tell me if this sounds familiar: you're using an answer, but it doesn't quite work - you read it again to see if you missed something, and this time notice a comment that explains what you're doing wrong (implicitly the answer is out of date, or omits a caveat, or what have you). It's not hard to find examples if you haven't seen it.

Honestly this is a flaw in Q&A, one made worse by how relatively hard and discouraged* editing is. I think it'd be much better if these comments had resulted in edits improving the answers, so just reading the answer gave you everything you needed. We're explicitly encouraging this is Documentation, by making it much easier to propose edits (while still requiring review for most changes)... and removing comments.

*One subtle discouragement we'll never be able to fix is the very notion of ownership. People feel, understandably, awkward about editing something that "is" another person's.

The "owner" of an example isn't the only one who can improve it

Commenting on a question or answer notifies the owner (ignoring @replies for now), which makes sense because they're the person having the problem/creating a solution. However that logic doesn't really apply for examples.

Examples, like all of Documentation, are meant to be collaboratively edited - having several contributors, all on a relatively equal footing. In addition, there are many more potential future contributors to an example than their are for a question or answer - this stands to reason, since we are documenting relatively general topics.

This is why we have improvement requests, and why down voting prompts you for an explanation. Those are routed to many people, not just the owner or previous editors.

This is also why we do have commenting on proposed changes. That's a place where there is a single person who can take feedback on something they produced and improve it.

Comments make versioning and historical referencing much harder

One of the basic tenets of Documentation is that you can always get to the page you were using when you wrote the code - that's why all topic pages get a #t=######-slug on them. If you ever copy/paste a link into a comment, stumble across a link in blog, an old tweet, or whatever - we want that content a click or two away for you. We've all been in the "my docs are gone!"-boat before, we'd rather not be there again. This is the root reason why edits in Documentation conceptually happen at a "page"-level - so the whole page is always sensible, and thus rewindable.

If we had comments on examples, editing (and reviewing edits) would get much trickier. For example, if an edit incorporated a comment into an example you'd want to delete the comment. Moving, combining, or splitting examples might necessitate moving comments. Actually making good edits (and determining if edits were good) would accordingly get more complex.

This also explains why, in Documentation, improvement requests are handled with edits. They're basically comments that are deleted alongside your a change, and exist out of band from the topic/example so we don't have to include them in older versions.

3
  • @NicolBolas uh, yeah? That's why I led off with "there's considerable room for improvement still" - chat option (and other things) isn't really working imo. Commented Aug 16, 2016 at 2:04
  • 2
    Clarified. And now the comments on this answer are out of sync with it's content, which I guess is appropriate? Commented Aug 16, 2016 at 2:16
  • I agree with the main substance of the answer, but ... the first para still comes across like "We have issues with X. Namely, Y and Z." (suggesting that's a full listing), rather than "For instance, Y and Z." (suggesting a partial listing, consistent with your comment about there being "other things"). I'd make the edit, but am not sure I've understood you correctly.
    – Frank
    Commented Aug 16, 2016 at 3:09
-1

Examples already appear as a wall of text when viewed. Adding comments to them will only make that worse.

That said, there does need to be a space to have extended discussions about the topic itself. These discussions would encompass individual examples.

As comments are not fit for extended discussion, the logical place to do this would be chat. Each topic should have a link at the very bottom below remarks. It could be called Discussion.

Clicking on a topic's discussion would take you to the chat room for that topic. Every author of an example would be a room owner in this chat room, this way anyone wanting to discuss a specific edit could ping the exact author. Conversely, a general discussion could also take place about the topic itself with regards to order, example content, merging, or breaking apart. In addition, the room owner aspect would allow users to see exactly who is already an author of an example in the topic as their names will be italicized.

The added benefit of doing this in chat is that it keeps the topic page clean while allowing a rich environment to have a dialog about the state of the topic.

13
  • this isn't very organized though, especially if there are two examples which need discussion. Also hard to follow when a new discussion popped up or just someone saying something to a discussion you've already decided to not pursue… no, please not this way.
    – bwoebi
    Commented Aug 18, 2016 at 20:13
  • @bwoebi - Where to start... so you would like every single comment to ping you? Otherwise, how would you follow the comments? Further, here are 6 comments shown (click to see another 5643 hidden).
    – Travis J
    Commented Aug 18, 2016 at 20:15
  • Two examples needing discussion would be perfectly capable of being handled in a chat environment. There is currently a chat that handles thousands of them right now.
    – Travis J
    Commented Aug 18, 2016 at 20:16
  • Chat is very organized, and is currently used at a high pace already. There are millions of chat messages and overall the organization aspect of chat is used in a wide variety of places. For example, the SOCVR room uses chat to organize all of their burnination, retag, review, and edit events; and have been for a few years successfully.
    – Travis J
    Commented Aug 18, 2016 at 20:17
  • Chat is most certainly not hard to follow. It is a simple transcript where extended discussion can take place. It is best to keep these types of meta discussions apart from the examples and topics themselves as it will detract from the content.
    – Travis J
    Commented Aug 18, 2016 at 20:18
  • I'm talking of discussions, i.e. not a series of random comments relating to different things. (i.e. grouped comments, basically a bit like Q&A we're using for meta or perhaps like wiki talkpages). Also, talking about two things concurrently is not an issue. But when something gets mentioned in middle of another discussion and not picked up quickly by anyone, it's quite likely to drown in a discussion about the other thing. In chat, if there is ever a lengthier discussion, I'm not going to read up transcript to find whether something else interesting me has been discussed and I'll miss it...
    – bwoebi
    Commented Aug 18, 2016 at 20:22
  • These chat rooms will be for topical discussion. I highly doubt anyone is going to simply wait in there to talk about the weather. That doesn't happen in "continue in chat" rooms. Further, if there is current discussion it is probably from users who are already well versed in the topic and its history. They could provide either finger tip knowledge or links for historical precedence. If they aren't there, then there shouldn't be that much to read, and to be honest, if reading is an issue none of these features will help you.
    – Travis J
    Commented Aug 18, 2016 at 20:32
  • 3
    It is impossible to have anything remotely approaching a meaningful discussion. Talking through chat is like talking to someone when you're out of breath: slow and inefficient. Wikipedia's talk pages are a far superior solution to such a problem. They're better organized, you can skip conversations that are not of interest to you, and so forth. Commented Aug 18, 2016 at 20:32
  • @NicolBolas Okay, so maybe it doesn't support meaningful discussions, but that doesn't mean it's useless. In particular, it seems to address the OP's example (ping an editor, chat about why something isn't good practice). For meaningful discussions, well, the discussion of those is over here: meta.stackoverflow.com/questions/329173/…
    – Frank
    Commented Aug 18, 2016 at 20:42
  • @NicolBolas - It most certainly is possible to have meaningful discussion. Wiki talk pages are a shot in the dark. Chat is a perfectly fine vessel to hold extended discussion about topics, and keep in mind this is an edge case. Docs does not have this right now, and aside from your personal (and frequent) gripes with the overall feature, including talk pages would not be a magical cure. Here is a talk page example "Mattheus Chediak Deletion Why did you delete my page ?/ — Preceding unsigned comment added by Chediak (talk • contribs) 19:30, 3 May 2016 (UTC)" This couldn't be handled in chat?
    – Travis J
    Commented Aug 18, 2016 at 20:45
  • If chat cannot serve as a solution here, the comments surely will not.
    – Travis J
    Commented Aug 18, 2016 at 21:07
  • To me, the biggest problem with chat is synchronicity. It requires all participating individuals to be online at the same time (not to mention sitting outside any firewall that blocks the chat).
    – Thriggle
    Commented Aug 18, 2016 at 21:16
  • @Thriggle - Chat here is stored indefinitely. All it requires is participating individuals to look, just like comments.
    – Travis J
    Commented Aug 18, 2016 at 21:17

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