


For instance, this page on using JSON in PHP would be links or embeds of answers to canonical questions on the topic of using JSON in PHP, such as this (no promise this is the best example).

I know this is an unconventional approach. Being practical though, I think it makes a lot of sense. The content already exists, is high quality, is already getting edits as facts change, and is usually posed in a documentation type manner.


  • 34
    So Docs would basically become like a structured archive of selected questions? – miradulo Apr 25 '17 at 16:33
  • 4
    @Mitch exactly. You can't use StackOverflow Q&A is made for searching, not browsing. What I'm suggesting could enable a user to browse StackOverflow Q&A like they do with Documentation. – Goose Apr 25 '17 at 16:36
  • 46
    This kind of has been my complaint from the start with Docs. If they want examples of code that can be found just search the questions and answers for the terms you are looking for. I really haven't been able to find anything in Docs but I can find a relevant question on SO normally in a minute or two tops. – NathanOliver Apr 25 '17 at 16:36
  • 5
    You mean, like, 99% identical homework questions? – ThingyWotsit Apr 25 '17 at 17:15
  • 12
    Some tag wikis are used for this, but they're not very useful because tag wikis are very well hidden. – Jeffrey Bosboom Apr 25 '17 at 18:24
  • 1
    i mean... it wouldn't exactly be "Documentation" at that point would it? – Kevin B Apr 25 '17 at 18:40
  • @JeffreyBosboom That's actually very true. stackoverflow.com/questions/tagged/… seems a much better place to learn PHP than stackoverflow.com/documentation/php/topics – Goose Apr 25 '17 at 19:17
  • 5
    @KevinB Yeah, it would be an FAQ. I don't think SO corp would accept that rebranding, but it would fit much better with SO's core competency. SO is great if you know what to search for, but if you just want to get immersed in some new language/library/feature to get a general feel for what it's about/gotchas, SO is really hard to usefully browse. – Jeffrey Bosboom Apr 25 '17 at 19:30
  • 4
    @JeffreyBosboom Tag wiki's could actually be a great starting point. Have the Q&A tag wiki + frequently asked questions, instead of the separate tags of documentation. – Jorn Vernee Apr 25 '17 at 20:41
  • 1
    Or enable a mechanism whereby one can export an answer (with or without its question) to the relevant Documentation area. Right now, the two are far too separate -- tighter integration would yield better usage of Documentation at least? – Alex Apr 26 '17 at 10:35
  • 4
    What if people just read the canonical Q&A posts straight away? It is admittedly terribly hard to find the nice ones in the flood of crap. So maybe focus on improving that, instead of beating the dead Documentation horse. – Lundin Apr 26 '17 at 14:09
  • Be careful what you ask for. This will just become another "tab" or "section" within docs. We have topics, and now we will have a new section probably called "Q&A". I actually like the idea because that is what I would use. your examples are really just this the Q&A. Maybe the examples can simply be links to existing Q&A points and they would be one boxed as Travis has mentioned. – JonH Apr 26 '17 at 18:03
  • Hopefully this will decrease the number of questions asked in Documentation edits... </sarcasm> – Heretic Monkey Apr 26 '17 at 18:43
  • I would like to hear more details about this proposal. – Trilarion Apr 28 '17 at 11:40
  • 1
    I really like this idea. It's too easy to write something less than useful if you don't have an audience in mind. Answers have a built-in audience: the asker. But the problem I have using Q&A as "shadow documentation" is the answers are inconsistent. Some are little more than code samples and others are complete explanations. And the example code is inconsistent too. If the asker uses a bit of code in their question, the answers tend to copy and modify that code. If there's no code, the examples aren't much different from examples in Docs; they are whatever the author thought up at the moment. – Jon Ericson May 18 '17 at 20:33

I think the easiest way to incorporate this type of approach into Docs would be to introduce a way to one-box an answer in there (similar to how chat one-boxes SO posts). That way a decent amount of the answer content will show, if the entire answer is desired it can be clicked through; the score will also show as well as the title and user name.

However, this sort of flies in the face of the idea of Docs. Documentation's goal was not to produce a set of answers or an organized set of answers. They are supposed to be stand alone examples in topics, whatever that means. To be honest, I am not entirely sure what the actual goal of Documentation is supposed to be (if you are not either, this is a good place to start for some background, make sure to follow another dozen links from there down the rabbit hole, I won't call it "light reading"). That said, I am fairly certain I can ascertain certain versions of what it is not, and organizing the current set of Q&A into a different structure of links is not it.

In comments it was pointed out that most users do not use chat. Here is what a one-box of this answer looks like:

enter image description here

  • 8
    Link-only documentation topics. What could possibly go wrong? – BoltClock Mod Apr 26 '17 at 5:01
  • 26
    "I am fairly certain I can ascertain certain versions" - say that five times fast... – Tieson T. Apr 26 '17 at 5:26
  • 2
    Certainly a lot less than in the current form, @BoltClock. The worst that can happen is a link goes dead. That's nowhere near as bad as providing wrong information. – Cody Gray Mod Apr 26 '17 at 6:10
  • 1
    What does "one-box" mean? I have never used chat, so I don't know. Does "one-box" mean "make a link"? – anatolyg Apr 26 '17 at 15:19
  • @anatolyg - See edit please, added screenshot of a one-box. – Travis J Apr 26 '17 at 18:01
  • 1
    I believe after saying "versions of what it is not", the next sentence ending would be "structure of links is it [what it's not]" /smartassery ;) – Félix Adriyel Gagnon-Grenier Apr 26 '17 at 21:35
  • 1
    To be honest, I am not entirely sure what the actual goal of Documentation is supposed to be I don't think a lot of people were. Documentation was so vague - if you can't explain it in a few sentences, it's probably not a good idea. – Qix - MONICA WAS MISTREATED Apr 26 '17 at 23:49

I like the sentiment behind this, but to me it seems redundant: Want an easily searchable collection of archived Q&A material, curated by the community, with search results biased towards high quality content? We have that already: Stack Overflow. Possibly combined with your web search engine of choice if you'd like, all this info is already at your fingertips.

The problem I personally had (and still have) with Documentation is it's really just redundant to what already exists on the internet. And while your idea definitely comes from a good place, it's essentially sort of a recursive SO, and more redundancy for Documentation, which already suffers enough.

So it seems like, if you're going to put SO content in Documentation, it would make more sense to just cut out the middle man, ignore Documentation, and continue using SO, which is already quite effective.

  • 3
    yes, SO is easily searchable, but it's not easily browsable for learning a technology like documentation provides. JefferyBosboom did note, tags sorted by votes actually works surprisingly well for this, although it's very hidden and likely not used by anybody trying to learn a technology. – Goose Apr 26 '17 at 18:44
  • @Goose That is true, it does lack a linear sort of structure. It has more of a wikipedia-like graph structure, where you can keep digging into e.g. related links on the side (don't forget about those on your journeys, btw). Still effective, but not the type of browsing you're describing, of course. – Jason C Apr 26 '17 at 18:44
  • 2
    Given Shog's recent post about the ossification of Q&A, I think Documentation may as well be a "recursive SO"; that's basically why it exists (even if Docs claims otherwise). Part of Wikipedia's browseability is due to human-curated infoboxes (near the top of a page) and navigation templates (near the bottom of a page) organizing a set of related articles. The 'related' links are a far cry from that; sometimes there's something good linked there, but often I find nothing useful after opening all of them. – Jeffrey Bosboom Apr 26 '17 at 20:00
  • 3
    @Goose Docs doesn't solve that problem any better than SO does though. If you want a good step by step guide of how to get into a topic, you get a book or find a tutorial, etc. That's already a solved problem too, and solve much, much better than Docs, (with or without this change) would do so. – Servy Apr 26 '17 at 20:18

I like the concept for the reason that it would give structure to Documentation, making it easier to browse and search. This hasn't been the direction the team has taken, though, so as you say, it would be a radical change.

Here are some reasons I think links to Q&A probably wouldn't work so well:

  • The focus of Documentation is different than Q&A. Documentation (as I understand it) allows topics that would be considered too broad (or sometimes too narrow) for Q&A. Also, requests for examples generally do not go over well in Q&A.
  • People have more freedom to edit the Documentation that they do to edit other users' answers. In Q&A if the accepted answer has outdated code, you generally have to just add a new answer to the bottom of the list. It is frowned upon to make code edits.

What if Documentation was just a documentation style organization to Stack Overflow Q&A content.

Not sure I understand you completely there. This sounds quite vague and I would like to hear more details about how this documentation style organization would look like (like which Q&As are taken, how they are ordered...)?

Among other things, I see the following potential roadblocks:

  • Most questions of the questions Q&A part are not useful (rather low quality) and would only spam this documentation style organization.
  • Spread of information over multiple answers to the same question is normal. How to cope with that? Do you link to questions or to answers?
  • Questions in Q&A often have specific context attached which again could spam this documentation style organization if people are not looking for that context.
  • What problem would it solve? What can you not do with Q&A currently (the search function for example)? Even a documentation style organization should justify itself.

First sorry my english. I am not native and it is hard to me.

A few days ago I thought about this topic. I Think that really, A & Q provides everything you need to gather information on a particular topic. I have time doing it for my learning so. I thougt the sense that was being given to Docs was no longer what is already being Q & A.

However. My thinking is as follows. Orient Docs in the sense of documenting certain information in order to preserve it, verify it, expand it, classify it and share it. This is where I see sense to new features. Call it Docs.

Let me explain. So far the way to work has been to look for concrete questions and concise answers. My proposal consists of several points that I detail below.

Q & A running as before.

The user has a personal documentation section where you can add "books". In order to facilitate the way in which the sections that store those books are detailed. The possibility of indexing, etc.

The sections of the books are individual valuable. But the book forms a valuable set too.

The content of these can come from the user, because he wants to keep certain information redacting.

Or, and here lies the main feature, the user has the possibility to add to his documentation certain questions and answers individually and by choice. By easily attaching, from the question itself for example, by means of a button "add to document" certain information to your document X. So that information is indexed in it and you can edit structure and so on.

For the rankings. I propose that Q & A continue on its way. And for the documentation I propose the following.

A user can go in search of specific documentation, relative to a certain subject. Of course the documentation that each user stores for himself, is shared. So that another user can investigate between documents and take what interests him. Here, this user can decide if he wants to for example download a document in PDF. Or what is more interesting. The user can "document in their own documentation" from the files of another user. In the same way we did from Q & A.

Now, how is this documentation valued? By votes that can be given either directly by pointing to X document. Or giving the user the ability to open a comment requesting specific documentation. All approved "answer" here giving value to the document proposed instead the answer itself There may arise that users who are working on a particular document want to open it to editing to share not only the content but also the possibility of adding to this content by one or more users.

When a user has a document he can choose to propose as a public document of a specific topic. Users can vote on that proposal and generate a relative ranking. Without forgetting that here if we can be sure that for example several documents have the same information from Q & A so you can even get a% equality between documents.

And take advantage of this feature so that you can create versions and propose in return. As if it were a version system. Imagine that a user sees 2 documents that he would like to have in 1 he can create a third party and propose to commit both. It would then have to be seen how to carry out this echo whether or not it should be a substitute.

Small details:

Possibility of valuation of both the document and the sections that it contains individually.

The sections generated from Q & A add a description by indexing it in our document that can then be entered as an introduction to the section. Sections can be proposed to remove from public docs or to be replaced.

Documents that reach certain reliability and volume become public documents and are subject to a version management system as if it were a project but the assessment or acceptance is given by the users.


I have a passion for web development. I recently changed environment and I owe most of my learning to this site. I have started from 0 in many aspects and imagine that I would have been able to add, remove, save, put, certain information of everything I have read to a single document and reference the author. Having: How to A in X, How to B in X.. in public document called "Adapting to the environment X". The information that was usefull to me. Without forget all that sections are part of Q&A so anybody looking for it could be referenced to the full document and upside down.

Then I can propose to do it official. Is it Duplicated? Then proposed to merge the undefined content or partials that people vote. Those could be added as less relevant, grey color,
smaller... related links.. of the official document. And also could be proposed in a list as Q&A is doing then people could vote to directly add, still stay (less relevant), or directly remove after an amount of downvotes.

In the other hand I can always save it for me and anybody who search for it as non-oficial.

Someone can take that because it has served him and decides to add "Adding Y to the X environment". It turns out that we have two documents and we know that the second document is in% equal to the first, since it is a section of it. They are linked in some way more than a tag. They have same context too. And they content references to Q&A where question "lives" and his author.

Now a user wants to pass my same step. Look for a document and find mine. He already have information on how to adapt and also knows about the possibility for adding Y after. All what he is gonna read there is interesting for the purpose

Another user wants to add Y because he already works the X environment. Find a book with 2 sections. The first document might be just as useful.

My bet goes for Stackoverflow official books of documentation

  • 1
    Are you quoting yourself? If you're quoting someone else, you should give proper attribution. And if you're quoting yourself, well, that's silly. You shouldn't use the blockquote formatting. – Cody Gray Mod Apr 28 '17 at 11:34
  • Im quoting myself. Im that mad, yes. :D Was with intention because first I proposed anyone to edit this message with other quotes if he wants. having the original part to be edited by me to see what proposals could be made. It was not a quote in the meaning of a quote, call me rare. I had not another way. – Sam Apr 28 '17 at 12:29
  • I have need to remove quote 1 line by 1 since format button was not working for remove. It was lazy too but I understand what you said. Appreciated. In the original message I was talking why it was a quote but I have not remove it after. I feel it was not important. – Sam Apr 28 '17 at 12:39

There are a few problems that I have found with some answers on Stack Overflow. (Many answers do not have these problems.)

Answers have typos which cause incorrect assumptions

Answers are flat out wrong or can cause major problems. (For example, some people will suggest giving global read/write/delete privileges when what is actually needed is a a change of ownership of some files.)

Answers may have been appropriate for some past versions, but the language features have either been deprecated or removed.

Suggested solution may work on one platform but not another. For example, one piece of software would work on Windows but not Unix. The Javadoc stated that certain methods couldn't be used safely except between the time of opening and closing the connection. The Windows API that was called was different from the low level calls on the UNIX system. The result was that the code failed on UNIX. There also may be features of their solution that can cause strange behavior when run in slightly different circumstance.

Before I actually use a solution from Stack Overflow, I duplicate the problem and solution on my home system. I will often provide links back to the Stack Overflow article after vetting it. By the way, even if the suggestion doesn't work, it will often give me the hint that I need to find the real solution.

Many frameworks and applications are horribly under documented. We need people to document more seriously and to cooperate with those who are willing to document. There are actually open source documents on many areas, such as Maven. Perhaps we need an open source document on documenting. (I'm quite serious.)

One final comment. Don't look for answers on the internet. Look for tools to help you find the answer.

I believe that you misunderstand my comments or I was unclear. I get a lot of information from Stack Overflow. However, I always test the answers before assuming them to be correct. When I refer to tools, facts are tools in finding solutions. Too many people give it up if they can't find it on Google in one minute. When I look at information on Stack Overflow, it may not answer my question, but it may lead me to sources that will answer my questions.

Automatically loading information from Stack Overflow, Google, or other sources into documentation yields unreliable documentation. We need reliable documentation.

  • 1
    Don't look for answers on the internet. Look for tools to help you find the answer. - I would argue that the internet is a tool and not using it is a hindrance. – TheLethalCoder Apr 28 '17 at 11:27
  • 2
    The tool I'm most fond of using is my brain. To aid that, I often go searching for information on the Internet. Hard to understand what the point of this answer is, other than an angry commentary on human fallibility. Have you never before been helped by anything you've read on SO? Of course you should try it for yourself first; that would be true of anything you read anywhere, including something called "Documentation". As for your point about underdocumented frameworks, what's the status of their documentation on SO Docs? Not so good. – Cody Gray Mod Apr 28 '17 at 11:35

Not the answer you're looking for? Browse other questions tagged .