Timeline for A better Documentation model: Task, not Topic [closed]
Current License: CC BY-SA 3.0
18 events
when toggle format | what | by | license | comment | |
---|---|---|---|---|---|
Oct 5, 2018 at 5:33 | history | closed |
pnuts jhpratt il_raffa Michael Gaskill Code Lღver |
Not suitable for this site | |
Oct 5, 2018 at 1:30 | review | Close votes | |||
Oct 5, 2018 at 5:33 | |||||
Mar 20, 2017 at 9:34 | history | edited | CommunityBot |
replaced http://meta.stackoverflow.com/ with https://meta.stackoverflow.com/
|
|
Jul 30, 2016 at 23:17 | comment | added | zarak | Given what seems to be the goal of Documentation, organizing by tasks rather than topics does make sense to me. For instance, I posted this under the topic of "Movement", but it would be a much better fit as a task, with each method of accomplishing the goal listed as a separate example underneath the theme of the specific task. | |
Jul 28, 2016 at 14:29 | history | edited | Nicol Bolas | CC BY-SA 3.0 |
added 511 characters in body
|
Jul 27, 2016 at 17:11 | comment | added | Frank | Personally, I'm organizing both around tasks and tools. So "Doing task X" and "Using thing Y for thing Y-ables". An example under X may link to Y ("oh, and by the way, look at Y to get a better grasp of how we solved this and where else this thing may be useful"); and vice versa ("look here to see alternative ways of approaching this problem"). It entails a small amount of duplication, perhaps, but seems more useful than the restriction topics == tasks. | |
Jul 26, 2016 at 22:37 | history | edited | Nicol Bolas | CC BY-SA 3.0 |
added 828 characters in body
|
Jul 24, 2016 at 10:55 | answer | added | SKOOP | timeline score: 10 | |
Jul 24, 2016 at 3:18 | comment | added | Cody Gray Mod | It seems to me that this "cookbook" model is much closer to what the team had in mind when they began talking about Documentation. Especially if you read between the lines, with all the focus on "examples" and considering the way it is structured. Mind you, I'm not sure that I am a big fan of it. Every "cookbook" book that I've seen has been...well, shitty, and I don't really understand (has Josh has already said), why the cookbook (problem -> solution) model wasn't already more than adequately covered by Q&A. But at least this might bring some sanity to the anarchy, so you've my support. | |
Jul 23, 2016 at 21:31 | answer | added | user1306322 | timeline score: 4 | |
Jul 23, 2016 at 19:41 | comment | added | Nicol Bolas | @Dux: They would just be different examples. The task is not "search with regex"; it's "search with string". One (or more) of the examples could use regex to do so. They could use something else too. | |
Jul 23, 2016 at 19:37 | comment | added | Dux | What about tasks that can be accomplished in different ways? How would that fit into a doc style? | |
Jul 23, 2016 at 18:51 | comment | added | Nicol Bolas | @JoshCaswell: Tasks are about goals, not the means. Solutions to tasks are the means to achieve them. Whether that solution is a UILabel or something else is a question of the solution's quality. So yes, the task would be about displaying a textual label. | |
Jul 23, 2016 at 18:47 | comment | added | jscs | I like this "cookbook" model, in particular because, as you say "voting ... now makes sense". But for the sake of argument, what about something like this: stackoverflow.com/documentation/ios/246/… "UILabel", the Topic, is a class; all the Examples are things you can do with the class. These are tasks, sort of, but there's not really more than one way to do most of them. Wouldn't it just be a useless mess to break them out into separate topics? Or is this the wrong level? Is the Topic not "Setting a UILabel frame" but something like "Displaying fixed text"? | |
Jul 23, 2016 at 18:19 | comment | added | Nicol Bolas | @JoshCaswell: It would be more Q&A like. In essence, it would be for general "questions" that in and of themselves are just too broad for Q&A. The kind for which no one answer could be complete. And you would edit an existing example, but only to clarify it or make it better within its domain. | |
Jul 23, 2016 at 18:12 | comment | added | jscs | On this model, we would accept the existence of bad-practice examples, allowing voting to sort them to the bottom, like Answers in Q&A. How does that integrate with the apparent ubiquity of edits and Improvement Requests? It would seem that they'd become subsidiary activities to original authorship and voting: you wouldn't edit such an example, you'd just provide a contrasting one. That would make the Docs interaction model a lot closer to Q&A than it appears now. Do I follow you correctly? | |
Jul 23, 2016 at 18:10 | answer | added | Dux | timeline score: 21 | |
Jul 23, 2016 at 17:59 | history | asked | Nicol Bolas | CC BY-SA 3.0 |