1. 16
  1.  

  2. 7

    I’m curious about people’s opinions on this. I’m cautiously optimistic that this will improve documentation for commonly-used software. Community-contributed docs can be great - I had to use PHP once, and their documentation’s comments section was often useful. A focus on examples and allowing requests is also welcome, as I’ve often hit things in e.g. the Python docs where there aren’t good examples or the ones given aren’t what you actually want to do.

    On the other hand, will this remove what little motivation there already is to write docs for a project? What kind of issues crop up when some other company effectively owns your docs?

    1. 16

      I’m not super excited about this, honestly.

      Things I like:

      • channeling the excess cycles of lots of developers to write documentation
      • using the SO badge and exp. system to con the people susceptible to such measures
      • the chance to finally get better docs on certain things

      Things I dislike:

      • perpetuation of SO ranking as some kind of developer merit badge
      • perpetuation of SO as the repository of information that should damn well be bundled with the software
      • perpetuation of developers giving away their free cycles to help companies who then profit from them
      • putting important docs into a platform whose moderation is whimsical
      • encouraging people to write docs that, frankly, likely shouldn’t be writing docs
      • duplicating or ignoring the excellent documentation that some communities already have

      We really need to think, as an industry, about just how far we want to lower the barrier to entry and just how much we want to sharecrop other people’s gardens.

      I mean nobody will actually do any of that thinking and this’ll be a huge success for Spolsky and Atwood, but fuck if I won’t at least say something about it. :|

      1. 4

        It’s not that I disagree, but SO docs can only succeed in a world where “proper” docs have failed. Projects that don’t like it can endeavor to make their own docs better. Unfortunately, my experience suggests that project leads often have very peculiar ideas about constitutes the best documentation.

      2. 5

        I think it will be great for “cookbook” style documentation in the style of “The Perl Cookbook,” but I’m not sure how well it will work for more in depth documentation or really understanding a topic. I don’t think it will work very well as a reference.

        For example, the Common Lisp “format” section, gives a couple very basic examples, and doesn’t even list (or link to) all of the format string characters and options. I suspect most people looking for documentation on format already understand what it does at that level, but need specific format strings to align, pad, or whatever.

        Some of the C++ sections seemed to take a more cookbook approach and were a lot better.

        It would help a lot to have links to reference documentation somewhere on each page, if it’s available.

        It seems inevitable that the languages with the most documentation generally available will have the most and highest documentation available on stackoverflow.

        1. 4

          I’m just hoping this will get some better ASP.NET and C# docs out there. The MSDN docs are awful. :(

          On the other hand, I think one of the best documentation sites I’ve ever seen are Mozilla Developer Network’s. We’ll see how SO Docs turn out.

        2. 6

          I will not be contributing to this.

          I have a combined rep of 19k on the whole StackExchange network, and 5k on the main StackOverflow site specifically. Lurkers may not have experienced it yet, but StackExchange has pulled my own words from under my feet one too many times, and I’m sure I’m not alone.

          Any question, answer or comment you submit to StackOverflow / StackExchange can be deleted without a public trace, and these deleted items you’ve spent time on researching and writing up stop being visible even when you are logged in and are not even a new user.

          I’m listed as “top 3% this year”, yet I still can’t see my own comments, answers or questions that have been deleted, supposedly because I still don’t have enough reputation yet, even being the top 3% is apparently not enough.

          If your post is well-written, but turns out off-topic, it can be deleted on a whim should you rub some moderator the wrong way. If they lunch a new site next month where the old post won’t be offtopic anymore, you’d have to write it up all over again, because the prior one is now gone from your account (even though they still store it on their servers, so, the top 0.0001% or whatnot can still read it).

          They have a whole bunch of mostly arbitrary reputation-based rules at varying levels of reputation of how their site works, which are not even documented well (here’s an idea, why don’t they document their own shit first?), and open-source projects should not be relying on this dubious platform for their documentation (just as we should not rely on Slack, either).

          Git is where it’s at.

          1. 2

            Regarding your last point, how does git solve this? Maybe whoever hosts your git repo won’t delete your answer entirely, but they can sure make the pretty markdown rendering hard to find. If editors exist, they’re going to edit.

            1. 2

              With git, I can be sure I have my own copy of the history, plus history rarely gets rewritten with git with public projects, so, I can always go back and find the other half of my memory, and it won’t be ripped out.

              With StackOverflow, any one of your questions, answers or comments can be deleted at any time, without any advanced notice, and without any recourse. They wipe the other half of your memory (explicitly denying you access to your own thoughts and such), and often without even having any decency to tell you about the fact.