207

I'm familiar with C# / .Net so I naturally tried to see what was available for those tags.

Currently it just looks like a bunch of random topics:

enter image description here

The dashboard doesn't help either.

Then I tried to navigate through the doc a bit, 70% of what I found seems pointless to me. The currently top-voted .Net topics are useless "Hello world" examples in multiple langages without any explanation:

Bunch of hello world examples

There isn't even a page that defines what is .Net, and that it supports those multiple languages.

So what is the point of Documentation?

Then there is the fragmentation issue. Again. This time it's within the Documentation stuff itself. Here's the "Hello World using .Net" topic on the C# tag.

While this one is clearly more useful, why those duplicates?

20
  • 135
    "Currently it just looks like a bunch of random topics:" That's how it's supposed to look. That's how Docs.SO works; it's an unorganized grab-bag of random factoids. That is by design. The makers of this project are under the impression that what the Internet is really lacking is peer-reviewed documentation that has absolutely no structural organization. So that's what we've got. Commented Jul 22, 2016 at 15:38
  • 97
    Calling it "peer-reviewed" makes it sound like it has scientific level quality. Instead it gets reviews by rand knob, who just earned couple points by answering "undefined variable" questions.
    – tereško
    Commented Jul 22, 2016 at 15:47
  • 16
    @NicolBolas but not being able to organize also seems to lead to a considerable amount of topic duplication from what I've seen so far.
    – charlietfl
    Commented Jul 22, 2016 at 16:13
  • 16
    @charlietfl: Yes. It also leads to it not being particularly useful or discover-able. Or any number of things. But the Powers That Be have made it abundantly clear that this is what they want. Commented Jul 22, 2016 at 16:15
  • 34
    Rand Knob for president. Commented Jul 22, 2016 at 21:09
  • 9
    Give it time. It will evolve.
    – Hack-R
    Commented Jul 22, 2016 at 21:22
  • 3
    That aside, why someone had the urge to document all C#6 features...
    – Braiam
    Commented Jul 22, 2016 at 21:22
  • 31
    @Hack-R: Evolve into what? It's been less than 2 days and the C++ tag is already quickly degenerating into garbage. cppreference.com is and always will be a far better resource because it doesn't have all of those "minimal, viable, complete examples" getting in the way of the genuinely useful information. Not everything of worth is something you can copy&paste. Indeed, not most information can be distilled down into that. Commented Jul 22, 2016 at 21:28
  • 21
    @Braiam: "That aside, why someone had the urge to document all C#6 features..." Because it gets them rep. Commented Jul 22, 2016 at 21:28
  • 8
    @NicolBolas It's degenerating from nothingness into garbage? That doesn't really make any sense. It will evolve into a useful resource as more and more people review the content, edit, prune, and contribute. 2 days isn't very long. How do you think StackOverflow Q&A looked after 2 days?
    – Hack-R
    Commented Jul 22, 2016 at 22:01
  • 7
    @NicolBolas "Evolve into what? It's been less than 2 days..." - precisely. If instead of complaining about the lack of quality content after a mere two days, people spent their time contributing, then things could quickly improve.
    – Myridium
    Commented Jul 22, 2016 at 22:01
  • 19
    @Hack-R: "It's degenerating from nothingness into garbage? That doesn't really make any sense." First, I was in Docs.SO beta, so I know what the state of the documentation was before then. Second, yes, nothing is better than garbage. Just like you would prefer your house to be empty than to be filled with trash. Also, time is not going to make Docs.SO better; it's main problems are organization, not (just) the quality of any particular facts. And organization isn't going to improve. Commented Jul 22, 2016 at 22:16
  • 34
    @Myridium: I don't dismiss your opinion just because you haven't actually contributed as you say that I should. I dismiss it because it is based on ignorance. You dare to claim that the reason so much crap is happening is because we haven't tried hard enough to stop it, when in actual fact I had literally done all that I could to slow the tide. How dare you make such a claim founded in brazen ignorance, then try to hide behind "race, sex, background," as though your opinion was being dismissed due to your rep rather than your lack of any real knowledge of the problem. Commented Jul 22, 2016 at 23:48
  • 6
    @NicolBolas - Pretty sure I'm not hallucinating when I read "someone who has only contributed 4 things to Docs.SO should keep their opinions about the matter to themselves". Anyway, you have misunderstood what I said. My point was, as Hack-R was saying, that it is early days and it seems silly to jump to the conclusion that the whole thing is crap when it's only just been released in public beta. I have faith that as people contribute, the quality of Documentation will climb. I never said that you or anyone else was the reason for the crap, or that you should be trying harder to stop it.
    – Myridium
    Commented Jul 23, 2016 at 2:12
  • 6
    What if you're just not using it as it should be used at the moment? I'm not sure browsing through the site is the common use case for documentation (any documentation). If I'm a developer and I'm running a google search for some topic in a specific language, I will soon find SO documentation somewhere at the top, and the link will direct me exactly to where I should be reading. This is how SO has worked so far, no reason to assume it won't work from now on. Commented Jul 25, 2016 at 7:24

11 Answers 11

135

Not only that. Go into a topic. What you see? 20 different topics.

If you scroll all the way to the bottom you suddenly arrive at Syntax, Parameters and Remarks.

Wait. What? Isn't that supposed to be somewhere closer to the top? Or somewhere where they can be found?

As to random topics. yes, it's a nightmare.

Look at docs for Java Streams for example. I invite you to find the "Introduction to Streams" topic.

Yes, "Documentation is all about examples". It doesn't mean "a random unmanageable unsearchable pile of examples" ;)

14
  • 9
    I'll see your Java Streams and raise you std::string. At least Streams actually has an introductory example, which could be pinned to the top. Commented Jul 22, 2016 at 21:35
  • 6
    As I'm digging into more discussions (like your answers/comments or the entire discussion here meta.stackoverflow.com/questions/315160/…), I'm starting to see what and actual nightmare this is :(
    – Mamut
    Commented Jul 22, 2016 at 21:37
  • Is there a way to reorder the topics? I also find it annoying that introductions tend to get shoved to the bottom. Commented Jul 22, 2016 at 21:42
  • 5
    most people at SO aren't complete clueless about their language of preference, that's why introductory threads will never rise to the top: users don't use them. Commented Jul 22, 2016 at 22:51
  • 8
    @catastrophic-failure: that may be true for 'us', early readers of Documentation, but not for "most people at SO" itself - which should be an important demographic target of this Documentation.
    – Jongware
    Commented Jul 23, 2016 at 9:25
  • 3
    @catastrophic-failure that's a terrible assumption. A bit like anyone who buys a new TV should already know how a TV works so shouldn't need an overview where the controls are. If I delve into a language or library that I've never used wouldn't I want an overview first?
    – charlietfl
    Commented Jul 23, 2016 at 14:59
  • @charlietfl How many are doing that at SO? Most people come here after learning the ropes of their language of choice, they won't bother with the introductory topics at all. Commented Jul 23, 2016 at 21:20
  • How many are doing that at SO... or... How many are doing that on the internet in general? Is Documentation for SO users only? I'd also think that SO users would also want structured documentation instead of a mish-mash of purely structured examples. Oh, wait. SO users do want that (see SO users: me, orccrusher99, Nicol Bolas...)
    – Mamut
    Commented Jul 23, 2016 at 22:25
  • 3
    @Mamut we are talking about two unrelated things: I'm talking how, under the SO system, introductory topics won't ever rise to the top. You are talking about how a minimal structure, prioritizing introductory topics, is more desirable. Commented Jul 23, 2016 at 22:58
  • 1
    "Introduction to Streams" was deleted because it wasn't an actual example. It belonged in the Remarks section, or needed to be broken up into smaller examples. Remember that it's all a work in progress. Commented Jul 24, 2016 at 1:35
  • The issue is that Remarks don't earn rep like examples do. Commented Jul 24, 2016 at 4:30
  • 1
    Whatever happened to "a topic has about 6 examples"?
    – tbodt
    Commented Jul 25, 2016 at 14:36
  • 1
    It gets even more interesting: I was just trying to review someone else's edit, and had to give up. There was a big deletion, and the edit comment said they were deleting duplicate content. I'm all for that, and have no reason to doubt the editor… but I couldn't figure out whether the duplication was on the same page or a subtopic in some overlapping topic's page or what. So these subtopics can make it hard to find something, and can also allow duplication, and can make it tricky to review edits
    – henry
    Commented Aug 2, 2016 at 21:40
  • @catastrophic-failure I believe this is the same issue.
    – Mamut
    Commented Aug 4, 2016 at 7:28
119

I agree. I poked around my favorite tags and it was/is a mess.
This is not documentation; it is a semi-random grab bag of "examples".

Call me old fashioned, but I was looking for:

  1. An overview. Ideally a one paragraph "elevator pitch". With, maybe, optional hyperlinks for more detail.
  2. A table of contents with some kind of logical organization.
  3. Articles and examples on key topics and/or typical scenarios.

So far, I'm not seeing how to make this beta useful, either to myself or to some beginner -- especially in a way that's not already covered by the existing Q&A or by off-site resources.

7
  • Agreed. I've always felt that PHP does a decent job with their docs. Succinct, simple, to the point. The examples could use a bit of help, but SO's documentation is essentially the opposite.
    – j08691
    Commented Jul 24, 2016 at 1:32
  • 12
    I agree with the elevator pitch idea 100%. There just needs to be an incentive to fill out the non-example parts of the documentation, because currently all the rep is in the examples, and it's screwing up the format. Commented Jul 24, 2016 at 4:20
  • Exactly. This is why I like Java's documentation, except for their lack of examples (but I find that the oracle tutorials work fine for that when necessary)
    – Justin
    Commented Jul 24, 2016 at 5:40
  • I'd upvote this a hundred times if I could. I thought it was just me.
    – TarkaDaal
    Commented Jul 25, 2016 at 10:44
  • 3
    "Elevator pitch" is extremely needed. It is all about examples, OK, but what if I cannot figure out what the examples are for? Commented Jul 25, 2016 at 14:00
  • Like it is now, most of the people coming in for learning something cannot understand what is going on. They will not learn C#. Instead, they will just find the "correct" topic (say, how to read a file), copy paste, job done. Dispose? pff, another topic. Encoding? Async? Streams? Commented Jul 25, 2016 at 14:03
  • I agree; unfortunately the "elevator pitch" was previously shot down by staff when I and others brought it up during private beta and before. Some staff have mentioned being open to adding it or at least moving Remarks to the top as a solution.
    – TylerH
    Commented Jul 25, 2016 at 14:38
32

To me, a great place to start for establishing meaningful topics is with the language authority itself. For instance, C# Programming Guide on MSDN and The Python Tutorial at python.org.

Now, my understanding is that the primary goal of SO documentation is to provide a rich set of peer-reviewed examples. So, I think an effective strategy would be to use the topics established by the language authority as an outline, and then provide examples that go above and beyond the examples included in the language authority's documentation. To be of real value, the examples would cover common use cases. I think a great place to start to find these common use cases is to consult the top-voted questions for the associated language tag.

So, in summary:

  1. For each language, establish a road map of topics by consulting the language authority's documentation.
  2. Consult the language tag's top-voted questions as a basis for creating meaningful examples that address common problems in the real world of programming.

In contrast, to proceed without some kind of road map for each language/technology seems destined to lead to a result of questionable value.

For a question that expresses a similar sentiment, see More hierarchical structure needed for documentation topics. Also see this answer by Jon Ericson♦ for a counter-argument.

10
  • @Braiam My answer is a direct response to the OP's opening statement: "Documentation doesn't look good right now...Currently it just looks like a bunch of random topics..." If you can point me to a question where the approach I've offered has been previously debated, I'd welcome that. Also, are you perhaps suggesting that the OP's question is a duplicate?
    – DavidRR
    Commented Jul 23, 2016 at 0:55
  • @Braiam Actually, the essence of what I've advocated here has been suggested before in More hierarchical structure needed for documentation topics. A key sentence reads: "API related documentation should follow the structure of the official documentation tree and change as the official tree changes."
    – DavidRR
    Commented Jul 23, 2016 at 2:10
  • ...and in this comment to his answer, Jon Ericson♦ offers a counter-argument: "...I think we owe people a minimal hierarchy. What Docs offers might not be ideal, but it's a good place to start." (And actually, I see that Jon's comment is a response to you.)
    – DavidRR
    Commented Jul 23, 2016 at 2:18
  • I'm not sure what are you getting at... I was making a jab at what was Docs goal (supplement official documentation) and what it actually became (mirror badly the official documentation).
    – Braiam
    Commented Jul 23, 2016 at 2:21
  • 2
    @DavidRR: I don't agree with this idea. The reason being is that many extremely useful topics are not directly covered. Consider string manipulation. This is a task-focused activity; you use different tools based on different needs. In one case you might use simple string member functions. In another, you might break out regex. And so forth. Your way would make it hard for a user to find the various ways of manipulating a string, just because "regex" isn't necessarily specified in the same "topic" as "string" in the main documentation manual. Commented Jul 23, 2016 at 2:52
  • 1
    @NicolBolas Yes, indeed. While my answer focuses on languages, there is another critical aspect of programming that it does not specifically address: the class library. For instance, .NET Framework Class Library and The Python Standard Library. Certainly popular classes are worthy of their own topics. Could namespaces be used to bring some kind of order (hierarchy) to them? (That is certainly Microsoft's approach.)
    – DavidRR
    Commented Jul 23, 2016 at 3:07
  • 1
    @DavidRR: How exactly would this apply to, for example, C++ which is defined by an international standard? The standard is defined in the order that makes sense for a standard, not for documentation. And there are many informal concepts that are not defined by the standard per-se but are inferred from it (the rule of 5 for example). Commented Jul 23, 2016 at 3:20
  • 1
    @NicolBolas But that said, what I think you are really arguing is that it is the problem that should be put front-and-center. And that each example that is presented for solving that problem is based on a mix of native language constructs and class library components (if needed).
    – DavidRR
    Commented Jul 23, 2016 at 3:20
  • 1
    @DavidRR: Not problem-focused so much as task focused. If they want to have example-first documentation, I think organizing it by task makes a lot more sense than "topic". String parsing, file reading, class building, etc. Commented Jul 23, 2016 at 3:23
  • 3
    @NicolBolas Yes, "task" is a better word. Are you perhaps advocating for the O'Reilly cookbook approach? And to cite a specific example, the C++ Cookbook?
    – DavidRR
    Commented Jul 23, 2016 at 3:39
29

The system incentivizes the wrong things.

Writing useful documentation is hard. This is among other reasons why there are so many projects with weak or bad documentation.Example code and snippets are simple to write by comparison.

The hard part of documentation isn't the examples. Organizing and explaining information in a useful and informative way? That is hard.

There needs to be a much higher reputation incentive to actually organize and explain things. Of course, this means there needs to actually BE a way to organize things. Right now, there's not, so it's a shotgun approach to spamming examples.

Even if all content was high quality there's still not a good way to cohesively organize it. Vote count is frankly a horrible way to organize documentation. You don't read a tutorial by reading step 6, then 4, then 10, then 1, then 3, etc. But the way documentation is implemented requires this.

The benefit of documentation (as opposed to searching individually for pieces of information) is you can easily find the information you are seeking. This requires some level of organization.

If each piece is supposed to be stand alone, how is that any different from Stack Overflow? Sure, technically it's a different thing, but if each piece of documentation is an answer to a simple question and intended to be independent of the others, scrap the entire project and add a better tagging/search system. Or add documentation tags and make a neat GUI for it.

And last, please for the love of all that is holy and right in the Internet make it so there is a more comprehensive process for determining who can actually write documentation. I am good at writing documentation. I'm not going to fight with script kiddies and rep farming people spamming low quality content in tags I'm knowledgeable in just to write documentation on Stack Exchange (instead of, you know, official sites) - there needs to be a way to somehow filter this out.

2
  • 19
    "I am good at writing documentation. I'm not going to fight with script kiddies and rep farming people spamming low quality content in tags I'm knowledgeable in just to write documentation [here]" This probably can't be overemphasized. If, in the benevolent desire to welcome everyone and avoid rejecting uncredentialed good contributors, this ends up with many bad contributors who just frustrate the good ones, then no good contributors will want to be involved. This was, of course, recognized a long time ago for SO.
    – jscs
    Commented Jul 26, 2016 at 5:21
  • 1
    That there is a problem: people want to score rep, so they put information in that is not only not authoritative, it's just plain wrong. How this can help the programming community is beyond me ...
    – holdenweb
    Commented Jul 27, 2016 at 9:28
17

Much of this may be because of the emphasis on examples.

To me good documentation explains:

  • Background: What do you need to know in order to understand something?
  • Why: What is the reason for specific behaviour? Does it interact with something else? 'Why' leads to understanding.
  • How: Examples.

...and while examples are useful, to learn a technology the background and the reasons for a design are more important.

What does it mean to "know the WinAPI", for example? It does not mean to have memorised the exact parameters to DrawTextEx or CreateToken, but that when you read the definitions you know the WinAPI conventions so you can guess UINT dwDTFormat is going to be an or-ed list of values without even looking up what it is. Or, at a more fundamental level, you would expect the first parameter to be a HDC because you know that most graphics functions work with a device context and they are accessed via handles.

Armed with that background, the detail of any one specific function or feature lets you implement it, and an example is useful. But you can't go in reverse from an example to that background knowledge.

The three items are listed in order of importance, and I would add a fourth:

  • Structure: First, moving from an item to other related items (crosslinks); second, being able to find what you need (hierarchical).

Stack Overflow documentation has only the third item, and it needs the others.

To put it another way: code samples are easy to find. We already have an amazing resource of code samples. But when developers complain about bad documentation, are they really complaining about not enough code samples - or are they complaining about badly organised topics or topics without the "why" and background?

3
  • 7
    I (and a few others here on meta) have gradually realized that SO Docs is intended to be a cookbook, not documentation proper. They just made a poor choice of name. Commented Jul 25, 2016 at 14:54
  • 1
    @JeffreyBosboom When the naming of this new aspect of SO was being debated, I offered this answer which indeed suggests making use of the term "cookbook." That said, I would argue that a cookbook benefits from some kind of organization (e.g., grouping related "recipes").
    – DavidRR
    Commented Jul 25, 2016 at 16:15
  • @JeffreyBosboom In that case, it truly is terribly named. But there is still an emphasis of code over everything else. A good cookbook has some background material too - it tends to provide a light overview, a few recipes to do something, but with the background and material so that you know where to start or where to look if you want to learn more. So far as I can tell, that emphasis on background and learning more is missing in Docs.
    – David
    Commented Jul 25, 2016 at 18:07
13

I'm no fan of the "Hello world" topic; personally, I feel like it betrays a critical point of documentation altogether in that you wouldn't look for documentation on a subject without at least having looked into what it is before.

Specifically, your point on explaining the technology is one I alluded to in chat the other day; you're not going to look around for documentation on a subject that you're not at least a little bit familiar with.

My belief and opinion is that the amount of "Hello world" topics (and topic duplication) needs to be addressed. If you have any way to address and figure out how to close duplicate topics or examples, that'd be beneficial to the conversation. But since the project is still in its infancy, we should give it some time to figure out the main pain points here.

13
  • 17
    "I feel like it betrays a critical point of documentation altogether in that you wouldn't look for documentation on a subject without at least having looked into what it is before." That makes absolutely no sense. If you've heard of SQL and databases, that doesn't mean you have any real conception of what they are. Just having heard the term "relational database" tells you absolutely nothing about what you'd be getting into. It's perfectly reasonable to assume that a person who's looking for documentation on a topic to know very little about it. Commented Jul 22, 2016 at 16:18
  • @NicolBolas: I disagree. Suppose I were looking for documentation into Rails Admin, and how I would go about solving a particular issue with its assumptions into HABTM relationships. Chances are very good I know what Rails Admin is, on at least a basic level. The other part to this issue is how broad or how narrow each subject should be; I'm under the impression that we shouldn't have something as vast as "relational databases" since there's a lot that could be covered in both the ANSI standard(s) and non-standard implementations like Oracle and Postgres.
    – Makoto
    Commented Jul 22, 2016 at 16:27
  • 5
    "how I would go about solving a particular issue with its assumptions into HABTM relationships" Then why are you looking at Docs.SO's main topic pages instead of using a Google search? Commented Jul 22, 2016 at 16:44
  • 4
    I can't think of a situation or question where I would ever look at Docs.SO's main page instead of using a Google search. Can you, @Nicol?
    – Cody Gray Mod
    Commented Jul 22, 2016 at 16:53
  • @CodyGray: For those who would never use Docs.SO's main page... what does it matter if there are introductory topics? Or if there is some form of organization rather than just a hodge-podge of random factoids? Why is it important that the main page be utterly useless, even to those who might find it useful if it were properly organized? Commented Jul 22, 2016 at 16:58
  • 15
    I honestly have no idea. I'm still trying to wrap my head around the whole concept here. I don't see any compelling ways in which a disorganized mass of copy-paste-ready examples would be useful to someone. This is not real documentation because real documentation explains why, not just contains code dumps. You can find disorganized code dumps all over Google. I've asked several staff members why there is no way to organize the material or to provide context, but I haven't really been able to get an answer other than it'd make it too fiddly or we don't know what it's good for yet either.
    – Cody Gray Mod
    Commented Jul 22, 2016 at 17:02
  • 2
    @NicolBolas: You've stumbled on my original point. Suppose I did find the Docs.SO page through a Google Search. I wouldn't find any value in those docs unless I knew what Rails Admin was to begin with.
    – Makoto
    Commented Jul 22, 2016 at 17:03
  • 1
    @Makoto: "I wouldn't find any value in those docs unless I knew what Rails Admin was to begin with." A Google search wouldn't lead you to introductory information on Rails Admin. It would lead you to what you actually searched for. So what's the problem with having introductory information at all? Commented Jul 22, 2016 at 17:31
  • 5
    @CodyGray: Believe me, I know the feeling. I'm just waiting for the SO developers to wake up to these facts. Commented Jul 22, 2016 at 17:33
  • @NicolBolas: It seems to me that we're talking past each other. My premise: you wouldn't use Docs.SO for a specific subject unless you knew what that subject is, and it's intended to supplement the existing documentation that's out there. My point is that I did face a very real issue with Rails Admin and a HABTM relationship earlier this year, and if I were to stumble on Docs and if it had a good approach to addressing this particular issue, that would have been hugely beneficial. I wouldn't care about the HABTM issue if I had never heard of Rails Admin.
    – Makoto
    Commented Jul 22, 2016 at 17:33
  • 9
    @nicol Wow, that is frightening.You nailed all of my conceptual objections months ago, while this business was still in private beta. And the official response seemed to be, well, we'll work it all out in private beta. Yet, here we are in public beta, and there seems to have been absolutely no progress made toward figuring out what the ideal page would look like. Even for one of the most popular tags on SO by far, the C# Docs page is haphazard, disorganized, and useless. And then beyond conceptual problems, there are serious implementation and usability bugs like it'd never been tested.
    – Cody Gray Mod
    Commented Jul 22, 2016 at 17:38
  • 1
    Hello world, setup, and installation are important. Take a look at C#'s hello world: there are multiple ways and it's nice to have consolidated tutorials on each of the various options. These are all things you expect from documentation, anyways. Commented Jul 24, 2016 at 8:24
  • 2
    @CodyGray I think the main idea here is that Docs.SO isn't really about documentation. It's about examples you can pick up and play around. You know, the way you learn by doing, and having fun. Show, don't tell. The examples don't work that way right now, because there's been a huge influx of people writing examples that don't make any sense and that are horribly broken (under the guise of "minimal example"), but the "examples first" idea is something that's been used in experiental learning for a long time, and works great, especially with guidance. Naming it "Documentation" is wrong, IMO.
    – Luaan
    Commented Jul 25, 2016 at 9:56
6

Two options to improve browse-ability.

Option 1: Have a (logically ordered) Table of Contents on each topic.

The site could would allow topics to be up and down-ordered - not by importance - but by complexity. This would give beginners on a topic some intelligent way to parse the info without wasting time on more advanced/niche topics that they don't need. Optionally, this could be an extension/rebranding of the "Remarks" section, which it sounds like is already being relocated to the top of page.

Option 2: Build dependencies between topics, and provide an option to order topics using a DAG (directed acyclic graph) approach

This is a much more ambitious approach to the problem. For instance: "Hello world" examples will have presumably zero dependencies, and can safely rank at the top. An article on advanced python decorators would rightly have a dependency on using functions as variables. By allowing dependencies to be declared between these two articles, we provide a guided incremental learning paths for readers who want to learn everything but otherwise would be going through topics backwards**.

An additional benefit of this approach is that if a user is overwhelmed by a topic, or if they know the topic they need to learn, but don't understand the terms used, they can expand the list of dependencies and learn the needed topics.

Another side-benefit is that - by mapping prerequisite topics for advanced articles - the more advanced articles can stay on point, without needless repeating of material that the reader should already know.

5
  • What does TOC stand for? Commented Jul 26, 2016 at 18:33
  • TOC = Table of Contents. I'm updating the post to specify this more clearly. Commented Jul 26, 2016 at 18:34
  • Re "time will show that more advanced topics are likely to get more votes versus the simple ones": that's the exact opposite of what we've seen in Q&A. Why would Docs be different? Commented Jul 26, 2016 at 19:16
  • Depends upon which use cases become most popular. If searching for a specific article is the primary use case (using google, for example), you'll upvote that topic. If the site doesn't effectively support starting from scratch (what many here are saying) then the beginners' use case will go elsewhere. ... which in turn decreases the number of votes on beginner-level articles. Commented Jul 26, 2016 at 19:24
  • @JeffreyBosboom - I don't have enough data to support the claim of which ordering will become most prevalent, so I'm removing that commentary from my response. After reviewing this further, I do see many topics where the top two or three topics are advanced. Example: "list comprehensions" at the top of the python page and the third or fourth topic is an intro topic. So it isn't that the results are in reverse order, exactly, but when the topic for "lists" is way below "list comprehensions", I think this supports the argument that votes shouldn't be only ranking function for browsability. Commented Jul 26, 2016 at 19:34
0

I do not want to sound elitist, but could we have "senior" people (high rep users on a particular tag, as suggested elsewhere) as the only ones giving "a structure" to docs?

Propose topic, sub-topics, write the "remarks" section, write the "elevator's pitch" introduction (another proposal I really like). Approve new examples. Everyone could contribute an example (in topic), or improve (simple edit) an existing one, but just letting everyone do everything will lead to a very unbalanced documentation and poor structure.

This is fine for StackOverflow: it is a Q&A site. Each Q could (should!) be independent from the other. But documentation should be a good balance of code and explanation, in a "good" order. Just the fact that there are topics suggest a structure.

2
  • The thing is... that they would be the only ones reviewing, and there are reviewing limits, but there are not submission limits. So, you have users that have demonstrated that they know reviewing instead of submitting what they know.
    – Braiam
    Commented Jul 25, 2016 at 14:13
  • 1
    What I want to say is: give more power to high-rep users. Not different roles, just let people who knows the stuff give some structure. You can give anyone permission to contribute and review, but not everything, not everywhere. Commented Jul 25, 2016 at 14:22
-3

I agree with you, the C# Language tag looks horrendous. One of my notes for launch readiness was that we should discard the "C# 6.0 Features" topic as a big red pimple at the end of Documentation's nose. It's only gotten worse as more and more people add their two cents to the already-bloated examples. Tons of edits exist not to make the topic better for a reader, but to add another coat of paint to the bikeshed. It's the What's your favorite “programmer” cartoon? problem all over again.

And we really aren't too worried about it.

Joel wrote in The Wikipedia of Long Tail Programming Questions:

Stack Overflow is not just a historical record of questions and answers. It's a lot more than that: it's actually a community-edited wiki of narrow, "long-tail" questions -- questions that aren't quite important enough to deserve a page on Wikipedia, but which come up over and over again.

When you see a question that seems like it might reflect a common problem, don't just answer it to get a few points. That doesn't make the Internet any better. Instead, help us build up a library of canonical questions and answers that are more generic versions of the same question, and then start closing all the exact duplicates.

The Documentation expansion is the same idea, but for examples.

"Ok", I can already hear you ask, "If Documentation is basically like Q&A, why not make it easier to share examples within answers instead?" For as long as the site has been around, we have encouraged self-answered questions. Unfortunately, they have never really caught on as a method of sharing knowledge; other users tend to treat it as a form of cheating. The other problem is that self-answered questions come off a little like watching a debate in the House of Commons where both sides address the Speaker instead of each other.

At any rate, we are working on some methods to discourage mega topics and examples. Instead, Documentation should be more digestible. Take look at the bash topic Brace expansion and imagine that you've arrived here via a Google search:

Brace expansion

That's how Documentation ought to look for most readers. We have some ideas about how to make the browsing experience better. (Mine is to use citations as a metric.) But it won't matter until we get overly wordy examples and excessively long topics under control.

6
  • Lots of duplication between .NET Framework and the various language tags, too. Which could be cleaned up by editing out a bunch of the cruft, migrating Framework stuff together, and making sure the language topics focus on the language-specific aspects of the topic. (The LINQ topics are a great example begging for some major editing...) But as I found out earlier today, once you flag a topic to be improved, you can't edit it anymore. :( Commented Jul 25, 2016 at 23:56
  • 12
    That's how Documentation ought to look for most readers I think that if this is the long term goal, documentation really will fail. Those sorts of explanations are much better fit for Q/A than "documentation."
    – enderland
    Commented Jul 26, 2016 at 0:11
  • @enderland: Perhaps. There is a pretty good comparison over on Unix. But I think the more common case is questions like this one, which includes a tanget about eval and useless echo. Nobody has an incentive to clean that up.
    – Jon Ericson Staff
    Commented Jul 26, 2016 at 0:21
  • 1
    I took a look at stackoverflow.com/documentation/c%23/24/c-sharp-6-0-features and the only reason it looks terrible is that you start with some of the examples expanded. Add a tag to the article to let you know it is a "Mega" topic and then change your code so that Mega Topics start out with nothing expanded. If you look at the topic with every example minimized, it is a cool list of all the C# 6.0 Features. Now, what might be interesting is to code up a feature so that once an article is marked with "Mega", a moderator can choose which examples to break into separate articles
    – Rhyous
    Commented Jul 26, 2016 at 22:36
  • 3
    Those aren't really digestible at all. They're random examples for a few specific scenarios, but you have to really look across all the examples to theorize how that might work for a scenario not already covered - and even then you can be misled. Where's the paragraph explaining what Brace Expansion is and expected parameters or syntax rules?
    – Troyen
    Commented Jul 27, 2016 at 0:32
  • @Troyen They're random examples for a few specific scenarios, but you have to really look across all the examples to theorize how that might work for a scenario not already covered Yes, this is called abstraction. Depending on your goals, it is a perfectly reasonable alternative to starting with a formal specification. Where's the paragraph explaining what Brace Expansion is and expected parameters or syntax rules? There is a link to the Bash Reference Manual in the remarks. I didn't feel the need to duplicate that content here. But if you think otherwise, go ahead and submit a proposal.
    – zarak
    Commented Jul 28, 2016 at 5:14
-20

I personally like the way documentation works, I think it just needs some kind of good tagging system to make it more useful and also smarter search. One more thing is that examples should have some kind of difficulty level identifier so that we can separate easy-medium-hard examples from each other.

3
  • 4
    I don't get why this answer has so many downvotes
    – AdrienW
    Commented Jul 25, 2016 at 7:16
  • 5
    @BusyAnt: Maybe because other people don't agree that Docs.SO as it currently stands is fine? Commented Jul 25, 2016 at 12:35
  • 1
    Also, some people, myself included, disagree with the "difficulty level" idea. Also, "good tagging system" is vague - is the existing tagging system bad? If yes, what would be better?
    – anatolyg
    Commented Jul 25, 2016 at 14:08
-21

If you go through your question and change "doc" to "question listing," "topics" to "questions," "page that defines" with "question that asks," and "Documentation" with "Stack Overflow," you'll find that you have just described Stack Overflow to a tee. Is it a bunch of disorganized bits? Sure, but so is SO: it's just a bunch of random strangers tossing out bits of documentation instead of questions. Is 70% of Documentation pointless? Sure, but 99% of the content on SO is useless/duplicate, and it doesn't matter because no one reads SO cover-to-cover - it's a reference, in which you find useful content via search engines. SO is incredibly useful as a whole, even though most of it is cruft. Does Documentation lack a topic that you feel is important? SO lacked many useful questions in its first two days of existence. Go write a self-answered question - I mean, topic - on it.

The fact that Documentation looks like a clone of SO should come as no surprise: it's the same people writing about the same things. We've just renamed "question" to "topic" and put a greater emphasis on self-answers. It's unrealistic to expect it to look like a document prepared by a team of professional technical writers, because that doesn't describe SO's userbase (mostly programmers). If you want it to look the kind of traditional documentation you've come to expect, it might need more involvement from people who actually know how to write that kind of documentation. I don't know where we'll get those, seeing as how I don't know many SO users who are actually technical writers who enjoy coding (such as myself). If you want Documentation to change, that'll rely on people like you, who don't like the way it looks and take it upon themselves to change it. I assume that power users at the very least are able to restructure groups of topics at will; I don't know for sure because I have no interest in this Documentation site. And hey, if it doesn't allow that, make a Meta topic suggesting as much.

That is your mission, should you choose to accept it.

17
  • 13
    Reading your answer renews the confusion about the purpose of documentation. If it's as similar to Stack Overflow Q&A as you describe, why do we need it at all?
    – Cody Gray Mod
    Commented Jul 23, 2016 at 12:30
  • 1
    @CodyGray - I don't know. I think it was a poor idea. But if it can be made better, people like the OP are the ones to do it. Commented Jul 23, 2016 at 18:37
  • Relevant trope. Commented Jul 23, 2016 at 19:06
  • The reason Q&A works is because questions are narrowly focused; questions with a broad focus or are rambling, incoherent messes are not. Q&A is about problem solving. Topics are not. That's the difference. Topics are meant to represent some kind of documentation topic, with all examples being aspects of that topic. Commented Jul 24, 2016 at 4:18
  • 2
    "I assume that power users at the very least are able to restructure groups of topics at will" That would assume someone put thought into this idea. So it shouldn't surprise you that no, "power users" have no greater ability on Docs.SO than 1-rep users. Every change has to be reviewed (and 1-rep users can reject them), and while you can make changes to multiple topics, each topic change is evaluated separately. Commented Jul 24, 2016 at 4:19
  • @NicolBolas - Well, it'll be slow going, I guess, but eventually the organizational changes that most people feel are necessary will get approved, right? I think Docs.SO is a fundamentally flawed idea, but I'm trying to be positive about it. There's bound to be some way for it to avoid the abject failure I think it's destined for. Commented Jul 24, 2016 at 4:53
  • @NicolBolas Maybe... maybe it's all a huge trap for all those repwhores, so that SO itself ends up cleaner! CONSPIRACY ALARM!!! :P
    – Luaan
    Commented Jul 25, 2016 at 9:57
  • I'm not sure why I'm getting so thoroughly downvoted for trying to be optimistic instead of diving into a pile of schadenfreude like Uncle Scrooge swimming in coinage, like I could be doing. SO is funny like that. Commented Jul 25, 2016 at 10:12
  • @TigerhawkT3 I don't see the positivity in your post. I see "you (meaning people other than TigerhawkT3) should make it better", and "I don't really care if you make it better, because I'm not doing Documentation"... Think about that. You're basically saying, "I don't give a crap -- I think the whole thing is stupid -- but you should totally fix it up". That's not positive. That's you telling a person having car problems on the side of the road, as you speed past, "Good luck with that!". Commented Jul 25, 2016 at 14:04
  • 1
    @MikeMcCaughan - Whoever wants to improve Documentation can do so. I'm not interested in it, so I won't be taking that on. Is it my responsibility or something? Should I drop everything and spend my days suggesting edits there? I think it's a little selfish of you, not to mention unrealistic, to expect strangers to rush over and fix all your problems for you. And, frankly, your entitled attitude isn't really convincing me to waste my time over there. Sorry. Commented Jul 25, 2016 at 14:41
  • You weren't sure why you were "getting so thoroughly downvoted for trying to be optimistic". I tried to point out how your post could be seen as something other than optimistic. I never said you should do anything you don't want to. All I said is how your post could be perceived as being negative. Somehow that makes me selfish and entitled. Okay... Commented Jul 25, 2016 at 15:00
  • @MikeMcCaughan - You didn't just "point out how [my] post could be seen as something other than optimistic," you (mis)quoted me as saying "I don't give a crap -- I think the whole thing is stupid" and then compared me to an uncaring passerby who shouts something unhelpful as I "speed past," implying that I should do something more. If I were just shouting as I sped past, it would look more like a comment consisting of "lol.............", not a full answer with encouragement and explanations. Commented Jul 25, 2016 at 15:08
  • And you do realize that you're expecting a Detroit autoworker (who was laid off because you thought you could build a better car) to stop and help you fix the car you made in your front yard, right? My answer here was as optimistic and positive as I could make it. I figured that was better than posting this and dropping the mic. :P Commented Jul 25, 2016 at 15:08
  • Again, I'm not expecting anyone to do anything. I did not imply that you should stop; I implied that you shouldn't shout something as you sped by. If you are not interested in Documentation, I would suggest not posting on Meta questions about Documentation. Maybe put [documentation] in your Ignored Tags list?. Apparently, there are still Meta questions not related to Documentation :). Commented Jul 25, 2016 at 15:20
  • @MikeMcCaughan - People should either fix your problems for you or just go away? It's not allowed to simply say "I'm not an expert on that site, but if its content is not to your liking, you have the power to improve it"? Commented Jul 25, 2016 at 23:10

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