122

I'm not sure about the motivation behind creating the SODocs project. But I'm personally very disappointed by it. If you are looking for the solution to a very specific problem, Stack Overflow is your friend, but if you're a complete beginner, you're better off using a documentation authored by a fewer number of people in an organized manner. SODocs lacks comprehensiveness and continuity.

Documentation is generally written in a traditional book-form, with a hierarchy of topics and mostly linear dependencies between them. While in SODocs, there is a complete lack of any dependency-threads that one can follow, and categories are restricted to being just one-level deep. Here's a very related discussion about this.

One important argument against using hierarchies is the question of how to determine the hierarchy when there is a lot of contention and conflicting proposals.

A second argument is claiming that people look for documentation by googling it! That argument is baffling, because the purpose of documentation is to teach you about things you don't know exist. How would I google for something I don't even know about?! What SODocs terribly lacks as of now is discoverability of the unknown.

One proposal that I can think of which kind of solves this problem is to keep examples independent, and to have multiple organizational structures be maintained at the same time. That is, anyone can propose a structure to organize them with, and others can vote on it and propose edits which must be accepted by the one who created it.

The default view may use a weighted combination of two or more highest scoring hierarchies (how to combine?) to show a rich view of the general consensus of structuring. The view should preferably be graphical (showing (weighted?) dependency links) and interactive (ability to collect directly connected topics of a given topic in one place), while being comfortably readable (not flashy).

I know I just hand-waved through a lot of complexities, but the status quo is quite lacking.

19
  • 7
    The purpose of Stack Overflow Documentation has been discussed many, many times. From the initial post describing it, the update to that initial post, and so on. I don't see much here except additional complexity (a graphic showing dependency lines?) that would not likely help beginners anyway. The fact is that Documentation was specifically made to NOT be the official docs, but rather a supplement where the original lacks. Apr 10, 2017 at 14:43
  • Related issues and idea that I've previously brought up: meta.stackoverflow.com/questions/328649/… and meta.stackoverflow.com/questions/329743/…
    – Tot Zam
    Apr 10, 2017 at 14:49
  • 4
    @MikeMcCaughan My thinking was that if there is a rich structural organization of topics, it may be easier to discover topics/examples that may be hard to discover otherwise in a barely organized heap of things.
    – John
    Apr 10, 2017 at 14:49
  • 37
    The problem is that they actually intend it to be a cookbook, not documentation (meta.stackoverflow.com/a/343684). As for Googling, indexing is apparently turned off right now.
    – jscs
    Apr 10, 2017 at 17:28
  • 5
    Documentation is generally written in a traditional book-form, with a hierarchy of topics and mostly linear dependencies between them uhh... my experience is that documentation generally is a terrible mess of either insufficient, incoherent or randomly structured uninformative walls of text. If there is any documentation. And let's not get started on machine translations. Apr 11, 2017 at 3:57
  • 15
    If it is intended to be a cookbook its brand should reflect that (call it StackOverflow Recipe or something) (although it may be too late to change now) @JoshCaswell
    – kennytm
    Apr 11, 2017 at 13:10
  • 20
    @kennytm no, never too late to get a name correct
    – Cœur
    Apr 11, 2017 at 13:28
  • 18
    "I'm not sure about the motivation behind creating the SODocs project." They just wanted to milk some more money out of the site without touching the core concept. It is not there to fill a need, that's just something people try to make up afterwards, to justify its existence. "It's canonical documentation! "No, it's examples!" "No, it's replacement for 3rd party manuals!" "No, it's a cookbook for newbies!" And so on.
    – Lundin
    Apr 11, 2017 at 14:21
  • 5
    Did someone say "quality" already? Recently I revised an Introduction(!) Topic "Getting Started ..." that didn't even get the basics right. And this has been there for half a year, at least – I didn't advance to the second page of the Change history. I wonder how many beginners "learned" from that in the meantime. Apr 12, 2017 at 4:34
  • 10
    I agree with at least some of this. I looked at the topics for the tags that I hang out on, [selenium] and [selenium-webdriver], and they are a hot mess. They are mostly written by people that have under 1k, if not under 500, rep. I went to propose some changes and got inundated with questions that didn't make any sense. At that point, I just gave up. I don't think there's much hope for documentation written and maintained by people that don't understand the basics and make it so hard for people that actually understand the material to fix it.
    – JeffC
    Apr 12, 2017 at 5:02
  • I think a good survey is in order on what people feel about the quality and usefulness of the documentation if there isn't already stats around this already. Although I see that the conflict on what is expected of the documentation varies widely.
    – Shawn
    Apr 12, 2017 at 17:06
  • 2
    @Shawn Not a survey but related: Is Documentation failing? Apr 12, 2017 at 17:11
  • 1
    @MikeMcCaughan Sometimes I think it makes sense to pivot from original intent when things are not as clear or useful as intended. How linked are the current examples to the original sources? In my opinion I see alot of code dumping but that has alot of threads around it too.
    – Shawn
    Apr 12, 2017 at 17:34
  • In the tags i follow, i primarly see a re-creating of official docs. Not copy/paste plagiarized, but the same information is being presented in a far less structured way. I can definitely see SO documentation being useful for some tags, but many of the popular tags that are getting all the attention don't need SO docs. They already have great documentation and examples.
    – Kevin B
    Apr 12, 2017 at 22:22
  • 2
    Even cookbooks have meaningful structure. SO Documentation does not have to be as organized as an encyclopedia or dictionary, but there should be some meta structure within each programming area.
    – Peter L.
    Apr 13, 2017 at 2:15

2 Answers 2

2

You raise quite some points.

Documentation is generally written in a traditional book-form, with a hierarchy of topics and mostly linear dependencies between them. While in SODocs, there is a complete lack of any dependency...

That is not completely true. Dependency is not the same as hierachy. You can for example have links as dependencies. The amount of linking between different Documentation topics is very low (just checked for several topics in the Python Language tag and found almost no inter-Documentation linking) but that is not solely because of the structure of Documentation.

A second argument is claiming that people look for documentation by googling it! That argument is baffling, because the purpose of documentation is to teach you about things you don't know exist. How would I google for something I don't even know about?! What SODocs terribly lacks as of now is discoverability of the unknown.

At first glance I would think so too, but then how do you discover the unknown anywhere else? How is it done in a book or in other online documentation? I don't know of anything else except:

  • Some kind of table of contents
  • Some kind of index
  • Random browsing
  • Links to related content

The infrastructure for the first two points is a bit low and could surely be improved.

One proposal that I can think of which kind of solves this problem is to keep examples independent, and to have multiple organizational structures be maintained at the same time. That is, anyone can propose a structure to organize them with, and others can vote on it and propose edits which must be accepted by the one who created it.

Here you lost me a bit. I thought Documentation examples are quite independent. They exist only in a topic coupled with a few other examples. And wouldn't it be a very big overhead to support multiple organizational structures at the same time? Voting is always nice, but someone has to implement it all..

I would like to hear more details about this proposal. I advice to make it a more fleshed out feature proposal with an example.

The default view may use a weighted combination of two or more highest scoring hierarchies (how to combine?) to show a rich view of the general consensus of structuring. The view should preferably be graphical (showing (weighted?) dependency links) and interactive (ability to collect directly connected topics of a given topic in one place), while being comfortably readable (not flashy).

This sounds rather complex. Again I would prefer to see a more fleshed out example of how that is supposed to look like.

I know I just hand-waved through a lot of complexities, but the status quo is quite lacking.

I agree and my guess is that the people behind Documentation chose this approach as a compromise of implementation time and their ideas how it would work as a self-regulating system. I don't think it works. It's failing. But with hindsight everything seems obvious.

Your ideas might be better suited.

My idea would be to actually make the whole project much smaller and understand Documentation as a collection of curated exemplary well StackOverflow answers to general questions serving as potential replacement/duplicate targets.

Anyway one way to get some flexible hierachy into Documentation cheap would be a tagging like for StackOverflow Q&A. That's what I would like to have together with all the simple, copied, beginner examples gone.

Also, by now it's not just the infrastructure that is suboptimal. Also there is lots of wrong content in Documentation. Documentation is barely alive.

3
  • I do agree that for the proposal I made, the cost of implementing probably far outweighs the expected returns. I have a much simpler idea (involving tags), but it is radically different, and not very ... user-friendly. I'll post another question if/when I feel it is reasonably intuitive to work with.
    – John
    Apr 13, 2017 at 16:00
  • @John If it's not very user friendly it might not be the solution. Anyway, I'm waiting for your ideas.
    – Trilarion
    Apr 13, 2017 at 18:42
  • Right. What I meant was that I'm waiting to see if I can get it refined to be user-friendly. I don't think posting the idea as it is now will be helpful.
    – John
    Apr 13, 2017 at 19:03
-10

As indicated in the comment, you seem to forget the key proposition of SO Documentation as mentioned here and referred in the comments.

In short:

SO documentation intends to pick up where regular documentation has dropped the ball. For example by adding:

  • Good examples
  • More recent or complete information

As such it does not strive for comprehensiveness, if there is already sufficient good documentation that people manage to find. And therefore the structure is set up the way it is now.

6
  • 6
    It would still be helpful if the examples were more logically organized (ie, in a more detailed hierarchy).
    – Suragch
    Apr 12, 2017 at 12:06
  • 35
    And then there is SO documentation even for Java Array. Like it's not documented by oracle/anywhere else on internet or it's all ancient. People just replicates stuff for reputation. I don't like the concept of SO docs as it is now.
    – T J
    Apr 12, 2017 at 14:36
  • 3
    I wasn't suggesting that SO Documentation should be comprehensive (it was about improving discoverability). Though, it might be reasonable to argue that in order to have useful dependency relationship among topics, the documentation should be somewhat comprehensive. I think SO Docs should very much encourage linking to official documentation pages (even within "dependency structuring"). This way, users would be easily able to refer to official docs if certain complex topics need more verbosity.
    – John
    Apr 12, 2017 at 15:22
  • @TJ I know that basic stuff is documented here which can be found in a million other places, but to my interpretation that was not the intent of docs SO (and it also does not add much value in general). Apr 13, 2017 at 8:01
  • @TJ I'm more appalled by how people use it and even now continue to use it. You can't blame the software for it being used as designed for all the wrong purposes :/
    – Gimby
    Apr 13, 2017 at 9:12
  • 2
    @Gimby When the majority of users use the software in the wrong way, you should blame the software for its bad design.
    – John
    Apr 13, 2017 at 10:44

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