
Introducing Stack Overflow Documentation Beta - sklivvz1971
http://blog.stackoverflow.com/2016/07/introducing-stack-overflow-documentation-beta/?cb=1
======
pietroalbini
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-projects' documentation on
search engines, pointing developers there. This can be problematic, for
example, if a big release comes out and the SO documentation is behind.

The documentation for a lot of projects is really bad, I know, but I prefer a
solution which doesn't disrupt the work of the mainteiners which writes good
and extensive documentation.

~~~
JimDabell
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 trying to _become_ the canonical source. Sure enough, a few weeks
later, the top hit on Google no longer pointed at the official documentation.
It pointed at that same Stack Overflow question, with a half-assed answer that
only gave a fraction of the information the real documentation did.

I appreciate Stack Overflow for its strengths, but it's harmful too. Being
able to go directly to the canonical source of information for a product and
do your job without anybody spoon-feeding everything to you is a vital
developer skill, and I'm seeing more and more people who won't bother to lift
a finger unless somebody does half their work for them. This project seems
like it will push the developer community much further down this path.

~~~
acjohnson55
To be fair, that best answer is totally editable by any user to be more
informative and/or link to the canonical source of information. There are few
projects whose docs have such low contribution friction, for better or worse.
And unlike project-specific documentation, it comes in one basic format and
set of norms.

I also don't think there's a problem of spoonfeeding information to
developers. If a developer at Company X tries to solve all their problems via
StackOverflow questions, waiting for someone to come save them, I'd have to
assume that this would manifest as them being blocked all the time. At that
point, it's up to their lead to teach them and hold them accountable for
exercising other ways of resolving their problems, including RTFM.

~~~
lstamour
I was just idling in the Documentation chat channel and based on what I was
seeing there, it appears links to sources are _discouraged_ on StackOverflow
documentation. Presumably, they're aiming to eventually host new content
that's better than what's already out there. I think it's a bit silly -- at
least make a Sources section where folks can click to view links to existing
docs!

~~~
recursive
Everyone knows that cool urls don't change, but the problem with links is that
not all urls are cool urls. Links rot over time.

~~~
theli0nheart
So the answer is to not use links at all?

~~~
sanbor
Put the content AND the link, instead of just the link. This way, if the link
changes the info will stay in SO.

~~~
true_religion
Wouldn't that be a copyright violation?

~~~
slavik81
Like in any other writing, a short quote is fine. If it's long, then you may
have to summarize the content in your own words.

------
akavel
In the footnote of the post they wrote they considered naming it "SO
_Examples_ ", but didn't. For me at least, using "SO _Docs_ " to name the site
is actually much more confusing. As a result, for the whole post I thought it
is a dynamic manual, with per-function docs and examples. Only after browsing
to the actual site I slowly realized it's not a manual: it's rather _a "book"
of examples_. A list of HOWTOs, speaking in a language of yesteryear. As far
as I see, it's impossible to build a MSDN in it. I couldn't add full
documentation for one of Go packages here — borders cross vague, overlapping
concepts, not clearly cut packages. To make it clear: I don't want to deny
that it can be useful — suppose as _examples_ for learning; but when looking
for _docs_ , I like being able to browse them systematically.

So, two possibilities: either something revolutionary I didn't fully grasp yet
— or _Examples_ , not _Documentation_.

For now, I much prefer the model of Go docs, MSDN, or PHP manual with user
comments — if talking about _docs_.

~~~
akavel
_(replying to self)_ Ok, I see now one area where it actually seems to make
much sense and looks like it can work very nicely: for stuff like _git_ ,
_vim_ / _emacs_ , _bash_ , etc. Generalizing, I'd say: for apps/services which
happen to have _abysmal, irregular UX /API,_ which often accrued/emerged
instead of being designed. A classical reference manual just doesn't work good
enough for them, because the "natural" edges/borders in the API are too random
and accidental. "SO Docs" as it is now can then organize the chaos, while
making it easier to _categorize_ & _improve_ than a typical wiki.

[http://stackoverflow.com/documentation/git/topics](http://stackoverflow.com/documentation/git/topics)

[http://stackoverflow.com/documentation/vim/topics](http://stackoverflow.com/documentation/vim/topics)

------
kyriakos
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 more user-friendly.

2\. To future proof the documentation examples should come with a version
number they apply to. For example there is PayPal and DropBox API examples
which in a few months might no longer be valid.

~~~
lucb1e
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 Google already.

~~~
eric_h
personally, google is how I always end up on stack overflow, so I'd imagine
the same will be true for this product.

~~~
lucb1e
19 out of 20 times, true. However I totally get how SO is structured and
contributing answers to people's question is something everyone gets. And if I
want to find other questions (like for marking a duplicate, or researching a
topic) I can use the search and tag system easily. Somehow the structure of
this documentation area is not very clear to me.

------
troymc
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 get made off this "documentation" (i.e. incoherent bag of
examples) will not flow to the community or company behind the software in
question. It's a parasite, leeching off the success of other projects which it
neither created nor cares about.

How did they get corporate partners for their launch? That's easy. It looks to
those companies like free labor.

~~~
orf
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 4 stack overflow links that _actually help me_. If they can take the
masses of questions which basically form ad-hoc documentation for tonnes of
projects and put them in a cohesive place then how is this a bad thing?
Because people don't get paid $0.01 per post or something?

Perhaps any advertising revenue from the docs site could go towards something
good, would this be better?

~~~
Theodores
That last point is an excellent idea, I could live with that, knowing the
project maintainers get ad revenue each time I look up my own examples and
examples by others. This is great.

~~~
fapjacks
I'm guessing that will never happen in any meaningful way, if only because
that's not as profitable as keeping everything they get.

------
rudedogg
Stack Overflow's point system is really annoying. I've been programming for
around 10 years, but because I don't participate much I can't even comment on
an answer.

A month or so ago I was stuck on a problem and thought I'd go through a tag
for something I'm familiar with, and submit some answers to try and get enough
points to be able to fully use the site.

One answer had a new programmer following a tutorial and using an old method
signature. I commented that the tutorial he was following is out of date, and
listed the correct method to use.

The person downvoted my answer, and then pasted (basically) the same code as
the answer to his own question and accepted it. I know I just had bad luck in
this case, but it's pretty frustrating.

Not allowing a user with low points to do some functions makes sense, but let
them submit content and allow other users to determine if it's useful. I could
have (and wanted to) comment on dozens of answers, which would of helped out a
lot of people and saved them time/frustration.

~~~
jsmeaton
Not being able to comment at low karma is a cause of low quality answers from
new users. They post answers that should be comments, and get down voted to
hell. I think account age should also factor into a few of the low karma
thresholds like being able to comment.

------
JamesBaxter
If this gains traction I don't think we'll feel the benefits till a little
later down the line.

I've contributed a little to the Swift tag but the real advantages come from
technologies that don't already have good documentation.

I'm considering starting a tag for the enreco HTML -> PDF generator I use
quite a lot as the official documentation isn't great.

~~~
Kiro
> enreco HTML -> PDF generator

What is that? Googling it only brings up this comment thread.

~~~
edgarvaldes
Top result for me:

[http://www.nrecosite.com/pdf_generator_net.aspx](http://www.nrecosite.com/pdf_generator_net.aspx)

------
greggman
I'm actually very conflicted about Stack Overflow in general and of course the
new documentation section as well.

For whatever reason I answer many (most?) of the WebGL questions. At some
point I felt I needed to make longer form answers with better working examples
so I made [http://webglfundamentals.org](http://webglfundamentals.org)

But, now there's this huge conflict. I spent a couple hundred hours on making
webfundamentals.org but when someone asks a question on stack overflow I'm not
supposed to just link to whatever I wrote. I instead I'm supposed to
effectively transfer all my content to SO. Something about that just feels
wrong. SO is making money from the content I created which feels a little
weird (yes I know I get other people's content back). Also, while I get that
SO's gamification is part of what has made it so successful it's also feels
like it turns many things into a competition. I try to tell myself don't worry
about those points I'd be lying if I said they didn't affect me at all in
various ways.

Taking all that and adding to documentation, as an example, when I contribute
to MDN I feel like I'm doing something purely positive. But if/when I
contribute to SO Docs I already know I'm not going to feel the same. One
reason is because SO Docs will be making money from my work. The only thing I
get in exchange is some "score" on my name I can maybe use to get a job. Maybe
that's a fair trade since I don't get a score on MDN?

I'm not sure how to make my point. I love that I find answers on SO but
something just doesn't feel right and I don't know how to express it.

~~~
Flimm
Links to what you wrote are welcome on SO and always have been, but link-only
answers are not. Just summarise what you link to, and then recommend the link
for the full answer.

------
IshKebab
This is awesome. I can't count the number of times I've found an Android
function that has almost no documentation. I usually post a question and
answer on SO if I work out how it works.

I only wish it were organised a bit more like normal documentation - i.e. into
classes and methods. Might make it easier to find things.

~~~
cag_ii
Have you considered/tried adding back to the official documentation in cases
like these?

~~~
IshKebab
Yes and yes. They just ignored my contributions.

------
michaeldwan
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.

~~~
giancarlostoro
Like genius.com but for code documentation? :)

Edit:

Apparently they do it already: [http://genius.com/web-
annotator](http://genius.com/web-annotator)

------
jackcarter
I hope they release a private enterprise version, like they have for
StackOverflow[0]. I'd love to host this on-prem to document my company's
codebase.

Anyone know of a similar solution that's available now?

[0] [http://meta.stackexchange.com/questions/16054/is-the-
stack-e...](http://meta.stackexchange.com/questions/16054/is-the-stack-
exchange-engine-available-for-use)

~~~
evoltix
I would definitely be interested in this as well.

------
newman314
I understand this is (for now) for devs. I would love to see an equivalent
(including private offering) for infra.

Getting people to document things on the infra side is deplorable in general
and I would love to try anything that helps improve that.

~~~
specialist
"infra"? Quick google search did not illuminate me.

~~~
newman314
Infra as in infrastructure....

------
metakermit
Cool new project – I think it might become very helpful one day. Documentation
for a lot of open source projects is pretty bad and having to figure out a new
contributing workflow every time just to hop in and help a bit is quite
problematic. Hopefully, the unified interface SO users are used to will give
docs writing a big boost.

That said, I still hope they output some sort of GitHub repo of all the
accepted changes to make it a bit less walled-gardeny. A CC license is nice
and all, but having the content in a repo as well would put my mind at ease.

~~~
mattip
The CC license used for stack overflow content is horrible. I have asked
multiple lawyers what it means for cut-and-pasted code, and have yet to
recieve a clear a definitive answer

\- is it viral when compiled into a binary, or when used in scripts?

\- how to attribute?

~~~
wool_gather
The license _for code_ changed earlier this year:
[http://meta.stackexchange.com/questions/271080/the-mit-
licen...](http://meta.stackexchange.com/questions/271080/the-mit-license-
clarity-on-using-code-on-stack-overflow-and-stack-exchange) to MIT. It's not
retroactive, though.

------
reitanqild
Really curious to see if this succeeds, fails like discourse or gets overrun
by what I consider to be a major destructive faction of nitpicks and
deletionists on SO.

~~~
morgante
Has Discourse failed?

~~~
reitanqild
Tell me about how it compares in usage to any of the solutions it set out to
replace :-)

Or tell me about where people are using it to discuss every question that is
not fit for SOs questions/answer format.

------
makecheck
I feel like this might be best used to document _unexpected_ behavior or
_stupid_ things that maintainers may be too proud to acknowledge in their
official manuals.

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?

------
krat0sprakhar
If anyone is wondering how this looks and is impatient to read the blog post,
here's an example Documentation page for Java Streams -
[http://stackoverflow.com/documentation/java/88/streams#t=201...](http://stackoverflow.com/documentation/java/88/streams#t=201607211226138669707)

~~~
elygre
Yep, examples with bugs.

------
jstoiko
This is cool.

It would be nice to have an API for this so that my IDE can pull these
examples.

------
RyanHamilton
Awesome! I've actually been working on a java IDE that allows uploading
examples together with the results to a website:
[http://jpad.io/example/1s/generating-random-int-array-
within...](http://jpad.io/example/1s/generating-random-int-array-within-range)

The idea is to build up libraries of examples in different areas, allow easy
code sharing and to remove some of the cruft needed. It's good to see
stackoverflow hit this "code examples" area better.

------
simonswords82
So this makes Stack Overflow a library of example code curated by people who
already frequent their website. Am I reading that right?

~~~
metakermit
I think this will be separate from Stack Overflow Q&A, if that's what you were
aiming at. SO Q&A will still target specific examples. But yes, the new SO
Documentation project will be code examples and explanations curated by
presumably many existing SO users.

------
bouh
I really hope that all open source documentation quality will increased by
adopting such kind of tools. The fact that SO is used an informal
documentation was a strong signal that there were much improvement to be done.
I am just sad because I wanted to work on project like that :'(. Great job SO
!

------
rohanpai
This is super cool!

I am interning at Sourcegraph and we have heard devs want better usage
examples too, so we automatically show all uses of any function

check out:
-[https://sourcegraph.com/github.com/golang/go/-/info/GoPackag...](https://sourcegraph.com/github.com/golang/go/-/info/GoPackage/net/http/-/NewRequest)
\-
[https://sourcegraph.com/github.com/golang/go/-/info/GoPackag...](https://sourcegraph.com/github.com/golang/go/-/info/GoPackage/encoding/json/-/Encoder)

------
d2ncal
While this sounds like a good idea and will probably do well, it also
centralizes more critical information and access to one for-profit company and
product.

I really wish that we as a community would spend more effort towards better,
decentralized systems.

------
RyanHamilton
Awesome! I've actually been working on a java IDE that allows uploading
examples together with the results to a website:
[http://jpad.io/example/1s/generating-random-int-array-
within...](http://jpad.io/example/1s/generating-random-int-array-within..).

The idea is to build up libraries of examples in different areas, allow easy
code sharing and to remove some of the cruft needed. It's good to see
stackoverflow hit this "code examples" area better.

------
grkvlt
[META] This is popular, but is there a way to notify the mods of duplicates so
that conversation doesn't get fragmented? I flagged
[https://news.ycombinator.com/item?id=12135897](https://news.ycombinator.com/item?id=12135897)
and
[https://news.ycombinator.com/item?id=12136086](https://news.ycombinator.com/item?id=12136086)
but I don't know if that's the right thing to have done?

~~~
detaro
linking to the more active discussion(!) and then flagging is the correct
thing. If you do it before other comments have been added, this even flags the
post as [dupe] automatically.

------
vorg
Didn't see the word "test" in the article (except once talking about beta
testing S.O.'s new product). And the word "test" isn't in these comments
either, so...

Will updated examples be run through a program testing them in some way? If
not a full run within a playground-style environment, then through a type
checker?

And will the examples be tagged with version numbers? Some programming
languages are notorious for changing syntax and/or semantics between minor
versions.

------
krick
I really don't want people to start using something like this instead of
improving the official documentation. I hate the fact it probably cannot be
helped.

To "do the same thing for docs that we did for Q&A"? Yeah, except there just
was no sane platform for Q&A before. And for docs there is, you know… the
docs!

~~~
0xffff2
"The docs" are remarkably inconsistent between projects. "The docs" for C#
really don't need any help, "the docs" (by which I mean the AFAIK unofficial
cppreference.com) for C++ are fine. But even major languages like Python don't
have the greatest documentation, never mind the thousands of libraries out
there that have wildly disperate levels of official "docs".

~~~
krick
Exactly, and this should be fixed individually per project. If this is open-
sourced project, you can contribute to the docs. If not — well, if not
protected by some license, there will be side-projects with documentation, or
you can make your own. But there should never be competition between actual
documentation and some fucking for-profit organization, exactly for this
reason: the documentation often is bad, and this can, and should be fixed.

------
tongcx
It would be nice if there is SO for business. Lots of companies have terrible
internal documentation, Q/A tools.

~~~
pinky07
Odoo Q&A is an open source clone of stackoverflow:
[https://www.odoo.com/page/community-
builder](https://www.odoo.com/page/community-builder)

It has three mode: forum, Q&A (clone of SO), share links (like HN)

~~~
tongcx
Very cool. Would be great if three functionality can be supported: transient
chat, persistent Q/A and persistent documentation. The same for Stack
Overflow. They may make a big profit if business start to use it.

------
allendoerfer
I think a big problem is user motivation. On Q&A sites you get the reward to
directly help someone and have a conversation. This is missing for
documentation. I wonder if their gamification is enough to motivate people or
whether they have to find a deeper human desire that they build into this and
satisfy.

~~~
senex
Besides karma, I wonder if users will be motivated by career opportunities?
Contributing to documentation could be a good signal to recruiters that are
looking for experts in a particular technology.

------
jcastro
Anyone know if there are plans to roll this out to other stackexchanges? Would
love to have this on askubuntu.com.

------
jbrooksuk
Odd.

Couldn't find blog.stackoverflow.com The Q&A site blog.stackoverflow.com
doesn't seem to exist…yet.

You can vote for it to be created through our democratic, community-driven
process at area51.stackexchange.com, or see a complete directory of all our
Q&A sites at stackexchange.com.

~~~
df07
The blog was down for a bit and falling through to the generic Stack Exchange
network handler, which is what you saw. It should be working now.

------
lucaspottersky
there's gotta be an integrated way to copy&paste examples (i.e. via
autocompletion/snippet) from SO to our favorite code editor/IDE :D

------
iamrohitbanga
Can we use existing SO answers to curate documentation?

------
ofcapl_
looking forward for some standarized integration with github's wikis

------
anotherevan
Will be interesting to see what the moderation guidelines will be like, and
how zealously they are "interpreted".

------
speps
Will there be an example of a bad regular expression that could take down a
website?

