Skip to main content
15 events
when toggle format what by license comment
Jan 18, 2021 at 12:05 history edited CommunityBot
replaced http://chat.stackoverflow.com with https://chat.stackoverflow.com
Jul 25, 2016 at 9:56 comment added Luaan @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.
Jul 24, 2016 at 8:24 comment added Mateen Ulhaq 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.
Jul 22, 2016 at 17:38 comment added Cody Gray Mod @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.
Jul 22, 2016 at 17:33 comment added Makoto @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.
Jul 22, 2016 at 17:33 comment added Nicol Bolas @CodyGray: Believe me, I know the feeling. I'm just waiting for the SO developers to wake up to these facts.
Jul 22, 2016 at 17:31 comment added Nicol Bolas @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?
Jul 22, 2016 at 17:03 comment added Makoto @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.
Jul 22, 2016 at 17:02 comment added Cody Gray Mod 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.
Jul 22, 2016 at 16:58 comment added Nicol Bolas @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?
Jul 22, 2016 at 16:53 comment added Cody Gray Mod 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?
Jul 22, 2016 at 16:44 comment added Nicol Bolas "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?
Jul 22, 2016 at 16:27 comment added Makoto @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.
Jul 22, 2016 at 16:18 comment added Nicol Bolas "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.
Jul 22, 2016 at 15:47 history answered Makoto CC BY-SA 3.0