Timeline for Is Documentation failing?
Current License: CC BY-SA 3.0
20 events
when toggle format | what | by | license | comment | |
---|---|---|---|---|---|
Dec 14, 2016 at 23:18 | comment | added | Confused | Q&A could be tiered to provide that facilitation, as it's already housing that sort of stuff, and changed the way people think about Q&A in programming, to this model, and condescension towards anyone else not aware of it. That's what I mean by a lack of self awareness. @NicolBolas | |
Dec 14, 2016 at 23:03 | comment | added | Nicol Bolas | @Confused: "As to the original idea SE idea had... that's even weirder." ... why? A public place to put common pieces of code is not an unreasonable thing. It fits more closely with the Q&A model, since we do have lots of bits of code here. | |
Dec 14, 2016 at 23:02 | comment | added | Nicol Bolas | @Confused: "This is a false equivalency." No, it isn't, and you've essentially proved my point. The reason Apple's techs don't have such documentation is not because SO has failed to provide a place for it. It is because the people who have domain knowledge are not willing to create the information for it, whether such a place exists or not. So even if Docs.SO was a great place for documentation, it still wouldn't have good docs for Apple technologies. | |
Dec 14, 2016 at 22:07 | comment | added | Confused | As to the original idea SE idea had... that's even weirder. That means they have no self awareness, and can't see their own impact on the zeitgeist of computing. Very odd. @NicolBolas | |
Dec 14, 2016 at 22:06 | comment | added | Confused | TL;DR; they're competitive, rushing to make money as soon as they can, in the mad stampede that continues... unabated. They're still apprehensive about their future, not secure in it as C++ programmers are. And this is the case for many of the platforms and languages of programming. C++ programmers are the most (or second most) secure programmers. Plus, what you're showing only deal with a language, not the myriad of frameworks that are Apple, and not newness of language - Swift. This is a false equivalency. But your question of motivation is relevant. Bigger than this space, tho @NicolBolas | |
Dec 14, 2016 at 21:37 | comment | added | Nicol Bolas |
@Confused: "Apple's documentation is woeful, sparing, out of date and getting progressively worse." Then why haven't developers who work with Apple technology fix that? Four years ago, you could have said the same about C++ and its standard library. cplusplus.com was an OK site, but it was error-prone and slow to update. Then someone made cppreference.org , which is the go-to reference for C++ now. If Apple users were interested in making documentation, they would have done so with similar technology by now. How would SO having a docs site make them want to write docs?
|
|
Dec 14, 2016 at 21:32 | comment | added | Nicol Bolas | @Confused: The reason that it is example-focused documentation is because the original idea SE had was that they would make a sub-site for examples. That it would be a curated collection of pre-built source code for doing certain things, not that people would consider this "documentation". That notion was added later, like some kind of tumor. So it's not that they "ignored common sense"; it's more that they started with one idea that mutated into something else, with neither part able to work with the other. | |
Dec 14, 2016 at 21:28 | comment | added | Confused | Rather than analyse and understand where needs are (for documentation), and what a better form of documentation may look like, SO.docs designers ignored common sense, dug a hole they thought they understood, to be filled in by people they presumed would come, for reasons they thought they knew. That's a string of fundamental flaws that are unrecoverable. Just burn it down, and think over, with fresh insight and a genuine compassion for all potential users. You know... like a product manager would do. @NicolBolas | |
Dec 14, 2016 at 21:24 | comment | added | Confused | @NicolBolas the example-focused documentation "concept" isn't a good idea... at all, in its own right. I've not touched that aspect because its issues seem self evident, are compounded by the naming, and there's some semblance of recognition of this aspect of SO.docs problems. But let's look at your point: that there's not enough people in those spheres badly documented. Nope. That's not true. Apple's documentation is woeful, sparing, out of date and getting progressively worse. They're not the only high profile platform letting documentation slip. They're the norm. There is a need. | |
Dec 14, 2016 at 16:02 | comment | added | Nicol Bolas | @Confused: "Imagine documentation having started with computing spheres that aren't well documented rather than saying "we're the new home for ALL documentation."" That would change nothing. The reason that those "computing spheres" aren't very well documented is because there are not enough people to want to document them. Docs.SO could not change that, no matter how it was implemented. Furthermore, Docs.SO's example-focused documentation is very different from normal documentation. So even as a means of documenting less well-documented stuff, it would take some getting used to. | |
Dec 13, 2016 at 20:16 | comment | added | duplode | @Fluidity "I was hoping SOdocs would become the new, only place for docs ^-^" -- That would never work. The naysayers in the original Docs proposal Q&A covered many of the reasons why that wouldn't fly. Check the first half-dozen or so answers there below the very first one, as well as this one, which gets straight to the point. | |
Dec 13, 2016 at 17:18 | comment | added | Confused | @CodyGray Google Glass demonstrates Google doesn't really understand users of computers. It showed they had a clear focus on their own desires for computing's powers, and absolutely no idea what people wanted from an AR screen in front of them. We know Google wants Android, Search, Location and Image scanning EVERYWHERE, ALL THE TIME, and to give us ads based on what we see, where we are, who we're with, what we're doing etc. But what Page or Serg want isn't why people use computers and Google. SO.docs demonstrates SO's leaders don't understand writers, illustrators, readers and learners. | |
Dec 13, 2016 at 17:12 | comment | added | Confused | @CodyGray Imagine documentation having started with computing spheres that aren't well documented rather than saying "we're the new home for ALL documentation." Imagine if they'd realised the skills required to write good documentation are different than being good at asking and answering specific questions. Imagine they realised the ability to assess and edit documentation is an entirely different skill, too. Instead, their hubris lead them to focus in on what they wanted, merged with "if we build it, they will come" absent knowing who they are, what they need and why they do things. | |
Dec 13, 2016 at 16:26 | comment | added | Fluidity | @CodyGray exactly, except I was hoping SOdocs would become the new, only place for docs ^-^ because SO rocks... | |
Dec 13, 2016 at 13:36 | comment | added | Cody Gray Mod | This seems like a long-winded way of saying that Google Glass and SO Docs are both a solution in search of a problem. It turned out that no one really wanted to wear a smartphone mounted on their head, and it turned out that no one really needs yet another place for documentation. | |
Dec 13, 2016 at 1:42 | comment | added | Confused | Suffering from @NathanTuggy's myopia? You ask questions of Google, it responds. You ask questions of SO's community, it responds. These are responsive environments, inherently unbalanced because those asking don't know what they don't know, nor what the system/others know, or even how it'll respond. Within this environment there's sufficient imbalance to architect and orchestrate rules evolvement and enforcement. Google Glass, VR & documentation platforms require creatively motivated contributions for success. Google, Facebook and SO are good at rules in imbalance, not spurring creativity. | |
Dec 13, 2016 at 1:20 | comment | added | Confused | @NathanTuggy I'd like to draw your attention to the part you missed, about SO.Q&A: "(as opposed to a responsive framework built on and of inherent imbalance)" Your other comments seem to fall inline with the degree of obliviousness required to miss this obvious reference. | |
Dec 13, 2016 at 1:10 | comment | added | Nathan Tuggy | On the face of it, similar equivalency would obviously seem to apply to Q&A, which was built by essentially the same group and has similar values of equality. This post completely fails to differentiate these, then compounds this by making unsubstantiated accusations of astroturfing, misanthropy, and fascism. (In particular, suggesting that any time some organization fails to consider criticisms adequately, it's because misanthropes are in power, is at once staggeringly misguided and remarkably unhelpful in avoiding such mistakes in the future.) | |
Dec 13, 2016 at 0:20 | history | edited | Confused | CC BY-SA 3.0 |
added 259 characters in body
|
Dec 12, 2016 at 23:28 | history | answered | Confused | CC BY-SA 3.0 |