Timeline for Documentation should be elitist
Current License: CC BY-SA 4.0
16 events
when toggle format | what | by | license | comment | |
---|---|---|---|---|---|
Jan 18, 2021 at 12:13 | history | edited | CommunityBot |
replaced http://data.stackexchange.com/ with https://data.stackexchange.com/
|
|
May 23, 2017 at 12:38 | history | edited | CommunityBot |
replaced http://stackoverflow.com/ with https://stackoverflow.com/
|
|
Mar 20, 2017 at 9:15 | history | edited | CommunityBot |
replaced http://meta.stackoverflow.com/ with https://meta.stackoverflow.com/
|
|
Dec 21, 2016 at 21:07 | history | edited | Peter Mortensen | CC BY-SA 3.0 |
Copy edited, etc.
|
Dec 21, 2016 at 6:36 | history | edited | Jon EricsonStaffMod | CC BY-SA 3.0 |
Tilting at windmills, once again. But it's the process that matters and not the result, after all.
|
Dec 21, 2016 at 6:07 | comment | added | Cody Gray Mod | In fact, I strive to always provide canonical answers, even when answering what is ostensibly a narrowly-scoped question, since our stated goal is and has always been to be a resource to the larger programming community, not just a help desk. "To take a very basic problem, what should you do when the canonical answer changes?" Not seeing the problem here. When the answer changes, you either update it (if it's a minor change), or you add a new answer (if it's a major change, and you don't want to lose the old information). We support edits and new answers quite well. | |
Dec 21, 2016 at 6:06 | comment | added | Cody Gray Mod | "Unfortunately, it's getting harder and harder to ask the sorts of questions that might result in useful documentation." Um, why is it getting harder? Because most of the good canonical questions have already been asked? Then the problem has been solved. If it's because people are closing legitimate questions, then perhaps that is the real problem you should be solving? "It's also, you know, a mighty big hack. Well, I guess this is where we profoundly disagree. I don't think asking a question and getting a good canonical answer is a hack at all. | |
Dec 21, 2016 at 5:57 | comment | added | Nicol Bolas | "Most documentation tells you how the technology was designed to work. It rarely explains the tricks that make it actually work in less-than-ideal cases." I think this goes back to user expectations. When people see the word "documentation", they do not think of something that "explains the tricks...". They think of reference manuals, something that is both explicit and comprehensive. Books that teach you tricks aren't called documentation. They're called "cookbooks". If that's what Docs.SO should be, then the reason people are using it wrong is because you named it incorrectly. | |
Dec 21, 2016 at 5:45 | comment | added | Jon Ericson StaffMod | @CodyGray: Stack Overflow is the bazaar model. The OP is suggesting converting Documentation to a cathedral. You are correct I did feel it best to answer the question asked. Joel did push for the concept of canonical answers. Unfortunately, it's getting harder and harder to ask the sorts of questions that might result in useful documentation. It's also, you know, a mighty big hack. To take a very basic problem, what should you do when the canonical answer changes? | |
Dec 21, 2016 at 5:35 | comment | added | Cody Gray Mod | I don't really understand how the Cathedral vs. Bazaar analogy applies here. It would only make sense if Stack Overflow Q&A was the cathedral, but it clearly is not, and the rest of your answer seems to agree with me on that point. As such, we already are trying out the bazaar model, and it has been quite successful. So successful, in fact, that "answers on Stack Overflow have become de facto documentation". Which brings us back to the recurring question, why do we need a special place for this. But I guess you weren't trying to answer that this time. | |
Dec 21, 2016 at 5:34 | comment | added | BoltClock Mod | "Most documentation tells you how the technology was designed to work. It rarely explains the tricks that make it actually work in less-than-ideal cases. Nor does it usually call out clever hacks that work around design flaws. And sometimes the tricks of the trade change over the life of language or library." I think what we really need is a way to convey this effectively to everyone (at least, everyone in the target audience). Right now, for whatever reason, none of the attempts at telling people what Documentation is and how it's supposed to work have managed to get it across. | |
Dec 21, 2016 at 5:34 | comment | added | BoltClock Mod | "good programmers" As opposed to inexperienced ones who have no idea what they're doing and are just throwing their hat in for the fake Internet points, yes. | |
Dec 21, 2016 at 5:32 | comment | added | Jon Ericson StaffMod | @GabeSechan: You seem to have interpreted ESR's ideas rather differently than I do. The distinction between bazaars and cathedrals is entirely about how they are managed, not how the contributors are compensated. The fact that many of these projects have contributors employed by different companies demonstrates they are anything by cathedrals. In any case, you can't deny that Linux and other early-90s open source project did succeed by organizing many good programmers rather than a small number of experts. | |
Dec 21, 2016 at 5:28 | comment | added | Gabe Sechan | In the meantime- you're doing the exact opposite. People who are experts in the various areas take a look at the utter shit that is documentation, and run the other way. Right now I wouldn't write for it if you paid me to. I'm not saying my suggestion has all the answers, but what you're doing right now isn't working. | |
Dec 21, 2016 at 5:25 | comment | added | Gabe Sechan | And the cathedral won. Almost no major open source projects are actually bazaars anymore- the majority of contributors to all of them are paid for by various corporations to work on the project. | |
Dec 21, 2016 at 5:20 | history | answered | Jon EricsonStaffMod | CC BY-SA 3.0 |