Timeline for Tearing Down the Structure of Documentation [closed]
Current License: CC BY-SA 4.0
83 events
when toggle format | what | by | license | comment | |
---|---|---|---|---|---|
Jan 18, 2021 at 12:15 | history | edited | CommunityBot |
replaced http://data.stackexchange.com/ with https://data.stackexchange.com/
|
|
Jan 12, 2018 at 2:55 | review | Reopen votes | |||
Jan 12, 2018 at 7:48 | |||||
Jan 12, 2018 at 2:46 | history | closed |
Robert Columbia Michael Gaskill Stephen RauchMod HaveNoDisplayName Code Lღver |
Not suitable for this site | |
Jan 12, 2018 at 1:05 | review | Close votes | |||
Jan 12, 2018 at 2:46 | |||||
Aug 5, 2017 at 12:38 | comment | added | Fattie | "failing early ..." folks never change. If the style of the folks running SO is that they tediously hang on to utter flops ("what can we Tweak!"), it will just keep happening over and over and over. I mean it's harmless though, it's only the odd million here and there. Once the business is finally sold to goog, FB or whoever, nobody will even remember the early players, other than "OMG those dudes were so admirable to make so much money, I want to be like that". It's just .. funny .. when folks take a "what can we Tweak!" approach to complete disasters. No harm done really. | |
Aug 3, 2017 at 15:44 | comment | added | holdenweb | Probably not pleasant for SO to have to make this discovery and admission, but far better to do so that continue ploughing their and users' efforts into a failed experiment. I hope this has taught SO something about a) the need to consult before implementing grand new features, and b) the value of user feedback in failing early those times when they've made a mistake. | |
Jul 7, 2017 at 20:05 | comment | added | JL Peyret | How about not notifying us every time someone makes a change to a topic that we've contributed to in the far distant past? | |
May 30, 2017 at 17:47 | answer | added | Alon Eitan | timeline score: 4 | |
May 30, 2017 at 17:25 | history | edited | Jon EricsonStaff |
edited tags
|
|
May 30, 2017 at 15:28 | answer | added | MER | timeline score: -2 | |
May 29, 2017 at 19:38 | answer | added | Roman Susi | timeline score: -4 | |
May 29, 2017 at 5:29 | comment | added | Akash Thakare | @TylerH Probably, but my point is improving on what people are coming here for and not wasting time on something which goes out of control after some days or hard to define. I mean documentaion is not documentation actually and yes SO team may get some better ideas to improve or solidify it undoubtedly. My only point is documentation does not belongs to SO Q&A and that's how I want it to be. I might be wrong but I won't be able to make habit to refer SO documentation at any point as per the current state of the documentation. | |
May 26, 2017 at 14:55 | answer | added | Jouster500 | timeline score: 4 | |
May 25, 2017 at 14:02 | comment | added | JDB | I still think this whole experiment is like throwing 1,000 cooks into a kitchen, from professional chefs to folks who struggle with boxed mac and cheese, giving them all equal authority, and asking them to produce a well structured menu and delicious meals. I'm curious to see how it goes, but after a couple months of trying, I found the whole experience to be far too frustrating. | |
May 24, 2017 at 23:52 | answer | added | Lee Whitney III | timeline score: 11 | |
May 24, 2017 at 16:02 | answer | added | spacetyper | timeline score: 0 | |
May 23, 2017 at 14:42 | comment | added | Kaz | Why would anyone want to use anything whose documentation is so locking, they have to use Documentation? The only purpose Documentation serves is to shame some projects into documenting. | |
May 23, 2017 at 12:38 | history | edited | CommunityBot |
replaced http://stackoverflow.com/ with https://stackoverflow.com/
|
|
May 23, 2017 at 10:54 | comment | added | Malcolm McLean | Just look at Wikipedia. Effectively we need a wiki that covers programming topics in more detail than would be appropriate for Wikipedia. The Wikipedia pages are attractive - you've got images, rich markup, cross-references. | |
May 23, 2017 at 6:27 | answer | added | Benjol | timeline score: 4 | |
May 22, 2017 at 22:44 | comment | added | Sam Axe | I agree with JasonC, the premise of Documentation is flawed. But if you insist on going down this path, you might find that not tying documentation to reputation nets you better content. Dangling the rep carrot from the doc donkey might be the wrong way to inspire great writing. | |
May 22, 2017 at 19:16 | answer | added | jinglesthula | timeline score: 1 | |
May 22, 2017 at 19:05 | comment | added | TylerH | @JonEricson Agreed; especially with the audit trail and revision diffing available, and the strong inclination and review process for citations and article locking, Wikipedia is a far more reliable source than your average fire-and-brimstone college professor would lead you to believe. The information there is often more reliable and up-to-date than the $200 textbooks I compare in reference. And it's hard to remember, but you make a good point - Wikipedia in 2006 was a far cry from the quality and scope of Wikipedia in 2017. I'm sure Docs will be the same. | |
May 22, 2017 at 19:03 | comment | added | TylerH | @TAsk Documentation is a separate subsite from Q&A, so the topicality constraints of Q&A are irrelevant. | |
May 22, 2017 at 14:05 | answer | added | toonarmycaptain | timeline score: -3 | |
May 22, 2017 at 5:31 | comment | added | Akash Thakare | I may sound bitter but to be honest documentation is not something and will not be something which I could expect from Q&A community. Because it's offtopic in my opinion. | |
May 21, 2017 at 8:06 | comment | added | sideshowbarker Mod | Rename it Examples instead of “Documentation”. As meta.stackoverflow.com/questions/303865/… explains, fundamentally what’s not working and never going to work is that y’all gave the thing the wrong name to begin with. The rest of the issues are symptoms of that fundamental mistake. Re-brand it as Examples and re-work the structure entirely around it being a place for examples rather than “documentation” and it will have a much better chance of success and much better chance of actually becoming useful. | |
May 20, 2017 at 17:44 | answer | added | Sumurai8 | timeline score: -2 | |
May 20, 2017 at 7:28 | answer | added | ItamarG3 | timeline score: 3 | |
May 20, 2017 at 4:46 | comment | added | Jon Ericson Staff | @philipxy: I feel like Wikipedia is reliable enough for the average person to learn useful things. That's more or less the model we've been aiming for so far. There might be a few places where people engage in edit wars (though I haven't seen that in Docs), but the slow accumulation of edits will, if designed well, produce something the average programmer can use to get their jobs done. (I gotta say, for an unregulated community space, r/Place was pretty amazing.) | |
May 20, 2017 at 4:06 | comment | added | philipxy | That's a nice pair of metaphors but unfortunately a crowdsourced product (eg an SO vote total, but not an SO question or answer, which is effectively individually sourced) is neither (the roughly analogous analogies) a cathedral nor a bazaar. It is a (reddit) place. | |
May 19, 2017 at 21:06 | answer | added | some bits flipped | timeline score: 2 | |
May 19, 2017 at 19:33 | comment | added | Travis J |
For example, there is plenty of duplication at Stack Overflow. I give you exhibit A: stackoverflow.com/a/16080764/1026459 . This content is rather terrible. It is not only incorrect, but it doesn't even explain what the goal was, it is a code only answer. It also has to do with jQuery's .on function which is asked about all the time. However, the post has 6 answers and only 42 views in 4 years. Was the incorrect content problematic to Stack Overflow as a whole? No, of course not. Why? Because more popular and correct content exists that ranks waaay higher.
|
|
May 19, 2017 at 19:22 | comment | added | Travis J | "incorrect content is the problem that needs to be solved", this is why there needs to be duplication. Allowing content to compete will allow the correct content to take precedence both in google searches and in local searches. Correct content will be a stronger target of external links, and as a result it will remove the problem presented by incorrect content as it becomes buried in obscurity. | |
May 19, 2017 at 17:32 | comment | added | Jon Ericson Staff | @JarrodRoberson: I'm afraid the "beta" label has lost it's meaning. (And we haven't helped.) I can understand skepticism of the entire idea of letting fellow programmers write documentation. But it's not a conclusion we are ready to jump to just yet. | |
May 19, 2017 at 17:30 | answer | added | Jason C | timeline score: 39 | |
May 19, 2017 at 16:22 | history | edited | Peter Mortensen | CC BY-SA 3.0 |
Active reading. [<https://en.wiktionary.org/wiki/head-scratcher#Noun>]
|
May 19, 2017 at 15:49 | comment | added | user177800 | enables creation of good, useful content is not the same as eliminates less than useless incorrect information, it still perpetuates the Balance Fallacy. | |
May 19, 2017 at 14:50 | comment | added | Vasudha Swaminathan StaffMod | @Jarrod Roberson,@ssube - We agree not all of the content created is good or more importantly 'correct'.Jon says it a few times above eg. - "fundamentally the structure we provided isn’t working and the artifacts being created don't serve users particularly well".While we are revisiting structure, we're also figuring out the missing elements for these artifacts so as to provide a platform that enables creation of good, useful content - hence this post.The eventual move (when ready) will be a careful one. | |
May 19, 2017 at 14:34 | answer | added | spring | timeline score: 7 | |
May 19, 2017 at 14:31 | history | edited | Vasudha SwaminathanStaffMod | CC BY-SA 3.0 |
deleted 41 characters in body
|
May 19, 2017 at 14:27 | comment | added | user177800 | @JonEricson - well organized incorrect content is still incorrect content. incorrect content is the problem that needs to be solved, not how to organize it. | |
May 19, 2017 at 14:24 | comment | added | user177800 | @ssube is correct, easier to find examples that are wrong is actually making the internet WORSE. as long as the content is W3Schools level, changing the navigation/organizational structure will do nothing to make the content more correct. but no one seems to even offically acknowledge that this is a fundamental problem. | |
May 19, 2017 at 14:00 | answer | added | user177800 | timeline score: 48 | |
May 19, 2017 at 13:28 | comment | added | SeinopSys | I don't know if anyone suggested this here yet, but I'd like to see any and all reputation-giving incentives removed, or Docs should get a separate reputation counter. I'm all for rewarding people who contribute but only those whose contributions are for the sake of helping others not for racking up points by copy-pasting in other documentation on the Internet. | |
May 19, 2017 at 13:16 | answer | added | PM 77-1 | timeline score: 23 | |
May 19, 2017 at 13:12 | comment | added | ssube | One of the biggest problems with Documentation now is the content. The system has been encouraging poor content, and even if you revise the system, keeping that content will kill any future iterations of the product. If you're going to start over with the idea, you need to start over with the content, or it will look and feel (and be) the same thing with a new GUI. | |
May 19, 2017 at 11:48 | answer | added | theGtknerd | timeline score: 9 | |
May 19, 2017 at 10:29 | comment | added | l4mpi | "This isn’t something we can address by tweaking a few features; it’s the foundation of the entire product." - yes, agree entirely. "Let’s work together to find a way of organizing and creating Documentation that’s better than what we have now and, perhaps, revolutionizes the entire genre of documentation!" - and you lost me - that's still the same kind of delusional crap that caused the current mess. This feels more like revolutionizing the act of shooting yourself in the foot by continuously iterating on a product that adds no value, as @JasonC said. | |
May 19, 2017 at 10:27 | answer | added | user128511 | timeline score: 4 | |
May 19, 2017 at 8:01 | comment | added | user694733 | "Should I keep contributing to the Documentation beta? Yes, please." Wouldn't it be better to start from scratch? It would be easier to be strict about the new content than cleaning out the bad content to fit the new model. | |
May 19, 2017 at 7:04 | answer | added | Lorenzo Dematté | timeline score: 110 | |
May 19, 2017 at 4:48 | comment | added | Mr. Alien | It feels like this thing is dragged every time when I see a new post. | |
May 18, 2017 at 23:13 | answer | added | Travis J | timeline score: 16 | |
May 18, 2017 at 22:53 | comment | added | pylang | As one who uses Python, I find a centralized repository of idiomatic examples across application spaces to be valuable. Although I would appreciate an easier way to search for examples, it is worth having Documentation. | |
May 18, 2017 at 22:15 | comment | added | Jon Ericson Staff | @TotZam: You mean like only allowing people we know are working programmers to contribute? Well, that's one way to increase people filling in their Developer Stories, I suppose. ;-) At the moment, restricting participation is not our focus. In it's current state, Documentation isn't exactly appealing to people who like their content well organized, so we ought to fix that problem first. | |
May 18, 2017 at 22:08 | comment | added | Tot Zam | I think one of the biggest issues with the current documentation is who is allowed to add information, and who is allowed to approve changes. Will there be more restrictions added to this new documentation, to somehow encourage contribution to come from professionals? | |
May 18, 2017 at 21:46 | answer | added | Draco18s no longer trusts SE | timeline score: 17 | |
May 18, 2017 at 21:26 | answer | added | Nicol Bolas | timeline score: 65 | |
May 18, 2017 at 21:18 | comment | added | TylerH | @Jaydles Sure, I just mean that much of Documentation just spec-esque information, e.g. objects, properties, methods, syntax, etc. rather than merely introducing some aspects of a language and then providing some useful examples of those aspects. | |
May 18, 2017 at 21:09 | answer | added | Kuba hasn't forgotten Monica | timeline score: 48 | |
May 18, 2017 at 21:00 | comment | added | Jaydles Staff | @TylerH, I'm not sure it'll be more example oriented than the current version (which is pretty darn example-oriented). I think we still believe one thing existing docs elsewhere are lacking is enough good examples, but we're gonna keep an open mind as to what's actually most important to make these as useful as possible. | |
May 18, 2017 at 20:42 | answer | added | Monica Cellio | timeline score: 135 | |
May 18, 2017 at 20:35 | comment | added | Jon Ericson Staff | @TylerH: Pretty much. The other element is that we are going to build from specific cases instead of designing top down. Oh. And we are going to be getting more focused feedback and testing our ideas more frequently. | |
May 18, 2017 at 20:31 | comment | added | TylerH | What I got out of this was that they are going to rework the foundation of Documentation to be more example-oriented and to let users have more flexibility in the way Documentation pages are laid out (e.g. a Docs page on T-SQL naturally calls for a different layout/approach than a Docs page on JavaScript or CSS). Is that an accurate assessment? | |
May 18, 2017 at 20:27 | comment | added | Jon Ericson Staff | @Goose: I probably should have left a comment on that question. Vasudha and I were really interested in reading it and thought it was an interesting idea. In fact, let me comment there now. | |
May 18, 2017 at 20:26 | history | edited | TylerH | CC BY-SA 3.0 |
missing word
|
May 18, 2017 at 20:06 | comment | added | Jon Ericson Staff | @Ðаn: Business decisions certainly play a part. As soon as you hire your first employee, money has to be a concern. But in my experience, Q&A features aren't ignored because of business. Rather they tend to be risky, hard to implement, low return on investment or a combination. That's why we need projects like Documentation. Even if it fails, we'll have some things to take back to Q&A such as "don't ever do X" or "Y turned out to be useful in these limited situations". Complicated systems like Stack Overflow are hard to maintain. | |
May 18, 2017 at 19:56 | comment | added | Goose | @JonEricson This was the suggestion I brought up previously in meta. meta.stackoverflow.com/questions/348407/… | |
May 18, 2017 at 19:37 | comment | added | Jon Ericson Staff | @Goose: So that I know I understand, do you mean somehow bring answers into the Documentation space? | |
May 18, 2017 at 19:35 | comment | added | Jon Ericson Staff | @Ðаn: I think what's missing very much depends on what technology you are using. If you have used T-SQL (or any SQL, really) I'd appreciate your input on the sister question. | |
May 18, 2017 at 19:25 | history | edited | Jon EricsonStaff | CC BY-SA 3.0 |
I wish I could edit _every page on the internet_.
|
May 18, 2017 at 19:11 | comment | added | Pekka | What @JasonC says on the top was always how I personally thought SO envisioned documentation - a platform that is so great to build documentation with that product owners and advanced devs would flock to it and want to do everything with it and ditch whatever they were using right now - with community contributions, editing, and examples added for flavour. Not just a sign put up on an empty field asking everyone and their dog to "contribute" stuff that mostly already exists elsewhere in the eternal quest for reputation points. | |
May 18, 2017 at 18:57 | comment | added | Goose | I've brought up similar ideas in meta but I'll repeat it here now that substantial changes seem more on the table. Utilize the existing wealth of knowledge on Stack Overflow in Documentation. I dislike the idea of having them be silos when there's an extreme amount of overlap between the two. | |
May 18, 2017 at 18:40 | answer | added | enderland | timeline score: 56 | |
May 18, 2017 at 18:34 | comment | added | user4639281 | @JanDvorak "Exactly like before, except a completely different structure (or structures) that the community will have some kind of input in, much more testing and user input, all built off of actually trying to write documentation on a given product then asking people to review the documentation that we've made to make sure that it checks all the boxes." So exactly the same, but completely different. Basically they're keeping the "Examples first" concept, and putting everything else up for debate. | |
May 18, 2017 at 18:34 | comment | added | Jon Ericson Staff | @JanDvorak: More like: "we're going to test samples early and often". We built the private beta in isolation and didn't change the fundamental structure and elements since. That's a mistake I hope to avoid in the future. | |
May 18, 2017 at 18:28 | comment | added | John Dvorak | I'm not in great shape for reading right now, but is the tl;dr "exactly like before, except we'll provide some examples of what we actually want this time"? | |
May 18, 2017 at 18:25 | comment | added | Jon Ericson Staff | @TinyGiant: That's a great insight. I think we mostly focused on functions (hence Syntax and Parameters). We should have known that wasn't going to be universal when we started writing Example Databases and Tables topics. | |
May 18, 2017 at 18:25 | comment | added | Jaydles Staff | @TinyGiant, I think you're probably right. The "H1" header sections you'd want for a given type of docs page seem to vary a lot. That's what the new approach will (hopefully) flush out - you'd need these sections for this, these others for that. Which ideally gets to a few choices, etc. | |
May 18, 2017 at 18:22 | comment | added | user4639281 | I keep coming back to the thought that there needs to be multiple types of pages. When you're documenting a concept, the structure of the page should probably be different than when you're documenting a function. | |
May 18, 2017 at 18:17 | comment | added | Jason C | Unless you rework docs to be a service that provides product developers with a documentation platform that is smoother and easier to maintain than their own web sites or GitHub readmes or whatever, with a search function that yields more effective results than e.g. Google and is as or more convenient than typing search queries in your address bar, I can't see this ever adding value to the internet; it's a really fundamentally flawed premise no matter how many tweaks you try and make to it. | |
May 18, 2017 at 18:02 | history | asked | Jon EricsonStaff | CC BY-SA 3.0 |