168

The big expansion we started on so many months ago, Documentation, is finally out of private beta!

Take a moment and read the blog announcement

Also go and play with Documentation for a bit, read through the help pages, and take the tour.

Anywhere you see a glowing blue dot, you can click to get additional information. You can click the (?) at the top of a page to make all the blue dots visible again.

Help tips

We’ve clearly put a lot of thought into Documentation, and the private beta a few thousand (seriously, wow guys) Stack Overflow users participated in has taught us a lot more but…

We’re still figuring a lot out, and we want your help

We want to hear from you about what’s missing, and what needs work. Upvote the good content you see, downvote the bad, request what is missing, and contribute where you’re comfortable helping out. We’re all in this together.

While you’re doing all that, remember: Documentation applies a lot of the lessons learned from Q&A, but it’s not Q&A. While the basics translate (peer review, by developers for developers, and be excellent to each other) many of the specifics probably don’t.

Things like forbidding...

  • "too broad questions"
  • "too small edits"

make perfect sense in Q&A, but don’t really in Documentation. Similarly, very narrow questions are great for Q&A but very narrow requests aren’t good for Documentation.

There are a few things we don’t think will work very well in Documentation, like..

  • machine generated docs (think Javadocs)
    • anything of that nature is well served today, and would obfuscate the examples we’re trying to create
  • things you don’t use with code
    • while not literally every example needs code, there’s a pretty deep assumption that every topic covers something developers use while coding

Finding Ways To Contribute

There are several ways help improve Documentation.

First, just browse and make the changes (just click the pencil icons) you think are improvements (and if you can’t make them, you can always request them).

Requesting improvements

Second, you can browse outstanding requests for new topics and examples in a tag’s request list.

Requests

Finally, a tag’s Documentation Dashboard lists all the proposed changes, topic requests, and improvement requests. You can browse from the dashboard, or subscribe to queues to have some pending items pushed to your Stack Exchange Inbox periodically.

Dashboard

Starting Documentation

Several tags already have Documentation that was created in the private beta. To add Documentation to tags that don’t have any, there’s a small commitment process.

Commitment process

To avoid creating ghost towns, tags must be relatively active to get Documentation (a few hundred questions overall, and activity in the last few days). In order to commit, you must have a positively scored answer in the tag and at least 150 reputation.

Committers are automatically subscribed to notifications when the commitment succeeds.

Q&A Isn’t Changing

To be clear, none of the rules or community norms for Q&A are changing. Just because a link points to Stack Overflow Documentation doesn’t mean link-only answers are acceptable now, for example. Documentation is expanding Stack Overflow, not radically altering the Q&A on Stack Overflow.

The integration points for Documentation and Q&A are pretty small:

Link Insertion Dialog
There’s a new link insertion dialog

Documentation callouts
If a tag has Documentation, it gets a callout on the question lists

Proposal callouts
If a tag is eligible for Documentation but doesn’t have it, a way to propose Documentation gets a callout on question lists

What’s to come

There are things we know we’re going to do that just weren’t ready in time for launch.

  • Code blocks with multiple languages (think MSDN’s C#/VB/F# switcher)
  • Mobile views
  • Embeddable topics and examples for 3rd parties
  • Improved search

Documentation is in beta, so we know we’re going to learn a lot in the coming months. This list will grow accordingly.


See the follow up post for more details

42
  • 39
    Stack Overflow Documentation. Making Copy and Pasting code ​even easier​. Will this eventually be rolled out to other sites? For example, resources for ServerFault, or Gaming?
    – tombull89
    Commented Jul 21, 2016 at 10:08
  • 11
    @tombull89 right now we're focusing on Stack Overflow. Once Documentation is "known to work" we'll start thinking about other sites. Commented Jul 21, 2016 at 10:16
  • 22
    The public launch of Stack Overflow Documentation... This is a big day, one that will go down in infamy for copy-and-paste developers all over the world.
    – Cody Gray Mod
    Commented Jul 21, 2016 at 10:21
  • 79
    So far, 80% of what I see sucks and needs downvoting. Is there a vote limit? More broadly, where are all of these rules documented? I've looked at the tour, and browsed the list of badges, but that's all very general and doesn't get into specifics. Why is it that when I downvote something, it gets auto-converted into an "improvement request", but there is apparently a separate way to create an improvement request by clicking the "flag" icon at the top? Are those different? The documentation for Documentation (pun not intended) seems to have been written by the marketing department.
    – Cody Gray Mod
    Commented Jul 21, 2016 at 10:54
  • 9
    You can vote 30 times a day, @CodyGray, and these are separate from Q&A votes. Downvoting only triggers an "improvement request" flag if you pick a reason for your downvote, and that's because... well, downvoting it means there's something wrong with the example, and it needs to be improved! But you can also just request an improvement without downvoting the example. Also note that, as this help center article mentions (emphasis mine), "If you see a problem and you can fix it, remember that you can just edit instead."
    – JNat StaffMod
    Commented Jul 21, 2016 at 11:22
  • 28
    @jnat Hmm yeah, I've been a member of Stack Overflow for a while. I'm no stranger to collaborative editing. (In several specific cases I observed, the problem was so fundamental that it could not be fixed by a few edits.) What I am unaccustomed to is the surprising and undocumented way that this system seems to work. When I try to flag for "improvement needed", I'm told I have 0 requests remaining. But yet I can downvote and leave a comment that is auto-converted into the same thing 30 times?? Also, I just figured out that leaving a reason for my downvote is optional. That isn't at all clear.
    – Cody Gray Mod
    Commented Jul 21, 2016 at 11:26
  • 6
    @JNat How is reputation handled, when examples are edited? When I improve an example but only get 2 rep points and the original author gets all the later incoming upvotes, this would surely discourage some to do so. Well known problems arise, like FGITW and multiple topics/examples for the same thing. So, how is reputation handled?
    – fancyPants
    Commented Jul 21, 2016 at 11:37
  • 9
    One of the differences between Q&A and Docs, @CodyGray, is the notion of ownership: substantial edits on examples that are way off are not discouraged like they are on Q&A — you don't have to worry about "preserving the goals of the post's owner" in the way you have to in Q&A. If you see something wrong, you're free to downvote and/or request an improvement; if you can improve it yourself, even if it requires a massive edit, do it. As for your other concerns, we're working on making what's not immediately intuitive either more intuitive, or explained properly. Your feedback is appreciated.
    – JNat StaffMod
    Commented Jul 21, 2016 at 11:40
  • 6
    Folks, remember you can always leave an answer here or ask a new meta question. (This comment thread may not be the best place to get your questions answered in an organized fashion.)
    – hairboat Staff
    Commented Jul 21, 2016 at 11:50
  • 5
    Actually I'm looking forward to the Git documentation (already 23 topics). I use Git but I never had time to dig into it and therefore never fully understood it. With the help of examples in Documentation it just might show the full power of the approach. Commented Jul 21, 2016 at 12:07
  • 29
    Should reputation for documentation be separate from the main site?
    – 2501
    Commented Jul 21, 2016 at 12:32
  • 21
    Isn't this going to make documentation worse by fragmenting it across multiple places? Wouldn't it be better to contribute to the project's actual documentation?
    – endolith
    Commented Jul 21, 2016 at 16:17
  • 8
    It's .. a list of examples? So it's RosettaCode with a StackExchange UI? Hmm. Commented Jul 22, 2016 at 0:12
  • 23
    Is there a way to downvote the whole stackoverflow Documentation idea? Commented Jul 22, 2016 at 21:00
  • 8
    The lack of any kind of structure makes this much less useful that documentation that can already be found on the Net. As for curation of documents that already happens on sites like github. A further issue is the difficulty of monitoring people making copy pasta all over the place to gain rep and become moderators. Ick.
    – empty
    Commented Jul 22, 2016 at 21:17

26 Answers 26

95

As per my comment:

Can someone please clarify the scope of the docs please. The blog post says examples are king, but what I see right now is people adding more or less random topics. What is the point of reiterating the Q&A of the main site? I would understand if docs was for user created API documentation, but I dont see why we need a Stack Overflow in Stack Overflow.

I have checked the various preceeding Meta Posts and it's not clear to me what should go into documentation and what is better left for the main site. It's too vague for me right now. It was often mentioned that the documentation is supposed to be an extension to the Q&A site, but my impression is that it is competing with it instead.

We have quite a lot of good canonical answers on the main site by now. Especially the basic stuff, like how to create an array for example or basically every git command out there, has been covered extensively on the main site. Why repeat that?

Also, how do I decide between supplying a self-answered Q&A on the main site or writing it into the docs? Is there some guideline when to choose which?

Finally, is there any such thing as a too broad topic? Or off-topic that should not go in the docs? I could obviously write a lengthy tutorial about how to handle XML with PHP, but that would then really be that: a tutorial - something that is deemed off-topic for the main site. What about duplicate content?

TL;DR: I miss a clearly defined boundary what should go into docs and what shouldn't.

11
  • 8
    My impression is that docs is like Q&A without the Q part. Therefore there is lots of overlap. As for the tutorial: if you can write it in examples, you can write it in docs, I guess. Commented Jul 21, 2016 at 13:12
  • 3
    "I could obviously write a lengthy tutorial about how to handle XML with PHP, but that would then really be that: a tutorial" - I don't know that you "obviously" could, because there doesn't seem anywhere in the documentation site for anything except examples and a small 'remark' at the end of the page..? Commented Jul 22, 2016 at 0:14
  • 1
    From the Tour: "Documentation is broad, and it is a general reference. You aren't documenting a specific problem you're facing, you're helping others deal with an entire class of problems by documenting." From what I understand, it seems Documentation i different from Q&A in the sense that it should cover topics in a more general manner that can be helpful to other's learning (contrary to Q&A's approach where people usually ask about very specific implementations of a problem which usually don't apply to everyone) Commented Jul 22, 2016 at 3:51
  • 1
    @TessellatingHeckler true, the lack of adding proper hierarchical and strutured content is a problem. You could however, add a single "example" like "Scrape content from website with libxml" and then put all the info in there. It's not optimal either, but it would be self contained.
    – Gordon
    Commented Jul 22, 2016 at 5:13
  • 6
    @sgarcia.dev yeah, that definition from the tour is not helpful imo. It's basically saying documentation as we understand it is a random bucket of whatever examples you want to dump in there.
    – Gordon
    Commented Jul 22, 2016 at 5:19
  • 11
    Q&A to Documentation: I will hurt you for this. I don't know how yet, but give me time. A day will come when you think yourself safe and happy, and suddenly your joy will turn to ashes in your mouth, and you'll know the debt is paid.
    – revo
    Commented Jul 22, 2016 at 8:45
  • I wish Documentation was more about tutorials, not just examples. With UI that allows you to write a long complete tutorial on how to write a small video-game in language X, for example. Commented Jul 22, 2016 at 12:45
  • 24
    I wish Documentation would just go away.
    – Gordon
    Commented Jul 23, 2016 at 11:15
  • 3
    @Gordon I'm in the same boat. I'm waiting for it to get to the good part. Commented Jul 24, 2016 at 2:18
  • So much that. But the problem is, no matter how much you define which shape documentation should have, and boundaries. Docs are meant to be structured, docs are meant to be a good mix of examples and explanation. Contributors here have a too different background to be able to agree to boundaries and stick with them Commented Jul 25, 2016 at 13:54
  • I warned before. Poor Documentation.
    – revo
    Commented Dec 4, 2017 at 21:45
84

After spending 10 minutes on site these are my worries:

  • Topics seem poorly organized. If I go to C# all I get is a list of random topics in random order, which seems destined to grow indefinitely. Currently the top 2 are C# 6 features and extension methods, hardly basic or essential knowledge for working with the language.
  • The strong bias for examples over explanations seems to lead to shallow articles that provide little understanding of how things actually work. Many of Stack Overflow's most useful and highest-voted answers are explanations, not examples. Take for instance most of what Eric Lippert writes.
7
  • 40
    "The strong bias for examples over explanations seems to lead to shallow articles" That! So much that! Documentation is not just a bunch of examples but explanation and context. A topic like, say, inheritance cannot be reasonably exlained just by some examples. Documentation is written documents.
    – Gordon
    Commented Jul 21, 2016 at 17:46
  • 7
    I also find the order of topics confusing. I would like to have at least one hierachy level or organization between tags and topics. What about topic-groups? Commented Jul 21, 2016 at 19:23
  • 5
    @Trilarion I think the problem is not about grouping, it's about having an index/TOC. A person clicking on, say, Haskell tag should end up on something like an index with a list/tree of all concepts for which documentation exists (possibly red links for topic requests). So this index will show how the topics are ordered. Commented Jul 22, 2016 at 12:44
  • @MirzhanIrkegulov Good idea. This TOC should be manually created, as for a real book/manual. Commented Jul 22, 2016 at 12:54
  • 4
    Examples are good, but we do find explanations way more important. Commented Jul 23, 2016 at 0:18
  • 3
    I do not want to sound elitist, but we should have "senior" people only giving a structure: propose topic, sub-topics, give structure. Everyone could contribute an example (in a topic), but just letting everyone do everything will lead to a very unbalanaced documentation Commented Jul 25, 2016 at 13:57
  • 1
    Thanks for the kind words; I appreciate it. Commented Jul 26, 2016 at 17:22
42

Edit: the rep stopped flowing (to any users who have earned above 200 today, I think). The linked user topped out at 1,270 rep, another at 1,900. Probably the recalc is on the way? (eeeek!)


The upvotes on examples don't count towards the cap :D not that it is bad, just saying.

https://stackoverflow.com/users/69875/jonathan?tab=reputation

26
  • 31
    Aside from this mistake, should reputation for documentation be separate from the main site?
    – 2501
    Commented Jul 21, 2016 at 12:33
  • 10
    @2501 shhhh... who doesn't want to rake in easy rep for being an early user of documentation?
    – RGA
    Commented Jul 21, 2016 at 12:34
  • 35
    @RGA I don't think it is fair. Just like edits on the main site give +2, an edit on docs shouldn't give +10, etc.... Just separate it, where's the harm? Users will still go for it even it is isn't a main rep. Not separating it dilutes the value of main rep.
    – 2501
    Commented Jul 21, 2016 at 12:35
  • 151
    I think it's ridiculous that documentation upvotes earn you reputation. You create a documentation entry for the simplest topic ever and earn a bazillion rep. Slap in the face for everyone who's investigating questions thoroughly and getting +15 in the end.
    – reVerse
    Commented Jul 21, 2016 at 12:37
  • 1
    @2501 the edit itself being approved only gives +2. the +10 comes from subsequent upvote, although I have also addressed the unfairness of this in my answer
    – RGA
    Commented Jul 21, 2016 at 12:41
  • 2
    @RGA I know, but any approved edit puts you on the list, where every upvote is +10. I could literally go over every example, fix some indentation or similar and get +1000 at the end of the day.
    – 2501
    Commented Jul 21, 2016 at 12:42
  • 1
    @RGA I have an edit where I changed three characters and I got +10.
    – 2501
    Commented Jul 21, 2016 at 12:44
  • 3
    @2501 clearly "substantive" needs some redefining..... the intention of allowing all users to gain rep is to encourage people to edit others posts and add valuable information, definitely not to rep farm as seems to be the case currently
    – RGA
    Commented Jul 21, 2016 at 12:45
  • 1
    @MSeifert Some are already above 1.6k :D
    – nicael
    Commented Jul 21, 2016 at 13:19
  • 3
    @reVerse That's not really all that different though from certain questions in Q&A. For example, my highest-voted question on SO right now has netted me almost 4k rep just on its own, and it's really just an incredibly basic answer to a popular question.
    – Ajedi32
    Commented Jul 21, 2016 at 13:20
  • 3
    @Ajedi32 At least you're the only one who received the reputation. Currently everyone who contributed to the documentation receives +10 reputation. So fixing some typos in the documentation may lead to a big rep gain. ;)
    – reVerse
    Commented Jul 21, 2016 at 13:22
  • 1
    relevant twitter.com/Nick_Craver/status/756136754168684545
    – Braiam
    Commented Jul 21, 2016 at 14:43
  • 68
    It's official, SO rep means nothing anymore.
    – user3956566
    Commented Jul 21, 2016 at 14:48
  • 3
    The live on-vote rep cap check was incorrect and I have deployed a fix. We will be monitoring for any other issues before recalcing the users later today to bring everyone in line. We just don't want to do it twice if there's another issue.
    – Nick Craver Mod
    Commented Jul 21, 2016 at 15:56
  • 4
    Yeah nice. 500 rep for creating arrays. Even with the new 200 cap on documentation, rep is nothing worth anymore... Commented Jul 23, 2016 at 23:27
39

Four glowing dots on one screen page? That's just terrible, and doesn't convey any information.

18
  • 15
    Click 'em and they'll go away forever.
    – hairboat Staff
    Commented Jul 21, 2016 at 12:14
  • 5
    @hairboat I clicked them, went to another page, went back and they appeared again :(
    – Braiam
    Commented Jul 21, 2016 at 12:17
  • 42
    The glowing dots are very distracting. If you need to tell the user what to do then your UI is wrong
    – Liam
    Commented Jul 21, 2016 at 12:30
  • 3
    My thoughts exactly: "A lot going on and a lot to explain! I'm confused... :S" Commented Jul 21, 2016 at 14:18
  • This just reminds me of those awful hosting sites which have every other word show an ad on mouse-over.
    – CubeJockey
    Commented Jul 21, 2016 at 14:33
  • 4
    I found five glowing dots on one page. It's like an easter egg hunt, but with radioactive eggs. I don't know who ever thought this was a good idea.
    – Cody Gray Mod
    Commented Jul 21, 2016 at 14:37
  • 3
    Just click one and click Turn tips off. and they'll be gone.
    – gkubed
    Commented Jul 21, 2016 at 16:16
  • @gkubed, that's what I did. I wouldn't have (had to) if there weren't so many dots.
    – Kijewski
    Commented Jul 21, 2016 at 16:18
  • 2
    @hairboat, you don't seem to understand the problem. Nobody says that all the dots need to go. Just don't have so many on one page. Only display one radiating dot at a time. When you read it, then display the next, but never two at once.
    – Kijewski
    Commented Jul 21, 2016 at 20:36
  • 1
    Ah, I think that's different from what JGreenwell was describing. But definitely to be looked into. The bubbles were added after user tests showed us the interface needed to provide new users more guidance on where to start; maybe we swung too far in the other direction. Regardless we'll certainly give it some thought based on this feedback.
    – hairboat Staff
    Commented Jul 21, 2016 at 20:59
  • 1
    I don't think it's that bad. Because if you forgot something, you can click the question mark on the page and those dots will appear again, then you can choose which tip (dot) you want to see. Also, distracting dots seems great because it makes users want to clear them and thus read the tutorials. Even if someone dislikes it, it only shows once...
    – Nier
    Commented Jul 22, 2016 at 6:05
  • 9
    "The bubbles were added after user tests showed us the interface needed to provide new users more guidance on where to start" You badly misinterpreted the results of those tests, @hairboat. When user tests indicate that users don't know where to start, you don't start adding magic glowing dots and other handicaps—you redesign the interface so that it is more intuitive. That is the core of the problem here, that you have so many different widgets whose behavior is unintuitive that you need 4+ contextual help icons on a single page!
    – Cody Gray Mod
    Commented Jul 22, 2016 at 6:51
  • 1
    @CodyGray: The bubbles were not the only change made in response to those user tests. "You should have seen it before!" doesn't make the current UI less confusing, and your criticism can stand, but I hope it gives you a little more perspective and helps you decide not to flip the bozo bit on the UI team.
    – hairboat Staff
    Commented Jul 22, 2016 at 13:42
  • 1
    turn-off the tips (the '?' icon) and the you won't find the glowing dots anymore. Commented Jul 22, 2016 at 17:44
  • 2
    @Rakitić, I'd say "thank you" if that wasn't commented 10 times already. Please read the comments first if you want to engage in meta.
    – Kijewski
    Commented Jul 22, 2016 at 22:02
36

As requested by JNat, posting some unclear UI here as an answer (rather than opening a new question). I plan to continually amend this answer as more questions pop up, though I won't remove anything from it as they are answered. Feel free to add your own questions here.

Edit and review edits

The process of approving changes is a bit unclear. It seems, unlike review queues, that only one user is required to approve or reject an edit for it to take effect (though its possible there were other hidden "reviews" of the edit that I had not seen, either way, its unclear). Is this intentional functionality? Is there a reputation threshold for making these decisions?

Further, there is no way at the present to suggest an edit or simply edit a proposed change. I've already seen a few changes that are valuable, but contain typos or improper formatting, so they shouldn't be approved in their current state. However, the only way to make the required changes is to wait for the change to be approved and then make a subsequent change request to fix the errors. This system feels flawed to me, given that the incomplete change will, for a period of time, be the visible version on the documentation.

In addendum to the previous paragraph, it seems that if we approve a change and the user edits their post, comments disappear (this could be that they mark them as completed or something, unclear), and the "approval" buttons aren't returned to the reviewer, such that they can choose to approve or reject the subsequent edit to the change.

Another issue I have encountered is the automatic combining of edits within a topic. Say, for example, I edit one example in a topic, and while that edit is awaiting approval, another example is posted. I then edit the new example, but rather than being posted as two seperate proposed changes, both changes are combined into one. This creates a problem for reviewing the changes, as now if one of my edits is worthy of approval but the other isn't, the review needs to decide whether the benefit of the good edit outweighs the loss from the second edit. Further, in combination with an issue posed above, if someone were to vote for approval on an edit, and then I edit a new section, their approval of the first edit is carried into the second edit, which occured after their approval.

This is specific to comments on edits, why is there no ability to upvote a comment? This would be a very effective method to show consensus rather than having people comment below: "I agree with @user". Furthermore, comments seem to persist across redacted revisions of an edit, but only if you add a new comment will they show up.

Limits on reporting issues with topics

Why is there a limit of "improvement requests" on a particular topic/example. Especially in these early hours, there are tons of changes that need to be made. I understand how too many flags could become overwhelming, but it seems better to place all the changes there so that users can pick and choose the ones that they are best equipped to handle.

When a user "dismisses" an improvement request, does it disappear for all users or only for that particular user? Should there be a way of "answering" an improvement request that you feel is unnecessary, so that the request can be removed if the community deems the change unnecessary?

Citations and attributions

What is the best practice for adding citations? For example, I proposed a topic in Excel VBA that I know already has a very comprehensive answer on SO written by Siddharth Rout (it is linked to all the time and serves as a go-to location). What is the best way to add this information to documentation? It obviously belongs in documentation, but I don't want to just copy and paste his answer saying, meekly, "credits to Siddharth Rout." It's not specifically just an issue of "stealing" reputation, but I feel as though there should be a way to actually attribute the answer to Siddharth, since it was fully and completely his content.

Reputation

One concern with the current reputation distribution system is the fairness of distributing reputation to all users with "substantive" edits (how is "substantive" itself even defined??). This makes it very easy to "piggy back" on the work of others for reputation gains. While to an extent, it is a collaborative process, I feel like the reputation gain should be scaled to the size of a user's contribution, rather than being an even distribution of +10 per upvote. Any user could make an early "substantive" change with only a few small edits (but sufficient to trip the barrier), but another user who later makes a huge change, contributing a much larger amount of information, will gain the exact same amount of reputation for subsequent upvotes as the previous user. Thus, by sheer luck, users can unduly gain reputation through others' work.

Tag Overlap

How should tag overlap be handled? For example, we have a vba tag which covers everything related to the language, but also tags like excel-vba and powerpoint-vba. The distinction between those subcategories is essential, because many of the methods and properties, though similar, are substantially different, yet they still fall under the same syntax. I believe that the tags should remain separate, but perhaps for "general topics" that are true for powerpoint-vba and excel-vba, but covered by the vba tag, should be linked to the sub-tags, rather than repeated for completeness. Should some hierarchy be established among tags to make this sort of sub-attribution easier?


I apologize if I am using incorrect or unclear wording to describe the issues at hand, but given Documentation has only been live for a few hours, I'm not yet fully familiar with the vocabulary

4
  • 1
    I've migrated this thread to its own question here
    – RGA
    Commented Jul 21, 2016 at 13:35
  • 3
    Well it's official rep really means nothing anymore.
    – user3956566
    Commented Jul 21, 2016 at 14:49
  • @Yvette see my answer on this post. I think I coined an adequate way of describing it
    – RGA
    Commented Jul 21, 2016 at 14:51
  • It's confusing trying to figure out what (if any) the rep requirements are in documentation, especially since many aspects are different from the Q&A side. Yes, the privileges page shows some documentation privileges, but that doesn't talk about (that I can find) who is eligible to review edits, if you lose rep for downvoting, etc.
    – Troyen
    Commented Jul 22, 2016 at 18:44
26

Showing "Awaiting approval" is not really correct. I agree it's nice to be positive, but the proposed change could also be rejected.

I suggest to change it to "awaiting review".

23

Please implement some type of version control mechanism. Something like Commit > Pull > Push

Otherwise edits are running over each other. For instance, me and some other user edit the same example at the same time. We both put a lot of effort and both edits are fine. If my edit will be approved first, then the other users edit, in order to be approved, will have to delete everything I've done. Or if it will be rejected, everything they've done will be deleted.

1
21

I can upvote / downvote my own example ... and the first time I do it I get a badge!

Example for bug or feature

1
14

Can't see the breakdown of reputation per example, shows somewhat funny error:

That's this user.

7
  • how much reputation does it say you have? On your SO it shows 6,097 and in your reputation I don't see them 1660 points for today... Commented Jul 21, 2016 at 14:25
  • @mar That's not my reputation tab.
    – nicael
    Commented Jul 21, 2016 at 14:26
  • @mar This user.
    – nicael
    Commented Jul 21, 2016 at 14:27
  • 2
    HOLY MOLY! (thx) Commented Jul 21, 2016 at 14:28
  • 1
    @mar Looks like the reputation is going to be recalculated and they will lose those those reps... At least no more rep flows in.
    – nicael
    Commented Jul 21, 2016 at 14:31
  • This UI was really intended to work with posts, I've just given it a dose of documentation loving and it will be building out in a few minutes.
    – Nick Craver Mod
    Commented Jul 21, 2016 at 20:37
  • @Nick Thanks for that! Could you also address this bug?
    – nicael
    Commented Jul 21, 2016 at 20:38
14

https://stackoverflow.com/help/documentation-notifications says:

Notifications are available at three frequencies:

  • Immediate
  • Every 3 hours
  • Once a day
  • Once a week

So that's four, not three frequencies.

1
  • 4
    I had to really dig to find the root cause here, but we're pushed a fix.
    – Nick Craver Mod
    Commented Jul 21, 2016 at 20:38
13

I downvoted an example with syntactically incorrect code, and it asked me why, but only offered radio buttons.

Then I saw I could "request improvement", where I could actually provide a reason why it was wrong. After I typed in the reason and clicked "Request Example Improvement", it then said I couldn't submit that because I'd already complained (paraphrasing, obviously).

(After lunch I came back and edited the example myself.)

If the radio buttons do effectively correspond to the request improvement options, the opportunity to provide a reason should be made available then, and you should disable or immediately warn when an option won't be accepted.

12

"Versions" section Feedback

I was creating my first "Versions" section just now. I saw the grayed out / placeholder text for the format.

First feedback: give me an option to inject that example or something similar. I now made a screenshot and then kept that side by side while creating the post :scream_cat:.

I decided to put some extra effort in, because it seems helpful to have a few notes for some releases to help people "spot the right one". So I used this markup:

 | Version     | Release Date | Notes
 | ----------- | ------------ | ----- 
 | [3.4.0][1]  | 2015-11-17   |       
 | [3.3.0][2]  | 2015-02-18   |
 | [3.2.0][3]  | 2014-08-12   | Introduced `component` binding 
 | [3.1.0][4]  | 2014-05-14   |
 | [3.0.0][5]  | 2013-10-25   | See also: [upgrade (from 2.x) notes][6]
 | [2.0.0][7]  | 2011-12-21   |
 | [2.3.0][8]  | 2013-07-08   | Last 2.x release
 | [1.2.1][9]  | 2011-05-22   | Last 1.x release
 | [1.0.0][10] | 2010-07-05   |

Which previewed nicely but gave me this upon submitting:

error about table format

So I changed it to this:

 | Version     | Notes | Release Date 
 | ----------- | ----- | ------------ 
 | [3.4.0][1]  | | 2015-11-17          
 | [3.3.0][2]  | | 2015-02-18   
 | [3.2.0][3]  | Introduced `component` binding | 2014-08-12
 | [3.1.0][4]  | | 2014-05-14   
 | [3.0.0][5]  | See also: [upgrade (from 2.x) notes][6] |2013-10-25
 | [2.0.0][7]  | | 2011-12-21   
 | [2.3.0][8]  | Last 2.x release | 2013-07-08
 | [1.2.1][9]  | Last 1.x release | 2011-05-22 
 | [1.0.0][10] | | 2010-07-05   

Which actually works:

rendering of previous code block

But that doesn't look as nice IMHO. So:

Secondary feedback: allow the Versions table to have multiple extra columns somehow, preferably keeping Version and Release Date columns together.

12

Feature Request

It would be nice to have a meta-topic within the documentation for each of the tags where users could suggest and vote on best practices and standards for the examples/topics in that tag. (Like meta votes these would confer no reputation.) The topic would be linked to the tag's dashboard, and could be optionally linked in the "Create Topic" UI. This would allow:

  • Tag-specific guidelines to be developed such that each tag's documentation can be internally consistent.
  • All users to weigh in on the merits of each suggestion through the tried-and-true method of voting up and down.
  • Engagement with the users who cannot or will not go to chat
  • Presenting best practices for each tag's documentation in an easy-to-browse way. (At least easier than searching through the chat's transcript.)

A couple examples:

  • : Don't introduce multiple concepts in an example. In an example that uses design pattern X, don't also use design pattern Y. [Replace X and Y with whatever patterns apply]
  • : Wherever possible, include links to the canonical/official documentation. [like MSDN, python.org, the iOS Developer Library, etc.]
  • : For basic language features (inheritance, explicit interface implementation, etc), avoid using the new lambda-bodied method syntax [snipped discussion of why...]
  • : Prefer the use of NULL over nullptr for examples, so that they are valid in C as well as C++.
  • : As much as possible, examples should conform to the PEP-8 style guide.

Note that these examples are just that, not a suggestion that they should be the ruling conventions for their respective tags.

Meta Note: I've made this post CW, so feel free to add clarifications or tweak the idea. (As long as the general thrust of the suggestion remains, obviously.)

1
10

It needs to be clearer what happens if there are two conflicting edits to docs.

If I create a topic and someone else creates a topic, and both drafts are approved, what happens? Does the order of approval matter?

If Person A fixes a spelling error and Person B completely rephrases the example that contained the spelling error, which change is incorporated?

6

The real benefit will come when a question can be closed as “read the docs” with a pointer to the docs, and maybe a few lines explaining how the docs answer the questions. At present we are creating documentation for the sake of it…..

We are also creating documentation that is often of a lower quality then what is already out there on the internet for the given topic, this is hard to solve without becoming a “link farm”.

4

The version system is too restrictive on dates. Neither the Haskell 98 Report nor the one for Haskell 2010 have an actual day of the month written down anywhere I can find, but the site only lets me enter YYYY-MM-DD formats.

Also, there should probably be some way to distinguish between specification versions and implementation versions and express "Foo 2.4 implements Bar as specified in the Bar 1.1 Report."

2
4
  1. Clarify how topics are sorted/presented.

Prime example: Java Streams. "Introduction to Streams" is the twentieth topic on the page. Yes, that topic currently has issues, they can be fixed. It's discoverability cannot (not for the current implementation of docs).

  1. Move "Syntax/params/remarks" from the very bottom of the page somewhere people can actually see them
3

Possibility to move topic request to another tag

SO Documentation is great, but I just have come accross a case that can be added in the future. I created a topic request in a tag (iOS) and someone comment it to said it could belong to another tag (xcode).

It could be usefull to be allowed to move the topic request to another tag to avoid deleting and recreating the topic request (and losing all votes on it too). This could be a request that will be handle by a moderator to avoid problems

1
  • I'd like to flag Synonyms as well.I've seen a Synonym of Selenium-WebDriver suggested WebDriver. Possible flags: duplicate, merge,
    – lloyd
    Commented Jul 27, 2016 at 7:56
2

I just looked around a bit and saw, that I could dismiss a proposal. I clicked on dismiss (topic "CORS" on "C# Language", https://stackoverflow.com/documentation/c%23/topic-requests/1328), because I would expect that to be off-topic. It would be okay in ASP.NET[-MVC], but it's out of scope for c#.

I'd expect there to be an "Off-Topic" reason in dismiss and some sort of "move to another documentation area".

1
  • 2
    And we should try to avoid the C# bias that already exists in the Q&A. Specifically, there's already C# topics that should be under .NET (and with the multi-language feature when it becomes available).
    – Mark Hurd
    Commented Jul 22, 2016 at 15:13
2

This is dumb.

enter image description here

Why is it dumb?

  1. Because I have a ton of experience working with the tech, but since I've never answered questions on SO about Moq, I can't get help write docs for it. I thought the whole point was to let people contribute to the cause in their own way? Why should I have to have answer a Q&A to commit to helping with Documentation? It feels like the coupling between Q&A and docs is far too tight right now.
  2. I'm not the only one, which has resulted in a request for it under .Net, where it just doesn't belong.

I'm really concerned about how all of this is going to end up being organized, or rather, the lack of organization that is occurring right now. It looks like the wild west.


This is even dumber.

The traffic is too low to create documentation.

https://stackoverflow.com/documentation/libgit2sharp/commit

Here is a relatively popular open source lib, with admittedly poor documentation, and yet we can't create documentation for it here. What's the point of this new feature again?

21
  • 2
    We're currently seeing massive quality problems in Documentation contributions; this is probably in response to that. One positively scored answer in a tag seems like a super easy requirement.
    – Pekka
    Commented Jul 24, 2016 at 17:13
  • 2
    Easy requirement @Pekka웃 ? Yes. but why is it necessary for someone who does not wish to participate in Q&A? because I don't. Haven't for a long time and I'm not alone, but I would very much like to participate in Docs. There really isn't a good reason to tie the two sections of the site together as they are now.
    – RubberDuck
    Commented Jul 24, 2016 at 17:15
  • Because it's the only half-way serious measure of competence that we have. Can you think of a better one? In fact, requiring only one upvote seems way too little.
    – Pekka
    Commented Jul 24, 2016 at 17:19
  • 1
    @Pekka웃 do you use Wikipedia? They require no proof of competence at all. At the end of the day, but what is Docs if not a wiki for programmers?
    – RubberDuck
    Commented Jul 24, 2016 at 17:20
  • 1
    Wikipedia has a mature peer review system. Documentation, at this stage, does not. Try viewing this from a greater perspective; read on Meta about the loads of quality problems it has right now. Just because the requirement is inconveniencing you in a way that doesn't make any sense to you (understandably) does not automatically mean it is a bad idea.
    – Pekka
    Commented Jul 24, 2016 at 17:22
  • 1
    And it's a fundamentally wrong headed idea that preventing people from contributing prevents quality issues from happening @Pekka웃. Have you seen the main site lately? Obviously, it's not working.
    – RubberDuck
    Commented Jul 24, 2016 at 17:24
  • Not sure what you mean - asking questions seems the biggest quality issue on the main site, and last I checked it did not come with a reputation requirement. Neither did answering. Anyway, it's pointless to discuss this any further. You think it's an awful idea, I think it's still way too soft a requirement - although I see that excluding a proven member of the community because of lack of tag answers doesn't make sense in your case. A general minimum rep for participation might be a better idea.
    – Pekka
    Commented Jul 24, 2016 at 17:25
  • 1
    It's absolutely worth discussing @Pekka웃. Here we are, two sets of users with opposing view points. We both want to use this site. Where's the compromise that makes this experiment work for both of us?
    – RubberDuck
    Commented Jul 24, 2016 at 17:27
  • One compromise might be you answering a question or two in the moq tag and receiving an upvote before long. :)
    – Pekka
    Commented Jul 24, 2016 at 17:27
  • Maybe, but like I said. I'm a user with zero interest in Q&A. How do we make docs work for folks like me?
    – RubberDuck
    Commented Jul 24, 2016 at 17:29
  • 1
    And now we're onto something. How can the peer review system be improved to a point where it's not necessary to participate in Q&A? (Not really asking. Just being a bit Socratic)
    – RubberDuck
    Commented Jul 24, 2016 at 17:56
  • 2
    @NicolBolas I'm active elsewhere on SE and used to be involved in Q&A here. I see docs as an opportunity to help do something I enjoy and help some people in the process. There is going to be a subset of users like me, who only wish to participate in docs.
    – RubberDuck
    Commented Jul 24, 2016 at 21:10
  • 3
    I don't see a damn thing wrong with people wanting to participate on Docs and not on Q&A. If there are a lot of them, though, it's definitely an argument for separating the rep.
    – jscs
    Commented Jul 24, 2016 at 21:14
  • 2
    @NicolBolas exactly. There is no way to know that currently. That doesn't mean there shouldn't be a Document only mechanism for this.
    – RubberDuck
    Commented Jul 24, 2016 at 21:55
  • 2
    Default should be allow creation; with continuous bad quality documentation from that specific user remove their ability to create content. With a % downvote threshold. Commented Jul 25, 2016 at 10:00
1

So one thing I'm noticing, for me at least, is that for a proposed changes/reviewing of new examples, I can't see what other reviewers might have commented, and I can't change my approve/reject status. Other reviewer comments is could be very important, and perhaps can cause me to consider other things which would make me reject the example.

Perhaps I just am missing something that is right there in plain sight, but it doesn't seem to be.

0

It appears that Documentation is very slow when the editor is open. Brings all major browsers on my PC to a grinding halt.

The halt occurs almost immediately after the editor appears. After about 10 seconds or so, the page comes back to life, and then freezes completely again.

I'm having to use a Markdown editor to do my edits, etc., and then paste them back into the SO editor. Even then, it's quite a tedious task.

What is making the editor hold the browser process up?

(Note: This is especially bad in FF, as e10s multi-process is not available on the stable branch.)

0

So I spent half an hour writing something up. I clicked "Submit to Review" with nothing visible happening; repeating showed some message along the lines of "no draft selected in workbench" which I couldn't understand. What workbench?

After navigating away, my text seems to be gone (other than everywhere else on SE where drafts reappear when you go back in the browser history).

Nope, not doing that again for some time.

0

The biggest mistake Documentation has is ignoring completely the Q/A base we already have.

Why "post your sample and explanation" instead of "adding this question/answer to"?

It feels so different. I can see great potential, but I am not sure is it:

  1. replacement of existing tutorials
  2. local sample base to use as RTFM in Q/A
  3. msdn/whatever else replacement.

Right now I refuse to contribute, because I don't feel I can. I know something, but there are John Snow, Bill Gates, John Smith, WhoElseWroteBookOfC#IForgot. Do you want me to write documentation for people more dumb (knowing less) than me? It's basically "common someone write something" game.

It's just wrong.

I'd expect it to be an addon to Q/A. Something what make Q/A experience better. Currently it feels like a complete replacement (in some way): "Let's forget about Q/A and start from very beginning".

-5

Enable Documentation in pt.stackoverflow.com so that we can have Documentation in portuguese

Since Documentation is a /documentation under stackoverflow.com, are you planning on making it available for pt.stackoverflow.com too?

1
  • 7
    Let's wait and see how it plays out in English first. It's far from finished there. No point in adding another language in the mix
    – Pekka
    Commented Jul 24, 2016 at 17:14
-9

I want to add my point my point: have a tag for users who are studying from book so that they can learn from others and easily understand their mistakes. This makes it easier to find simpler problems and prevent copies of the same question and will allow the right answer for the user to understand

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