Skip to main content
22 events
when toggle format what by license comment
Mar 20, 2017 at 10:32 history edited CommunityBot
replaced http://meta.stackexchange.com/ with https://meta.stackexchange.com/
Mar 20, 2017 at 9:34 history edited CommunityBot
replaced http://meta.stackoverflow.com/ with https://meta.stackoverflow.com/
Sep 23, 2016 at 18:41 comment added BenPen @JonEricson and this alone is an argument for a hierarchy of some sort. If there are multiple ways to consider std::string C++ -> std::string -> {Grouping 1, Grouping 2} might be better than C++ -> std::string - Grouping 1, C++ -> std::string - Grouping 2...
Jul 28, 2016 at 14:10 comment added Jon Ericson Staff @Trilarion: I can see having linked examples like that and I think the solution (no matter the sorting) is to use hyperlinks.
Jul 28, 2016 at 12:03 comment added NoDataDumpNoContribution "We really don't expect people to sit down with Documentation and learn by careful reading. Instead, we want to surface the examples that show concepts in action." I understand the idea behind it, but what if one example requires understanding of another example before. Wouldn't it be better to then show the one that depends on another right below the other? I would actually like to sit down with Documentation and learn by careful reading.
Jul 22, 2016 at 17:20 comment added Jon Ericson Staff @CodyGray: That std::string topic is loooooong. I'd want to split it up into topics. (Again, that pushes off the problem to the topic sort.) Voting hasn't really been tested yet because all the votes are from other Docs users right now. But the hope is that useful examples will rise to the top. Except for very early learners (who are likely to have other resources) the examples of simple things are not likely to be very useful. We really don't expect people to sit down with Documentation and learn by careful reading. Instead, we want to surface the examples that show concepts in action.
Jul 22, 2016 at 16:17 comment added Cody Gray Mod But I could come up with other examples if you don't like that one. Just about any of the topics on the C++ page contain examples that, to me, would make more sense sorted logically, rather than by arbitrary vote counts. Why is it that case-conversion is ranked higher for string operations than the more fundamental act of creation or conversion into C-style strings? Even topics that look fine now simply do because the easy stuff got created first.
Jul 22, 2016 at 16:15 comment added Cody Gray Mod Hmm, I guess that gets into the one-size-doesn't-fit-all model. Not all programming languages are Java and C#. Or maybe it is my own personal bias creeping in. I find documentation that consists of only code dumps with no explanation to be essentially worthless. The x86 instruction set architecture seems like the perfect thing to be documenting on SO because it is not very well-documented elsewhere (unlike most other languages and APIs). But you aren't going to understand what it means if you're just given a bunch of code. Assembly requires some conceptual understanding to make sense of it.
Jul 22, 2016 at 15:03 comment added Jon Ericson Staff @CodyGray: That looks like great content. But it kinda stretches the definition of example past the breaking point. They look nothing like the sample provided in the Good Examples help topic. I don't know a whole lot about x86, but each of those "examples" look like reasonable topics to me. (Thugh that does push the problem to another level.) Do you have an example of actual examples that require manual sorting?
Jul 22, 2016 at 9:31 comment added Cody Gray Mod I don't know why manual sort would be "fiddly". I mean, does it take work to get a good sort order? Yes. But that's neither surprising nor unique. It will take a lot of work to get good documentation on Stack Overflow. For example, I just approved this topic for the x86 documentation. It contains a bunch of different examples that deal with different topics under that fundamental heading. It looks like great work to me, properly using all the features. But the sort order is inane and confusing.
Jul 21, 2016 at 23:43 comment added nickguletskii @JonEricson There are several reasons. The first one is that the only logical place for a link to other topics is the remarks section, and its visibility is rather limited for such important references. The second one is that its more likely that people will react to something written in larger letters and in a differently styled box than they are to the frequently occurring hyperlinks. Since it seems that SO doc is targeted towards people who mostly copy examples without reading, it is very important to properly advertise these connections.
Jul 21, 2016 at 23:21 comment added Jon Ericson Staff @nickguletskii: Why not edit in some links so people won't miss that connection?
Jul 21, 2016 at 23:17 comment added nickguletskii What SO Documentation has now is clearly not enough. For instance, for the Java tag, there is a topic called "Concurrent Programming (Threads)". Anyone who searches for examples on concurrent programming in Java is likely to end up in that topic, but it is missing information on best practices and important classes because they are, as it turns out, in a different topic. This wouldn't be a problem if "Concurrent Programming" were a category, not a simple topic. This lack of hierarchy and discoverability is going to dramatically increase the spread of bad practices.
Jul 21, 2016 at 19:46 comment added NoDataDumpNoContribution Topic-Groups would be nice. I feel like the list of topics is quite unordered and does not give a good overview, so something below the tag level and above the topics level. Alternatively multiple tags per topic as in the main site.
Jul 21, 2016 at 19:23 comment added Jon Ericson Staff @CodyGray: We discussed different ways of sorting examples, including manual sorts. But it was just too fiddly and we didn't know exactly how people would use the system. So we copied the pin-and-scoring system from Q&A. I would not bet against that model being augmented or even scrapped in the future. It'll be easier to design after we have more content to prototype with and more edge cases.
Jul 21, 2016 at 19:14 comment added Matthew Whited currently I only see duplications instead of crosslinks (sidewalks)
Jul 21, 2016 at 11:52 comment added Cody Gray Mod demonstrate different things you might need to do with a string. Why would case-conversion be shown at the top, whereas trimming be shown at the bottom? Worse, since votes affect this, and votes can change at any time, the order is also subject to change. I find that very confusing. It would make far more sense if there was some way to order the examples from, say, beginner to intermediate to advanced. Or just some type of logical ordering, assuming that they weren't intended to all just be different people's attempts at examples of how to do the same things.
Jul 21, 2016 at 11:51 comment added Cody Gray Mod The fundamental problem I see is treating all examples as if they are equal, so that the best ones (most upvoted) rise to the top. This works well for Q&A because all answers are expected to be an answer to the question. The best (most useful, most accurate, most complete) answers filter to the top; the others fall to the bottom. But that model doesn't seem to transfer to examples in Documentation, at least not the way I currently see it being used. Look for example at C++ Strings. There are a bunch of different examples that...
Jul 20, 2016 at 17:52 comment added Suragch The path to sidewalk philosophy is intriguing. I'll be interested to see where it leads. In the past few days I've tried adding some new topics and examples to existing topics. The examples seem to be acting like sub-topics. I also don't know how duplicate handling will work. I purposefully added some duplicate examples that were broken down with a different organization that I felt was easier to use.
Jul 20, 2016 at 16:46 comment added Jon Ericson Staff @Braiam: That's the GitHub wiki approach to documentation. The trouble with requiring people to build their own structure is that it adds a tedium to an already tedious task. We know that the most useful bit of documentation is examples, so we require those. It also makes some sense to group examples on a page somehow. And it's sorta insane to lump Java documentation with Javascript documentation, so you gotta divide by tags. I think we owe people a minimal hierarchy. What Docs offers might not be ideal, but it's a good place to start.
Jul 20, 2016 at 16:36 comment added Braiam Actually, documentation is simple, more simple than pure Q&A. You got a thing, that does stuff, and thats everything that needs to be documented.
Jul 20, 2016 at 15:48 history answered Jon EricsonStaff CC BY-SA 3.0