I don't really have a problem with docs in theory. A lot of languages don't have the support that we do. And even in Python there's some things that could be added that will work. But DAMN the execution has been bad.
Just think about what we have been doing with the canon, collecting great answers covering actual worthy topics. In theory, docs would be a place where those topics would be covered properly. And that’s probably what it’s going to end up as at some point. But this is all done by duplicating resources that already exist, discrediting the original contribution on Q/A.
I don't get the excitement over sqlalchemy topics. The sqlalchemy official docs are really nice on their own, contain a lot of good examples. People will just end up posting that same stuff just to earn rep
@poke yeah. but i'd just make a topic, put the official doc link and call it a day (or something like Ffisegydd did for matplotlib) :P Why take the pain to copy paste the whole thing?
@Quill You mean questions about writing docs? In my opinion, if people need help to write docs content, then they probably shouldn’t attempt to write docs in the first place?
@ChaoticTwist Link-only is lazy and probably not rewarded; but if you copy lots of content, then it looks like you did a lot of things and it still takes little effort
I vaguely remember Flask had issues with keeping docs up to date because it was mostly $flask_author doing them and no easy way to break it out, so this could solve that, perhaps
> Like a string, a list is a sequence of values. In a string, the values are characters; in a list, they can be any type. The values in a list are called elements or sometimes items.
I really don't understand how everyone at SE can think these Docs are amazing. Do they have some leverage on their staff or something? Is it blackmail? Or maybe brainwashing?
If I was an evil man (I am) then I'd go through and edit every single print statement to be a function. Think of all the delicious rep you'd get over time.
http://stackoverflow.com/documentation/python/2169/interval-comparison#t=201607221001437908328 (SCREW OFF SO IF I WANTED IT ONEBOXING I'D HAVE LEFT IT ON ITS OWN NOW I'VE GOT TO CODEIFY THE LINK AND MAKE IT REALLY LONG) should maybe be in a topic that deals with boolean stuff, not on its own.
It could have been a great place for collaborative docs that are OT for SO or can't be covered on an external site easily, but in practice it's just bad.
It's also probably much better/less annoying for communities with bad existing docs.
But a lot of the stuff I'm seeing is "Well, this is worse than the standard docs..."
OTOH, even when done well, a nice juicy pool of examples will feed cargo-culters, as Andras and I said earlier. I guess that happens with the main Q&A site too, but I get the feeling that Docs will be worse for that.
@poke " Yeah, and require a bronze badge to contribute or something " That makes sense to me. Letting low-rep noobs create and edit stuff is madness, even with an approval system, unless people with actual topic knowledge are in the loop.
@AnttiHaapala Sure. Overall rep is a reasonable indicator of general SO competence. But for documenting language stuff, I think needing a badge in that language is a reasonable requirement. For special topics, needing a badge would not be practical
There are a lot tags on Stack Overflow which don’t really cover a topic you could write a documentation about. A lot of these are tags which are about a (named) concept that exists in multiple languages.
Currently, we get a lot documentation proposals for these topics. Here are just some example...
@AnttiHaapala as someone stated before, the whole sqlalchemy doc is a bit pointless, as the official docs are very good and contain basic examples etc. Tried writing stuff there, ended up just repeating the official docs pretty much.
2 years ago I was arguing with a python core dev (Ezio Melotti) about porting; his view was that you should fork all codebase for python 2 and 3 and maintain separate versions of them.
@AndrasDeak this is one point of documentation, there can be several distinct ways of doing things in examples
With many topics, there are a few common warnings or pieces of advice that keep cropping up. For example, with Git, there is the warning that a certain command deletes information permanently, and there is also the warning that history shouldn't be modified on branches that you're collaborating o...
Especially for parameters section. Example CSS - Selectors
Should there be a line in the suggestion box that encourage contributors to put in the official API document or specification links? That would be very helpful.
> If we want this to be used, if we want this to actually work, then sooner or later we gotta figure out how to make this work on Stack Overflow. Yes, that's gonna be painful at times. Like ripping off a band-aid. Remember how awful suggested edits were? That was tiny compared to this. Eventually, we'll work out the problems.
When i try to write something with those characters like <Type> while editing the syntax section the wrong error shows up (Syntax must be formatted as a list of one-liners) and i can't publish my changes.
Work-around: Use < >.
As per my comment:
Can someone please clarify the scope of the docs please. The blog post says examples are king, but what I see right now is people adding more or less random topics. What is the point of reiterating the Q&A of the main site? I would understand if docs was for user created AP...