61–70 of 136 posts
It should not be used to add redundancy. And it should not be used to accumulate cruft that doesn’t belong in any manual or list of examples. People have already gone for low-hanging fruit; for instance, do we really need examples of how to initialize a list?
What I'm most worried about is the duplication between the canonical documentation of a project and the StackOverflow one. As the author of an open-source project, I try my best to write a great documentation, and I would be a bit annoyed if people started to add examples to StackOverflow just to gain reputation there instead of contributing to the "official" one. Also, SO is ranked way higher than the smaller-projec…
There's one question I saw on Stack Overflow a while back that irritated me. If you copied and pasted the literal question directly into Google, the top hit was directly to the canonical documentation, where you could just scroll down to the clearly marked heading, and copy and paste the sample code and have it work straight away. When I pointed this out, I was berated for not understanding that Stack Overflow is try…
If the canonical documentation is more helpful to more people, it should rank higher. If Stack Overflow Documentation is more helpful, _it_ should rank higher.
It doesn't hurt to try to create a resource that might end up being more useful to more people. But until it really is, it needs to be ranked as so.
Great idea I especially appreciate the fact that its done by example. A couple of things that bothered me are: 1. The UI needs some refinement. I was looking to find a topic to post about and from my 10 minute browse I realised that if I was meant to find information in this documentation it's really hard to find what you are looking for. After you drill down to a tag it feels "unstructured". Readthedocs layout feels…
The UI needs some big improvements indeed. I toyed around with the site and although I could find my way around when just clicking through some topics, I am still confused as to what the structure of the site is (other than a list of topics, with a list of examples, not hierarchically structured or Q&A style or anything else that would make sense). I'm not sure I could find anything on here if I didn't get there via…
This is awful, another trick site that fools people into doing work that they could be getting paid to do, all for the joy of getting some "karma." Well kids, karma ain't gonna pay the rent. If you want to get experience volunteering to write documentation for software, then find the existing official documentation and add to that (or start it, preferably in a repository close to the actual code). Any profits that ge…
The worst part, imho, is moderators not getting a dime for all the work they do.
They're the ones that really run the Stack Exchange sites.
I like the concept (reminds me of gobyexample.com) but this really isn't documentation. Instead of more code snippets I want high quality annotations (like snippets!) atop official documentation. If more people were driven to canonical docs but with a guiding hand I think we'd see more people actually understanding the code they write.
Edit:
Apparently they do it already: http://genius.com/web-annotator
This is awful, another trick site that fools people into doing work that they could be getting paid to do, all for the joy of getting some "karma." Well kids, karma ain't gonna pay the rent. If you want to get experience volunteering to write documentation for software, then find the existing official documentation and add to that (or start it, preferably in a repository close to the actual code). Any profits that ge…
The same could be said about the general idea behind Stackoverflow, except it's wrong. Sure, it's "free labour for internet points" but so is posting a project to Github and wanting stars. You're forgetting that it genuinely helps other people in your industry. Stackoverflow is an amazing resource for programmers, pretty much every question I type into google relating to a library or some software comes up with 3 or…
Earlier quoted context omitted.
There's one question I saw on Stack Overflow a while back that irritated me. If you copied and pasted the literal question directly into Google, the top hit was directly to the canonical documentation, where you could just scroll down to the clearly marked heading, and copy and paste the sample code and have it work straight away. When I pointed this out, I was berated for not understanding that Stack Overflow is try…
Honestly, this seems more like a problem with search algorithms than Stack Overflow. If the canonical documentation is more helpful to more people, it should rank higher. If Stack Overflow Documentation is more helpful, _it_ should rank higher. It doesn't hurt to try to create a resource that might end up being more useful to more people. But until it really is, it needs to be ranked as so.
For example, Flask [1] has a great and complete documentation, but still someone is starting to duplicate it on SO Docs. Why are we wasting time duplicating things instead of improving what's already there?
Earlier quoted context omitted.
I think they should link back to the official documentation wherever it makes sense. They could even automatically import official docs into their system if the license permits that and a standard tool is used.
They would still outrank your official docs. Just like wikipedia, they add nofollow to their links, meaning the links mean nothing in the eyes of Google. Instead of having some innovation when it comes to spammers, wikipedia and stack overflow punish the original content creators.
What I'm most worried about is the duplication between the canonical documentation of a project and the StackOverflow one. As the author of an open-source project, I try my best to write a great documentation, and I would be a bit annoyed if people started to add examples to StackOverflow just to gain reputation there instead of contributing to the "official" one. Also, SO is ranked way higher than the smaller-projec…
There's one question I saw on Stack Overflow a while back that irritated me. If you copied and pasted the literal question directly into Google, the top hit was directly to the canonical documentation, where you could just scroll down to the clearly marked heading, and copy and paste the sample code and have it work straight away. When I pointed this out, I was berated for not understanding that Stack Overflow is try…