47

The apparent foundation of Docs.SO is the belief that examples are more important than text. That seeing an example communicates better than words.

There appears to be a general misunderstanding about how Docs.SO is designed to work. Right now, we have lots of people with their own idea of what the concepts of "topic" and "example" mean.

If examples are indeed a better way of communicating, then I would like to challenge the designers of Docs.SO. Go into the various tags and post links to topics that represent exactly how Docs.SO is supposed to work. Others can do that too, but I would be curious to see what the people behind this site's design think about the documentation currently available.

Give us an example of superlative Docs.SO-style documentation.

3
  • 1
    Ties in with my suggestion of going through some sort of presentation/test of the good the bad and the ugly before unleashing the masses on creating and approving crap
    – charlietfl
    Commented Jul 24, 2016 at 14:37
  • 25
    So basically, do what should have been done during the private beta? Sounds reasonable.
    – Cody Gray Mod
    Commented Jul 24, 2016 at 14:55
  • Honestly, this seems like something that will emerge as the community matures around documentation.
    – Ant P
    Commented Jul 26, 2016 at 8:34

2 Answers 2

13

Our SRE Team has been using Documentation since early in the private beta to host usage exmples of Bosun, their open source monitoring system. I personally found the introductory topic helpful for setting up a Bosun instance on my machine. (I'm experimenting with several site metrics that may help us keep track of our network. It's on a back burner at the moment.)

A few things I appreciate about their efforts:

  1. The SREs started dogfooding Documentation on their own. They figured out how to create useful examples and organize by topic without us providing any hints. Both during the private and public betas, they've used public channels (mostly meta) to get support and report bugs.

  2. Bosun's official documentation is hosted on their site. There's no plans on moving that content. Instead, the examples hosted on Stack Overflow augment the canonical documentation.

  3. The team makes used of Requested Topics and Improvement Requests to plan publicly and give the community space to contribute. There's even been an edit can from outside their team.

  4. Topics range from 1 to 7 examples. There aren't any kitchen-sink topics (though Notifications might be a bit broad). Some topics eschew Syntax, Parameters and Remarks when they don't add anything. The examples themselves get to the point quickly and avoid unnecessary explanation. They assume you already know the basics of using Bosun and link to more detailed documentation when it would help the reader.

This is a great example of how a small project can make use of Documentation to supplement other resources. In fact, the best uses of the feature seem to be the smaller Stack Overflow tags. I think the problem with big tags at the moment is everyone is kicking the tires in tags they know well. It's perhaps an example of Parkinson's law of triviality.

25
  • 6
    You name this as "a great example of how a small project can make use of Documentation". Is Docs.SO supposed to be used by projects or teams? This is not what I see right now. Most tags are contributed to my many different people that are in no way related or work together as a team or project.
    – user5547025
    Commented Jul 26, 2016 at 7:44
  • 3
    s/tags they know well/tags they think they know well/
    – BoltClock Mod
    Commented Jul 26, 2016 at 7:46
  • @Full Name: Those are the "big tags" alluded to in the last couple of sentences.
    – BoltClock Mod
    Commented Jul 26, 2016 at 7:47
  • @FullName: My guess is that tags will follow a power law with a small number of very popular tags aborbing the majority of contributions. But the really interesting stuff will be going on at the long end of the tail. Unfortunately, that content is far less visible than Java and C#.
    – Jon Ericson Staff
    Commented Jul 26, 2016 at 7:52
  • I see. The problem right now is that the "big tags" are prominent on both the Docs.SO start page and, of course, the list of SO questions tagged with them. So Docs.SO will attract more of this questionable controbutions instead.
    – user5547025
    Commented Jul 26, 2016 at 7:53
  • @FullName I think the disconnect here is, it's not a mutually-exclusive thing. Individuals AND teams (or, basically anyone) can use it. I could use it to write more real-world examples to augment PHP's manual, and so could PHP if they wanted to. The audience isn't granularly defined because it's simply "anyone that wants to contribute something".
    – user50049
    Commented Jul 26, 2016 at 7:53
  • The original question was for the SO team to show good examples. This discussion makes me think that good usage of Docs.SO will not be found in the Java or Python tags, for example. Again it seems that SO is more about quantity instead of quality.
    – user5547025
    Commented Jul 26, 2016 at 7:55
  • I think some of the Python Topics are pretty good, if a bit wordy. The map examples taught me something as a novice to the language. Other then excessive length, quality of the final content seems to be trending up, though I certainly understand not being able to see that while entrenched reviewing unproductive "Hello World" bikeshedding edits.
    – Jon Ericson Staff
    Commented Jul 26, 2016 at 8:06
  • 8
    This is a good start. From the example we've been given, Docs.SO is meant to work best when: 1) Examples are just code with maybe a blurb or two of text. 2) Example code can be short, so APIs that are long-winded need not apply. 3) There is existing external documentation which can explain the details of the code. 4) Examples should assume the reader is familiar with the system being used. 5) Everything is written by a small cloister of people who know each other and agree on how it's supposed to work. Am I understanding things correctly? Commented Jul 26, 2016 at 17:09
  • 4
    @JonEricson: "But it's necessary to have systems like reputation in order to have a real community." Wikipedia shows that it is not necessary to have that system be an algorithm. Wikipedia's equivalent to reputation is very ad-hoc rather than algorithmic. There are no numbers; privileges in Wikipedia cannot be gained automatically. They only come via human review. You can play politics in such a system of course, but you cannot automatically game it the way Docs.SO rep can be. Commented Jul 26, 2016 at 17:47
  • 1
    @NicolBolas: It's not purely a question of having short examples, per se. Rather the question is "Can someone who wants to use the API absorb the example in a reasonable timeframe?" So many topics with lots of activity end up with rambly explanations and multiple, unrelated code blocks. That's stuff would have happened no matter the motivation. People want to work on Docs because it's new and rewarding. Eventually this feature won't be new anymore.
    – Jon Ericson Staff
    Commented Jul 26, 2016 at 17:57
  • 1
    This is just never going to work in C++, then. There's no way to make the examples "simple" enough. You omit details and the community will freak out because it isn't precise enough. It really only seems to work for small, simple APIs. There's no way we're going to document Win32, HTML, CSS, C#, Java, etc. You say people are moving to document these because of Parkinson's law of triviality, but I don't think that's true at all. People are moving to document these because they are what they use the most. Sure, they know 'em the best, but they also think they're the most useful to document.
    – Cody Gray Mod
    Commented Jul 27, 2016 at 0:55
  • 1
    You are going to have to make massive changes in the system to discourage any attempt to document common languages and APIs. Not that I think that's a bad thing. Most of those are already well-documented elsewhere, and would not benefit from having that documentation "ported" over to Stack Overflow and separately maintained. My radical suggestion would be to simply disable Documentation for the biggest of tags. (By a human, of course, for sanity reasons.) With the proposed upcoming changes like the addition of a review queue, documenting smaller tags will actually work.
    – Cody Gray Mod
    Commented Jul 27, 2016 at 0:57
  • 2
    Reading some of the comments, you say "the real problem is that people naturally prefer completeness to the detriment of clarity...we need to make sure the community has the tools to curtail bikeshedding. It took years to get that stuff right (or rather, better) on Q&A." But those have nothing to do with one another! Q&A encourages completeness because there are no artificial restrictions on length. All the good, top-rated C++ answers are exceptionally complete, even though they take take time to digest. This isn't simply bikeshedding. You fundamentally misrepresent programming as easy!
    – Cody Gray Mod
    Commented Jul 27, 2016 at 1:01
  • 1
    I've read it several times, and come back on a couple of different days thinking it might just be my mindset, but I honestly cannot make sense of your last comment or what it has to do with my representation of your statements. So you asked a question on SO that was "too broad". What is the relevance of that? It is not too broad because of the complexities of the language and the difficulties in distilling those down into simple, easy-to-digest examples, which is what I was talking about. And it doesn't appear to be something that you'd cover on Docs, either.
    – Cody Gray Mod
    Commented Jul 30, 2016 at 14:18
2

The reason that we didn't give a whole ton of guidance on what to create and how to organize it is because you, as the largest group of developers on Planet Earth are a lot better at figuring that out together. We're here to help guide it, but we need to see how you actually want to use it, and work to support the best use cases.

Tim Post, Director of Stack Overflow Communities in this answer


Having made and reviewed a lot of examples, an also from experience in chats with the community, personally I give you these advices:

  • If there is a tag that is more directly related to the topic/example, it should be there instead of where it is, e.g. DOM is an API used with JavaScript, all the DOM specific examples and topics should be in the DOM tag. (Of course they're not..., they're all in JavaScript)
  • A topic should be created only if the topic can be covered in more than 3 to 5 examples, if not, the examples should be moved into a broader topic (that should be created if it doesn't exist)
  • There shouldn't be duplicated content between examples/topics in the whole site, content should be linked, not duplicated.
  • If a topic contains more than 20 to 30 examples, it should be split into 2 to 4 different topics.
  • Features not basic to the tag being documented that are referenced to or used in the example should be linked. Not everybody know everything.
  • If you are splitting your example in sections (e.g. 4 titles with their respective code and prose), take each of those sections and make different examples.
  • If your example is more than two screens long, review it, remove too specific information, search for already documented information and link to it instead of duplicating it, and if all that fails, split it into two different examples if possible.
  • If the user can't see a code snippet after 0 to 15 lines of prose, you're doing something wrong.
  • If the edit doesn't follow coding conventions only link to those conventions in comments if it's very good, otherwise also reject it.
  • If the edit has typos, comment on those typos so the user that made it can retract the draft and make the proper corrections, don't reject it!
  • If an edit or example is not grammatically acceptable, but the code is pretty good, approve it, and then edit it if you want. Not everybody speaks english perfectly.
2
  • 3
    "covered in more than 3 to 5 examples" Perhaps you mean fewer than. "If your example is more than two screens long, review it, remove too specific information, search for already documented information and link to it instead of duplicating it, and if all that fails, split it into two different examples if possible." Then I guess Docs.SO is never going to work with Vulkan. You can't even create a shader with less than 2 screens of code... Commented Jul 27, 2016 at 0:44
  • @NicolBolas no, i think topics should have more than 3 to 5 examples, if not they're not broad enough to be considered a topic. If you understood something else, i might have to rephrase that. Of course there will be exceptions, the idea is to give guidance, not strict rules. Commented Jul 27, 2016 at 0:46

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