3

To me documentations are different from SO questions they should first address the most applicable scenario and then from there answer questions that are less common. If they answer corner cases then they are no different from SO questions itself. Right now this question highest voted example is a tangential one.

I completely know what AutoLayout is and while this example is extremely useful I think it deviates the SO's documentation vision. It doesn't touch the most common needs, it's positioning as the highest voted answer creates confusion for people who is see this as an answer to 'what is AutoLayout`.

The 2nd and 3rd answers are much more generic. So my question is: Is this the right direction of Documentations, or should I flag the example for anything or edit the example to 'this is not a common use case but'.

2
  • 1
    IMO it’s also the question if a "stack overflow"-style for doc examples is a good choice …
    – elegent
    Commented Aug 2, 2016 at 19:58
  • @elegent exactly, I was reading it and then asking myself what is the difference, but then I realized that it mostly consists of great examples that are generic as much as it gets.
    – mfaani
    Commented Aug 2, 2016 at 20:00

1 Answer 1

3

Generally... I don't agree with your thesis that Docs should cover best-case-scenario problems rather than those people struggle with in reality. To uncover the latter, we rely on votes and requests for topics.

That's the role I think voting should play. It may still need some tweaking, though.

In this case... Sounds to me like the problem is that that example is under something called "What is AutoLayout?" and might not belong there. Either the topic title should be changed or the example should be moved to a more suitable topic.

Note that if you have some example in a topic that you want folks to see first, you can pin it. A new "focus" section at the top of a topic is also planned.

12
  • 1
    I don't see any pin option, I only have 4 options: edit, share, flag, collapse. Can you tell me where is it?
    – mfaani
    Commented Aug 2, 2016 at 20:04
  • 3
    @Honey Yeah, it's kind of hidden. There should be a green pin icon in the lower left corner of each example when editing. I'll see if I can find a link or picture in the help center. Hm, best I could find is the first picture in this old announcement post: meta.stackoverflow.com/q/319319
    – Frank
    Commented Aug 2, 2016 at 20:05
  • 2
    This doesn't make sense, I had to save the pin as an edit and have it submitted for reviewing. Am I doing something wrong here?
    – mfaani
    Commented Aug 2, 2016 at 20:07
  • 1
    Yeah, gotta go through review and everything as if it were a more substantial edit. I guess that's just the easiest way to do it in their system, and also prevents pinning wars (like edit wars, but sharper).
    – Frank
    Commented Aug 2, 2016 at 20:08
  • 1
    @Honey: Yep because some must approve it ;)
    – elegent
    Commented Aug 2, 2016 at 20:08
  • 1
    Can someone please provide documentation on the usecase of pinning and why it needs to be reviewed and can their be multiple pins? If not then that means there should be a pin for the entire page, which means if someone else later on decides the pin should be removed then—that is very loopish!
    – mfaani
    Commented Aug 2, 2016 at 20:11
  • 1
    Yes, one pin per page. If you want to start a discussion about it (and its woeful lack of documentation; and its potential for pinning wars), you might want to make a new meta post @Honey .
    – Frank
    Commented Aug 2, 2016 at 20:12
  • 3
    But this kind of voting (system) reminds me of "Hot Network Questions" and their answers: You vote it because other voted it. The result are for example 600 (!) votes for the Creating and Initializing Arrays in Java example…
    – elegent
    Commented Aug 2, 2016 at 20:15
  • 1
    @Frank I creaetd a question, feel free to edit: meta.stackoverflow.com/questions/330456/…
    – mfaani
    Commented Aug 2, 2016 at 20:19
  • 2
    @elegent Yeah, I'm not impressed by voters' behavior so far. They rarely seem to see past the top two examples, even if others are equally helpful. And the lack of rep potential and visibility drives new editors to pile onto the monstrously long examples at the top...Anyway, that's kind of a separate discussion.
    – Frank
    Commented Aug 2, 2016 at 20:20
  • 1
    @Frank it isn't entirely a different discussion I mean it is related in the sense that a first written answer which happens to be tangential but still acceptable is voted highest and destroys the genericness of documentation.
    – mfaani
    Commented Aug 2, 2016 at 20:32
  • 1
    @Honey I see elegent's comment as more pertaining to how people pile onto the top (some academic ref: jstor.org/stable/2647037), and think what ends up on top is just as likely to be the "generic" thing as the "tangential" one. Here, the generic one won, for example: stackoverflow.com/documentation/r/801/… Also, as mentioned in my answer, I don't see the tangential ones as worse necessarily.
    – Frank
    Commented Aug 2, 2016 at 20:38

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