Timeline for A better Documentation model: Task, not Topic
Current License: CC BY-SA 3.0
19 events
when toggle format | what | by | license | comment | |
---|---|---|---|---|---|
Jul 24, 2016 at 7:29 | comment | added | Cody Gray Mod | @josh You think that's confusing, proposed changes have a critical bug wherein they diff against the current revision, rather than the revision at the time that the changes were submitted. I mentioned this as an afterthought here; perhaps I need to promote it to a separate question. I doubt it'll do any good. There are so many bug reports for Docs on Meta the team is surely overwhelmed. | |
Jul 24, 2016 at 4:55 | comment | added | jscs | Plus an interface that's making me go cockeyed. What the f just happened in this review stackoverflow.com/documentation/proposed/changes/… | |
Jul 24, 2016 at 4:51 | comment | added | bwoebi | @JoshCaswell and herein lies the core problem… they give us not enough guidance. | |
Jul 24, 2016 at 4:45 | comment | added | jscs | @bwoebi: "the people in charge of docs...where they want to guide us" Unfortunately, that's the explicit and conscious opposite of what they are doing "what [they...] are saying" they say "wait and see". | |
Jul 24, 2016 at 4:31 | comment | added | bwoebi | @NicolBolas Sorry if this was unclear; You exposed the issues. It clearly didn't expose them to the SE staff, even with your advice, though. Now - I very much hope at least - they will realize the issues too and act adequately. | |
Jul 24, 2016 at 4:23 | comment | added | Nicol Bolas | @bwoebi: "Private beta sadly wasn't able to truly expose the issues, so we have them now :-(" Nonsense. I exposed the conceptual issues with Docs.SO months ago. The lack of structure, the question of how to document things that aren't code, the unclearness with how Docs.SO is supposed to work, and so forth. Nothing was done about any of that. | |
Jul 24, 2016 at 4:20 | comment | added | bwoebi | @NicolBolas True, there's been some communication problem with SE staff. They themselves only seem to have had a vague idea. Private beta sadly wasn't able to truly expose the issues, so we have them now :-( In private beta the systems also worked so much better due to the vastly limited scope of participants. There was no need to deal with low quality and whatever. So these systems are now lacking a lot of care and the loads of problems only slowly unfold... TBH, I'm waiting a bit for what the people in charge of docs are saying and where they want to guide us. Not much we can do currently... | |
Jul 24, 2016 at 4:10 | comment | added | Nicol Bolas | @bwoebi: "But you cannot expect that to be present in first days of public beta." ... why not? What was the several months of private beta for, if not to develop those facilities? "I very much agree that we need to first figure out what docs is before everything else." If you launch a service, it's incumbent upon the launchee to figure out what it is before it gets launched. Wikipedia knew what it wanted to be from day 1, and they found people willing to make it into that. We have lots of people willing, but far fewer with ability and even fewer with any idea what we're supposed to do. | |
Jul 24, 2016 at 4:00 | comment | added | bwoebi | @NicolBolas You can only be banned. A new account is quickly created (assuming you have a dynamic IP changing upon every new DSL lease request). … But yeah … I agree that we shall put ways in place to eliminate the users who are providing bad content from contributing further. I also fully agree that we need clearer scope about good and bad. But you cannot expect that to be present in first days of public beta. We have to evolve them. We've gotten the tools; now we need to figure out what we do with them. I very much agree that we need to first figure out what docs is before everything else. | |
Jul 24, 2016 at 3:31 | comment | added | Nicol Bolas | @bwoebi: "They do have a lot of bad contributions, but most of them are obvious and reverted. Same problem here." No, it isn't. As you point out, people who make negative contributions are punished. We don't do that; the most we'll do is undo the change. Furthermore, Wikipedia makes it very clear what the difference between good and bad contributions are. Docs.SO does not; we can't even decide what constitutes a "topic" or whether a valid example on a language page should include a library written in that language. | |
Jul 24, 2016 at 3:12 | comment | added | Cody Gray Mod | Wikipedia is completely different because it is far more free-form than Docs is. In that sense, Wikipedia is much more like our self-answer Q&A. The question introduces the topic/problem, and the answer gives a solution using any format that is appropriate. | |
Jul 24, 2016 at 1:01 | comment | added | CWilson | I believe that the problem statement in stackoverflow.com/tour/documentation, "It was usually written once, often by someone not even using the technology, so it was a guess at what to focus on." suggests that the argument that documentation already exists from microsoft or whoever and therefore does not need to be replicated here is not considered a valid one by the people who made Docs.SO. | |
Jul 23, 2016 at 21:29 | comment | added | bwoebi | @NicolBolas They don't have Rep, but contribution count is also an impressive stat and not totally ignored over there. Also, a major difference is that if you write repeatedly low quality text, you get publicly called out, on your discussion page. That's more stigmatizing than anything we have here. [The downside of that is that you need a thicker skin.] And still, Wikipedia has had some notorious hoaxes and perfidious vandalism long unnoticed … because you can just not verify everything. They do have a lot of bad contributions, but most of them are obvious and reverted. Same problem here. | |
Jul 23, 2016 at 19:44 | comment | added | Nicol Bolas | Wikipedia doesn't have a rep system that encourages bad contributions. Wikipedia doesn't have a built-in structure that encourages contributions that are neither extensive nor easy to dive into. MediaWiki was nothing more than a system for collaborative editing of marked-up text. Wikipedia worked because it managed to create a culture of people who were willing to build and follow certain rules, and it made it easy to make major changes to pages in accord with more reasonable organization. Docs.SO has none of that, nor is it likely to without major, fundamental changes. | |
Jul 23, 2016 at 19:36 | comment | added | Dux | I believe I gave this purpose? Write a doc that is easy to dive in, and that is nevertheless extensive. I understand your point, and you are right, docs IS disorganized atm. But I guess so was Wikipedia back then, and look what has become of it. | |
Jul 23, 2016 at 19:26 | comment | added | Nicol Bolas | "With that argumentation, why write a doc at all?" Then at last you've come to the fundamental question that has yet to be satisfactorily answered: what exactly is the point of Docs.SO at all? Right now, it is a dumping ground, a disorganized hodge-podge of random crap. My suggestion here is intended to give it a well-defined purpose. If you want it to have a different purpose, fine, but you need to actually state what that purpose is. And equally importantly, a scheme that will actually achieve that purpose. Because Docs.SO currently will only produce what you're looking for by accident. | |
Jul 23, 2016 at 19:03 | comment | added | Dux | I can ALWAYS just look up the original documentation. Which may or may not be way too heavy to understand at first or second read. With that argumentation, why write a doc at all? | |
Jul 23, 2016 at 18:55 | comment | added | Nicol Bolas | "Because that would bundle the knowledge I can get from browsing through tons of Q&A..." Or you could look up the actual regex documentation for your language of choice. I don't see how this is any better than this (ignoring the massive quality difference, of course). It didn't become better just because it's hosted here. | |
Jul 23, 2016 at 18:10 | history | answered | Dux | CC BY-SA 3.0 |