58

I've been trying to keep the PHP list of Topics clean. A common issue I'm seeing (and removing) are Topics that are just too localized (i.e. tutorials on how to perform some highly specific task), but there's another trend I'm seeing: new topics made that should be examples or belong in a different tag. That last one (assuming it should exist at all) really belongs under PHPUnit tag, but there is a Unit Testing Topic as well. That last user also created a second Topic that should have been part of the first Topic. I can't blame him too much. The interface didn't try to stop him or offer guidance.

PHP has over 100 Topics (Android has 233 as of right now). Is there anything that can be done to discourage users from making new Topics? Or can we shunt people to either creating Examples or a different Tag? Something like how asking a question tries to match it up to an existing question.

7
  • 19
    I'm seeing the same thing in PL/SQL. There's just a rambling, unstructured collection of poorly written examples and questionable opinions, like any random selection of blog posts you'd get from a Google search. Plus there is no reference to language versions despite these affecting syntax. Frankly I can't see the point of it. It's all documented already. Commented Apr 15, 2017 at 11:49
  • 43
    I think that we should make a canonical post for "Documentation is a pile of garbage", possibly with a top answer "don't waste time on it and let the dumpster fire burn, sooner or later they'll just shut the whole thing down"; then all these questions will have a nice dupe to link to. Commented Apr 16, 2017 at 0:10
  • 3
    @MatteoItalia Good idea, but write it following Be Nice.
    – Nic
    Commented Apr 16, 2017 at 0:30
  • @Machavity Well this platform is built on the very ability to use reputation to discourage prolonged unintended behavior. The system sort of weeds out the bad eggs over time due to their very reputation, this is the driving force of SO and honestly, it is one of the reason I come here for answers on a consistent basis. Heck I visited this site for years before I ever even created an account and became a member. With prolonged use, I began to seek out the KB articles and help FAQs to make sure I am on target when asking and posting on SO. Commented Apr 17, 2017 at 1:33
  • 20
    Let's burn all the documentation rep too, while we're at it. Commented Apr 17, 2017 at 1:34
  • @dalelandry, I don't see rep discouraging unintended behavior at all. The site is full of old and new off topic questions (people asking for library recommendations for example). 1000s of those questions come in everyday, they may or may not get closed but more often than not they get a useful comment or an answer before they are closed. That means the bad user got what they wanted and the site is how polluted with Q&A showing that it doesn't matter what the rules are, the odds are high you'll still get an answer or at least a comment in the right direction to your off topic question.
    – user128511
    Commented Apr 17, 2017 at 6:37
  • 2
    I half-expect this post to be closed as "by design."
    – BJ Myers
    Commented Apr 17, 2017 at 16:50

3 Answers 3

127

Personally, I would just stop caring.

Documentation, in my opinion and in the opinion of many others, is a failed experiment. There are many specific grievances about it that can be found in the previous posts about it (see in particular @Nicol Bolas and @Peter Cordes answers); but the main underlying point is exactly what you expressed in your question:

There's no clear guidance about what Documentation should be and how it should be organized

This isn't a thing you can crowdsource; you can't just say "here's is some wiki-paper, do something about documentation for whatever project in the world you can think of; something with examples, I don't know, whatever, figure it out".

Addendum: Actually, as @Frank correctly noted in the comments, it's way worse than this, because not only the general direction is completely confused, but the provided software platform has some "hard" structure, which however is not clear at all how is supposed to be used effectively; so, while a free-form wiki has some hope to succeed if the community manages to self-organize around some emerging format, forcing the content in an opinionated hard canvas that is not adequately thought out is probably the perfect recipe for a disaster.

Stack Overflow succeeded because questions come in "for free", so to say, and there's a very specific, narrow focus on answering them in the best possible way, all while competing with other talented people. It was clear from the beginning what Stack Overflow was (a Q&A for specific, focused questions) and what it wanted to incentivize. This kind of direction helps people (especially the programmer type) to stay focused on the problem, to contribute effectively and to enforce some policies about questions and answers that most of people understand and agree to.

Documentation, on the contrary, is as vague as a project can be. No guidance is given about what kind of documentation is expected to come out of that, so everybody and their mother starts writing stuff hopefully with a certain wider idea in mind, only to find it later either completely altered or in a completely different context, because someone else had a completely different idea about how to organize the topic - possibly valid, but which doesn't fit the previous format.

The lack of a generally shared idea of what this thing should look like makes policing for bad form, bad content and, most importantly, bad organization essentially impossible; on Stack Overflow I have a well-defined idea of what a good question/good answer looks like, and I expect it to be mostly shared with other fellow Stack Overflow-ers. On Documentation everything goes, so who am I to say that some format is worse than another, and thus to try to fix a bad post into a good one?

The comparison with Wikipedia that I heard often is moot; although anybody can contribute, Wikipedia is a quite bureaucratic project, where high-level decisions about how to organize voices are heavily discussed and widely enforced. Most importantly, they do have an always-present focus about what they are doing - they are writing an encyclopedia composed of single, monographic, interlinked articles, possibly organic. Distributed knowledge about a topic is distilled into a single voice, generally decently organized, which is what makes it so easy to consult, both to get a quick insight over a given topic and to locate painlessly the information you need.

This is exactly the opposite of Documentation, where you have a multitude of non-organic, non-coordinated sub-topics that for some reasons are voted one against another, as if they were to compete although they are often talking about different aspects of the same topic - sorting by their score is literally comparing apples to oranges.

The end result is that currently Documentation is a burning pile of garbage that eats men-hours from well-intentioned but undirectioned volunteers. I'm sorry for any person who wasted his/her time on this project, but I still have to find a topic that I would suggest to a friend or a coworker to use as a learning aid. A single subtopic may be well written, but the global result is generally completely unusable for any learning endeavor that I can think of.


My proposal for those who feel frustrated about it is simple:

Don't waste your time trying to fix it; just let it die

The complete lack of direction is the only well defined aspect of this project. It has been expressed many times and wasn't and cannot be fixed. Way too much manpower has been wasted on this clusterfuck trying to salvage it.

Sooner or later they'll shut it down and we'll all have learned a lesson about wasting collective manpower in well-intentioned, but completely ill-defined, projects.

12
  • 2
    I would think something closer to the MDN would work better than Documentation - anyone can contribute a pull-request for a topic/sub-topic/whatever, but only some users with sufficient can approve the pull requests (in our SO model, that would users with sufficient reputation).
    – Tieson T.
    Commented Apr 17, 2017 at 1:47
  • 3
    I wonder if removing all rep from docs would help? There's no rep on wikipedia (or if there is i've never seen it). That would at least change the motivations in which I suspect many people contribute to docs solely to get some rep they can put on their CV. A single article on Wikipedia might have been edited by 100s of people and except for hidden in the edit history there's nothing on the page about who contributed to it. Of course Wikipedia editing is still highly political and I wouldn't expect docs to be any different so burninating it might be best.
    – user128511
    Commented Apr 17, 2017 at 6:33
  • 15
    Awesome overview of an expensive failed experiment
    – charlietfl
    Commented Apr 17, 2017 at 16:22
  • 10
    Re 'you can't just say "here's is some wiki-paper, do something about documentation for whatever project in the world you can think of; something with examples, I don't know, whatever, figure it out".' I actually think it had a shot as such ... if the structure was as free-form and internal link-friendly as a wiki; and if there were good mini-metas per tag to have discussions on. For me, it's too late for that; I took what I'd contributed and rehashed it in a link-heavy tutorial. So I agree with your recommendation re walking away.
    – Frank
    Commented Apr 17, 2017 at 18:47
  • Total tangent, but: what does "fruible" mean? I can come up with possible meanings based on guessing the base and its use in the sentence, but I don't think I've ever seen that before.
    – DSM
    Commented Apr 17, 2017 at 19:12
  • 4
    @Frank: that's a great observation that I didn't make evident enough; not only the general idea is confused, but the platform is opinionated - in some confused and definitely not-well-thought way, which makes it difficult for user to use it as a generic wiki to shape in whatever form they feel best. I'll add this in some way to the answer, because it's an important point. Commented Apr 17, 2017 at 19:21
  • @DSM: that's what I get when I'm writing a post in English while I'm replying in Italian to an email :-). "Fruible" is a totally made up word over Italian "fruibile", which means something like "easily employed for some aim"; there I meant that Wikipedia articles generally aim to be organized in a coherent enough form that makes it easy and painless to both get a quick insight over a topic and locate and fetch the information you need. Commented Apr 17, 2017 at 19:26
  • 5
    @MatteoItalia: TIL! Which is more than I've gotten from Docs. ;-)
    – DSM
    Commented Apr 17, 2017 at 19:28
  • 5
    @gman: "I wonder if removing all rep from docs would help?" Not really. The problems with Docs.SO are too deep for that. Oh sure, there wouldn't be an incentive to post crap or copy&paste from other sources. But removing rep would change nothing about the other flaws and contradictions inherent in the system. Like I said in the referenced post, Docs.SO is a bad idea, in both concept and implementation. Commented Apr 17, 2017 at 20:31
  • 1
    I think the important part here is to accept that Docs is a failed experiment and a sunk cost. Learn what you can from it and move on. Don't let the psychology of "trying to recover it" drag you down. When you're trying to do something that's never been done before, you may succeed, or you may fail. And there's no shame in failing. SE did the right thing by killing off things like "support for opinion-based questions", and the SO TV thing. Let's see if they do the right thing here.
    – Mysticial
    Commented Apr 19, 2017 at 21:04
  • so everyone listened to this post, and a indeed nobody goes there anymore (except a few newbs trying to see themselves in print). As I point out here .. meta.stackoverflow.com/a/348180/294884 I'm not sure you can even say "failed"
    – Fattie
    Commented Apr 20, 2017 at 14:37
  • THANK YOU FOR THIS!!!!
    – Confused
    Commented Sep 25, 2017 at 5:06
-3

Right after launch I proposed a "paving the cowpaths" approach to Documentation. But since then I've learned that has some significant downsides. In particular, I think we can learn something from the early days of Wikipedia:

Using the simple technology of the wiki allowed Wikipedia’s founders to focus on the encyclopedia’s content — on getting article contributions rather than building technology. Instead of acting as technologists, Jimmy Wales and Larry Sanger could instead act as evangelists, [researcher Benjamin Mako Hill] pointed out, seeding Wikipedia with content they solicited from contributors — which, in turn, led to more content, and more contributors. There are lots of convincing arguments suggesting that peer production projects succeed because of technology; in encyclopedias’ case, though, it seems that technology actually became a distraction. Leaders needed to be able to take their infrastructure for granted so they could focus on the content that would populate it.

Looking at the existing Documentation on populated tags like PHP the topics seem a bit too broad and certainly too few. For instance, someone asked in 2012 for an explanation of register_shutdown_function. There is an example under Exception Handling and Error Reporting, but this feels like a good candidate for an entire topic. That way, there'd be space for more specialized examples:

  • Registering several shutdown functions.
  • Removing a registered function. (Or an explanation of why that can't be done.)
  • Using the facility for non-error related cleanup. (The accepted answer suggested closing open files and saving persistent data.)
  • Demonstrating the optional parameters.
  • Illustrating how die interacts with register_shutdown_function.

And even some of those might make good, specific topics on their own. So I kinda think Flash messages after POST (w/o Frameworks) sounds like a good topic (assuming this is a thing people actually need to do). Speaking of which, a few of the topic requests for PHP seem worth creating. I know it's a pain to keep track of existing topics (and avoid duplication), but that's among the issues we are working on. The way we think of Documentation, every Topic is a potential target for a Google search and people tend to search fairly specific things rather than broad things.

To preempt the usual criticism: Stack Overflow Documentation isn't exactly what people think of when they talk about "documentation". Normal documentation focuses largely on the "what":

  • What does X do?
  • What inputs does it take?
  • What does it output?
  • What errors might it produce?

These are important questions to answer. But they are best answered by the people who maintain the language/framework/library being documented. Stack Overflow Documentation might answer these questions, but that's never going to be the best way for developers who aren't maintainers to contribute. Instead, we intend Stack Overflow Documentation (SOD?) to focus on Examples that answer "how" questions:

  • How do I do Y with X?

or maybe:

  • How do I do Y with X given Z?

These can be pretty specific and probably won't fit into a clean top-down hierarchy. But ultimately community-driven systems work best when they dive into long tail content.


For the PHPUnit topic(s), I have some good news: you can now move topics from one tag to another. It took a surprisingly long time (we first announced it back in November). We are a long way away from having a good topic management toolkit, bit this is one item that clearly was needed.


There's also the problem of guiding users to create good topics within the software itself. The "Request Topic" button does try to find existing topics:

There's already a Unit Testing topic

But we don't give a lot of advice about what makes for a good topic scope:

Initial topic draft

I think we can do better.

15
  • 5
    'we intend Stack Overflow Documentation (SOD?) to focus on Examples that answer "how" questions' - there are multiple problems I want to point out with this approach, and I've pointed some out before, but mostly I just want to shout BUT YOU ALREADY BUILT AN ENTIRE PLATFORM THAT SOLVES THIS PROBLEM AND SOLVES IT REALLY WELL! Why are you trying to build a new product that directly competes with your core offering's single greatest strength, and what makes you think that you'll manage to do it better?
    – Mark Amery
    Commented Apr 18, 2017 at 22:56
  • 1
    @MarkAmery: Might I ask you to ask a question along the lines of What does register_shutdown_function do? It lasted less than a day before closure in 2012. How long do you think it would last in 2017?
    – Jon Ericson Staff
    Commented Apr 18, 2017 at 22:59
  • 1
    @MarkAmery: Or, since it just came up on meta, maybe ask how to use Ruby to create a storage profile in Azure VM. My point is the community is (understandably) hostile to questions that look like documentation requests. Stack Overflow Q&A is pretty great for examples iff there's someone willing and able to ask the right question.
    – Jon Ericson Staff
    Commented Apr 18, 2017 at 23:12
  • Interesting. I partly take the point. On the one hand, the register_shutdown_function question is not a "how" question in any sense that I understand, (and nor are most of the individual examples that you propose most naturally understood as the answers to "how" questions), but I actually do agree that the Documentation platform could be effective at documenting register_shutdown_function's behaviour if register_shutdown_function got an entire topic. That seems to imply a drastic narrowing in the community's current conception of a 'topic' is needed, though.
    – Mark Amery
    Commented Apr 18, 2017 at 23:16
  • 1
    Fleshing out this idea a little: your vision seems to be to have examples that are roughly the same in scope as answers, but topics that are like slightly "Too Broad" questions. A topic wants to be "what would I use the frobnicate feature for?" when there are like 6 or 7 major use cases for the frobnicate feature, or "what does this function do?" when the function is (like register_shutdown_function) one whose full functionality can be expressed by half a dozen examples. Too much ground for a single answer to cover but little enough that 6 can do it.
    – Mark Amery
    Commented Apr 18, 2017 at 23:27
  • 1
    (The problem you currently face, of course, is that most currently existing topics, including the most "popular" ones according to the "popular" tab, are massively too broad even under this vision, and without communicating the vision clearly there's little chance that this will change.)
    – Mark Amery
    Commented Apr 18, 2017 at 23:31
  • 3
    "That way, there'd be space for more specialized examples:" A question arises: what does it mean for an example "Demonstrating the optional parameters" to be voted higher than one "Registering several shutdown functions"? Are optional parameters really more important that multiple shutdown functions? Or is it merely what people voted on? Competition among examples doesn't make sense within this vision, because each example is showing off an independent part of the whole. In Q&A, a single answer can be complete. This is not true of this Examples.SO vision. Commented Apr 19, 2017 at 2:17
  • 6
    "Stack Overflow Documentation isn't exactly what people think of when they talk about "documentation"." Then why are you using words that you know will be misinterpreted? If Docs.SO will not provide something recognizable as "documentation", why do you use that word? You are not going to change the definition of "documentation". Name things based on how people will understand them, not based on what you want people to think of them as. Commented Apr 19, 2017 at 2:22
  • 1
    @NicolBolas: Yeah, score-order sorting on examples is strange. I've never been comfortable with it and the "pin one example" solution is only somewhat workable. (And that only when there's an obvious example to go first.) On the flip side, we do have a section (at the bottom) for optional parameters. We added the introduction section a few months ago and we could certainly add more sections if needed. And there's room for people to organize topics in a way that voting on examples could be reasonable. But my money is that we'll have a different sort system by the time we leave beta.
    – Jon Ericson Staff
    Commented Apr 19, 2017 at 2:35
  • 1
    @NicolBolas: I think it's fair to say Stack Overflow changed the definition of Q&A. Stack Overflow was radically different than all the ways programmers got their questions answered in the past. (And the credit goes in part to Jeff, Joel, and the early developers and in part to the community of developers who made the crazy system work.) I think documentation is due for a revolution. If we don't change the definition, I'd be willing to bet someone else will.
    – Jon Ericson Staff
    Commented Apr 19, 2017 at 2:41
  • 6
    @JonEricson: "I think it's fair to say Stack Overflow changed the definition of Q&A." How, exactly? What we call "questions" are still recognizable as questions to people not used to the SO platform. The same goes for "answers". If you tell people SO is a Q&A site, and then you show them SO, they get how it works quickly (I know I did). SO didn't redefine anything; it merely presented the concept more effectively. By contrast, a bunch of examples is not merely presenting the concept of "documentation" more effectively; it's presenting something people don't think of as documentation. Commented Apr 19, 2017 at 3:01
  • 1
    @NicolBolas: By removing a bunch of stuff that turned out not to matter (threading, for instance), adding a bunch of obvious-in-retrospect features (like tagging), and introducing clearly insane ideas that destroy the fabric of the endeavour (reputation, mostly) but somehow works out ok in the end. In contrast, Usenet, forums, Experts Exchange and the rest were dinosaurs. In the end, the killer feature was something that old types of Q&A could never provide: searchability. My biggest concern with Docs (by a country mile) is that it's not very discoverable.
    – Jon Ericson Staff
    Commented Apr 19, 2017 at 3:16
  • 6
    @JonEricson: You're misunderstanding my point. If you say "documentation site" and show someone Docs.SO, they wouldn't agree that it's a documentation site. If you went back in time 20 years and said "Q&A site" and then showed them SO, even though they've never seen anything like it before, they would agree with you when you called it a "question and answer site". That's the difference: Q&A.SO fulfills the expectation of the term it's attached to. Docs.SO does not. Commented Apr 19, 2017 at 3:40
  • No, I think I just disagree with you. (20 years before SO was in beta, websites hadn't been invented yet. But let's pretend you meant 5 or something.) Honestly, I thought the whole project would fail because it lacked proper threading. Seriously.
    – Jon Ericson Staff
    Commented Apr 19, 2017 at 3:51
  • Reading that quote makes me wonder why you built all this tooling for SO Docs instead of just using, or modifying, a wiki, and focusing on getting it populated with useful information. Commented Apr 19, 2017 at 6:38
-11

This is not the answer you are looking for, but I am in favor of seeing many more topics in documentation than currently exist. I can't speak to the content or quality of the PHP tag, but I can definitely say that 233 topics is not enough for Android. I quite often search the official documentation only to find topics that were "just too localized" for the Android team to write any useful description or examples. I would be very happy to see these things documented in Stack Overflow.

Voting to sort the examples has more meaning if the examples are all on a similar topic. If we force the topics to be broad generalized categories, then the examples tend to become subtopics unto themselves and voting has no meaning as far as the sort order goes.

That said I would like to commend you for sticking with SO Documentation to try to make it a better place. I haven't done the same, but if some of the issues related to the topics and organization get resolved, I would like to contribute again in the future. I hope Documentation can be successful because it is needed. I need it, anyway.

2
  • 17
    1 single good topic anywhere, beats 233, 2330, 233^233... crappy topics any time.
    – Braiam
    Commented Apr 16, 2017 at 2:16
  • 5
    "I would be very happy to see these things documented in Stack Overflow.". The fact that, a year into the experiment, these things are not, documented should tell you a lot.
    – user3458
    Commented Apr 18, 2017 at 0:07

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