2914
votes

It’s been 7 years and 10,000,000+ Questions since Stack Overflow was launched. The amount of good that has been done for the field - all the developers helped, all the person-hours saved, all the beginners who grew into professionals - is hard to overstate. I cannot express how proud I am of what we’ve built together (and not just because it let me see our arch-enemy vanish from my Google results); this community has realized the goal of "making the internet a better place" beyond what anyone could have predicted.

Lately we've been asking ourselves "what else could we do to improve developers' lives on the internet?". Jeff’s original announcement of Stack Overflow said this:

There's far too much great programming information trapped in forums, buried in online help, or hidden away in books that nobody buys any more. We'd like to unlock all that. Let's create something that makes it easy to participate, and put it online in a form that is trivially easy to find.

Stack Overflow has made all of that a lot better, but there's one area that is still hanging around: Documentation. Just like Q&A in 2008, Documentation in 2015 is something every developer needs regularly, and something that by most appearances stopped improving in 1996. We think, together, we can make it a lot better.

How would adding Documentation to Stack Overflow improve Documentation?

  1. Documentation is often an afterthought, obviously done just to say that it exists, with little concern for its quality. We've all seen plenty of this in our time. Bad documentation is bad We can bring a focus on quality, peer review, and "actually solves real problems for real developers"-ness to documentation that would be very welcome.

  2. Often documentation is lacking in examples, or the examples are trivial and don't demonstrate typical use. Because Stack Overflow benefits from constant feedback from developers writing real-world code, we could greatly improve the quantity and quality of examples. Let's be honest: finding examples is already a common use-case for Stack Overflow; we might as well embrace it.

  3. Much of the documentation out there is tied to release cycles, and thus infrequently updated and rarely "complete". The community-contributed and edited nature of Stack Overflow would be an immediate improvement.

  4. A lot of documentation descends from Javadocs, and while it was better than nothing in '96, it's hard to call framesets with unshareable URLs "good" in 2015. We can focus on creating the best UX for creating and serving documentation on the modern web.

What would adding Documentation to Stack Overflow improve about Stack Overflow?

  1. We've heard repeated requests for a place for broader artifacts to live. Less "a specific problem you are having right now," and more, "what is there for me to use." We think Documentation could provide a place for many of the useful artifacts that developers actively need, but we've been turning away over the years.

  2. Many posts are improved by citing official documentation, but today, that means using offsite links that are sometimes hard to find and that may break. Having it on-site makes it easier to find and incorporate Documentation into posts.

  3. There are Questions that come up repeatedly whose root cause is poor documentation. If you see a bunch of people struggle with Foo's Bar class, with Foo's documentation on Stack Overflow you could fix the Bar page and mitigate a source of repetitious (often exact duplicate) Questions.

  4. A smaller, but just as real, benefit is that it opens up more opportunities for giving back. Oftentimes we'll hear from a developer who has benefited from a Stack Overflow Answer, but has trouble finding a Question they can help with that isn’t already answered. Documentation adds many more opportunities for paying it forward.

The Plan: We need YOUR help to build this

The first step is to share some rough ideas we've been kicking around for what the Documentation "part" of Stack Overflow might look like and how it might behave, and get your feedback. This is still in an early stage, but most of the successful ideas in Stack Overflow originated from the community, so we want you all in the loop as early as possible.

The second step will be a private beta, where we break everything and make the team cry test out the tools and workflows, but not on Stack Overflow proper. There's a sign-up form for this further down, so keep reading. Private beta will be shipping in the traditional six-to-eight weeks.

Then a miracle occurs

Or we're wrong. Maybe Documentation isn't as exciting to the community at large as it is to us, or we fail to iterate to a solution. Maybe we can't fill in that step.

Failure is always an option

But we think it's worth having a go at it. Interested? Give this post an upvote, and sign-up for the beta. Hate it? Downvote. Questions or comments? Well we've got more info below, but do post any and all feedback you have at the end - we want to hear your thoughts. After all, Stack Overflow is you.

How Documentation Will Work*

* we think

Tags that already have involved communities on Stack Overflow, such as or , can have associated documentation created for them. Documentation is broken up into pages called Topics.

Topic page

Topics always have Examples and Remarks; other sections are optional.

Examples are collapsible and deeplink-able. We're putting them at the top of the page because we believe they're the most important - the information you desire is likely within them. We're expecting Topics to have more Examples than Questions have Answers, since Topics will be broader than Questions.

Because Topics are envisioned as being much larger than the typical Question or Answer, trying to compose them in our current editor would be painful. So we're building a new one.

The new editor

You can edit individual sections or Examples, you'll see a live preview, and your changes are automatically saved as drafts. We're still using Markdown and prettify for formatting and code styling, of course.

Anyone with sufficient privileges in a tag can create or edit Topics, and those without those privileges can suggest changes for review à la suggested edits. Those who think a Topic is needed, but cannot themselves write it, can instead request a Topic using the creatively named Request Topic button.

Searching for an existing request

Requesters first search for an existing request to upvote, and if they find none, they can then enter a new request.

Submiting a Topic Request

We're anticipating the typical good Request will be smaller than the typical good Question. A good Question has some explanation of the issue, a reproduction in code, and lists things that the asker has already tried. A good Request only has to explain the deficit in the Documentation. Because of this difference, we’re going with a much lighter UI in comparison to the Ask page.

For giving feedback on existing Topics, voting and flagging are available. These look very similar to existing flows, so they're not pictured.

All actionable items (request, pending changes, flags, votes, etc.) are aggregated into a dashboard view for people looking to help out.

Dashboard mockup

Each "view more" and tab go to full lists like in the user profile.

All this stuff is very early and very much subject to change; especially now that we'll be getting your feedback.

FAQ

  1. How will reputation work?

    • You'll get reputation for peer-reviewed contributions to Documentation. Peer review may take the form of citations, suggested edit reviews, explicit voting, or a combination of all three. Reputation you earn from Documentation will be added to the existing Q&A reputation; there won't be two separate numbers. Obviously, we're still working out lots of the details.

    • We intend for participation in the Documentation parts of Stack Overflow to be about as rewarding, in terms of reputation, as asking and answering is in the Q&A parts.

  2. What can be documented?

    • We're thinking "anything you use through code" as a really rough guideline, but we'll ultimately decide together as a community, just like with what’s on-topic for Q&A.

    • For the betas, we're planning to restrict ourselves to established and widely used projects. We're trying to test out the bigger stuff first, to make sure all the tools and processes can cope. If all goes well, eventually just about anything that sees some Q&A activity will be fair game to document.

  3. What should be documented?

    • Anything where we can actually make it better. If a project already has awesome documentation that's easy to search and cite, then there's no need to duplicate it on Stack Overflow. We're interested in fixing what's broken with documentation, not just moving them onto Stack Overflow.
  4. What's the line between a Question and a request for a Topic?

    • Topics are broader in scope than Questions. In fact, we're expecting that if you "asked" most requests, they’d be closed as Too Broad.

    • Topics should also have multiple Examples, so a request that can be served by a Topic with a single Example (ie. one block of code) is probably too narrow.

  5. Is importing existing documentation encouraged?

    • No. We're hoping we can improve documentation, not just move it under the stackoverflow.com domain.
  6. What license will documentation be under?

## Register For The Beta

We’ll need to know three things:

  • Your email
  • Your Stack Overflow profile URL
  • A list of 2-5 tags you’d be interested in helping document

Please pick tags from the first two pages of popular tags that have an especially active community. Things like , , or so we can test our system out against the real things that lots of developers are using in the private beta.

Register and help Make Docs Suck Less

198
  • 155
    4 minutes - 15 upvotes? Who can read such a long post so fast? Commented Aug 31, 2015 at 15:34
  • 253
    "We’re interested in fixing what’s broken with documentation, not just moving them onto Stack Overflow." - Assuming this works how you want, if a project improves documentation to the point where it's not needed on SO any longer, will there be a process to encourage users to go back to the project itself instead of continuing here?
    – Andy Mod
    Commented Aug 31, 2015 at 15:39
  • 164
    I wonder how, in the case of something like .NET, this would be better than MSDN. Maintenance would be another concern generally. Things change. Commented Aug 31, 2015 at 15:41
  • 32
    @Andy in the same way that a community could stop posting to Stack Overflow Q&A, yes. Ultimately the contributors control the content, if they're convinced to tear everything down and point folks at the official docs then that's fine. If it turns out we need to build tools for such a process, we will. Commented Aug 31, 2015 at 15:43
  • 36
    @Plutonix read #3 on the FAQ again. They don't want to replace existing documentation if the existing docs are good enough. However, I'm wondering how we could somehow supplement existing documentation with better examples, because some of the examples and information on MSDN (and plenty of other OSS documentation) sucks.
    – Dave Zych
    Commented Aug 31, 2015 at 15:44
  • 34
    Along the same lines as the concern indicated by @Andy, would there be some process to discourage people from creating 'usurping' documentation sets that have the effect of making other documentation worse (or, more likely, die on the vine)? The first thing that came to mind is asp.net-5 - docs.asp.net is really incomplete, but it's collaborative and could be made quite good with enough contributions. What happens when all those potential contributors do it here instead? (comment a little out-of-sync with your response to Andy..) Commented Aug 31, 2015 at 15:44
  • 22
    @Plutonix we have some ideas about handling version releases (tl;dr version tables and inference), as well as obsolescence (tl;dr flagging and markdown extensions). This post was pretty long already though, so I cut it. We'll have some super detailed stuff when the beta starts, you're correct that this stuff is tricky. Commented Aug 31, 2015 at 15:46
  • 27
    WRT point #5, if the tag wikis are the recipients of plagiarized content now, I can't wait to see how the documentation pages end up. I definitely like the idea though.
    – j08691
    Commented Aug 31, 2015 at 15:54
  • 19
    Love the idea, but worried about visibility if this is confined to tag wikis or a similar corner on SO with relatively low "through traffic". Would this perhaps warrant a separate docs.stackoverflow.com portal? With a Google-like search field, a tag selector, and specific information around docs? With users signing up separately, as they would to a different SE site?
    – Pekka
    Commented Aug 31, 2015 at 15:56
  • 180
    Maybe we could take this opportunity to improve licensing: explicitly dual-license code samples in docs as MIT, not just Creative Commons, so they're clearly safe to reuse.
    – Jeremy Banks Mod
    Commented Aug 31, 2015 at 15:57
  • 82
    How would the project deal with the danger of documentational ghost towns? Say a bunch of people wants to create SO docs for something that already has decent documentation of its own. They may want to mine rep, or genuinely feel they can contribute something great but aren't allowed to in the project's own docs. Because the larger community isn't with them, the effort withers away quickly and leaves a half-finished pile of partially useful information. How to prevent that?
    – Pekka
    Commented Aug 31, 2015 at 16:15
  • 65
    One of the most difficult things to enforce to maintain utility will be versioning. Here I refer to the version of the thing being documented. There is already much in the questions section that doesn't have good versioning and most of the time it works. How to inject discipline into the documentation consistently? Commented Aug 31, 2015 at 16:27
  • 45
    First, I'd like to recommend that the design lend itself to printing. I still print out documentation and write all over it, so make sure there's some thought put into the printer style sheets. Second, you said "Topics always have Examples and Remarks; other sections are optional. Examples are collapsible and deeplink-able. We’re putting them at the top of the page because we believe they’re the most important ". I think this is wrong, and parameters and syntax should be required while remarks should be optional. And since syntax will usually be shorter than the examples, it should be 1st.
    – j08691
    Commented Aug 31, 2015 at 16:35
  • 23
    I like the idea, but it shouldn't be part of Stack Overflow. It should be a seperate thing.
    – Jeroen
    Commented Aug 31, 2015 at 19:02
  • 52
    Will it replace W3Schools just like SO replaced Experts Exchange?
    – Uwe Keim
    Commented Sep 4, 2015 at 19:16

94 Answers 94

868
votes

Yes! I support this idea, if the focus is to create examples.

I already use SO frequently to get a fast view of how to do something. For example, if I Google for "node.js write file", I want to quickly find how I can do it.

Google

On Stack Overflow:

Stack Overflow

On Node.js official docs:

Node.js

Which one is faster to get what you need?

I want to help writing docs for technologies that I like providing good examples for fast access.

41
  • 455
    +1 Immediate examples are so much more useful than here is a bunch of words to parse.
    – Dave Zych
    Commented Aug 31, 2015 at 16:57
  • 147
    Exactly what we want to fix.
    – Nick Larsen Mod
    Commented Aug 31, 2015 at 16:59
  • 56
    This example is very strange: the node/fs documentation you mention is full of examples. In fact the green links of your screenshot link to examples... See nodejs.org/api/… Commented Aug 31, 2015 at 17:39
  • 75
    @DenysSéguret I'd rather see the example straight up, than parse, understand, and maybe guess which method link is relevant; that I follow, and maybe find an example.
    – OJFord
    Commented Aug 31, 2015 at 17:46
  • 9
    Not to mention, where on the page your answer is.
    – Nick Larsen Mod
    Commented Aug 31, 2015 at 17:47
  • 7
    How would Qs like this one fit in when docs existed? Just a 'related question', which the now-answer to is obviously just "check out SO docs"? Would there be a new close reason, like "answer is an [example in the docs](link!)"?
    – OJFord
    Commented Aug 31, 2015 at 17:48
  • 27
    @DenysSéguret With something like that nodejs doc, there is so much information oftentimes people don't know where to start. With a simple, immediate example, it helps someone just get the dang thing working and from that starting point they can further review the docs and refine their code.
    – Dave Zych
    Commented Aug 31, 2015 at 18:00
  • 12
    @DenysSéguret Isn't that exactly what docs are for? People who don't know a feature of the language/framework they're working with? I've worked with NodeJS before (albeit not a ton) and I still get confused with their docs sometimes.
    – Dave Zych
    Commented Aug 31, 2015 at 18:20
  • 13
    Why do you think it's important for the page that helps you to be called "Documentation" rather than a "Question"? The current SO is already providing what you need. Commented Aug 31, 2015 at 18:30
  • 8
    It's hard to take that example seriously. I mean you have a perfect nodejs documentation and tons of examples across the web (and the first page on google). If you are still see a problem to find out how to write a file using nodejs, you are simply not willing to find it. period.
    – hek2mgl
    Commented Aug 31, 2015 at 22:54
  • 38
    If SO became the #1 repository of easily-searchable examples by language, framework, etc. I would never look anywhere else. Yes, one can google "How do I do X in Y-language/Z-framework" and you might come up with a examples through SO (sometimes), blog sites, etc., but if you want to do something in a not-so-popular framework or language, who better to show you how than the experts. I support this fully, as 99% of the things I search for in terms of software development are examples. Yes, I know how to read the Oracle Java Documentation, but that takes so frigging long. Commented Sep 1, 2015 at 16:32
  • 10
    @Zanon "it provides documentation, but it was not designed for that"... Every time I try to suggest on meta that the main driver of SO is askers having problems and answerers willing to help, with the knowledge building being a secondary, but intended effect, I'm told that SO has always primarily been a KB (especially by hardcore curators). Knowledge base and documentation are extremely similar concepts. If we're talking about "recipes", SO is spot on as it is. Class by class, method by method API documentation really belongs to the official stuff. Tutorials are a different category as well.
    – Bruno
    Commented Sep 2, 2015 at 15:17
  • 7
    Out of this exmaple I see, there should be a "make documentation" button on SO to create links back and forth and reuse already available content. Also I think, it would be better to create a "getting started" collection than of documentation where such questions are easily explained and afterwards comes further information to details. But I think, this example is pretty good. If I open node.js page, there are many links, where I would click on fs.write(..) since it is the topmost that sounds useful. So I won't notice fs.writeFile really and as beginner in node.js would go to SO ;)
    – Matt
    Commented Sep 3, 2015 at 12:19
  • 53
    I die a little inside when everyone starts going on about making it "faster" to go to examples without having to actually read. Without reading and perusing how are you going to gain any real understanding of what you're doing? Copy/pasting examples without understanding is exceptionally dangerous (IME leading to many stupid SO questions) and I'd really rather people went out of their way to put more time into their research, not less. As such, all this "yes yes move everything to SO so it's faster" seems to be like the direct opposite of what we should be doing. Commented Sep 3, 2015 at 13:39
  • 17
    @LightnessRacesinOrbit, "How to tie a tie?" - you can learn with a 2 minutes youtube tutorial or with a 30 minutes lenghty explanation with the different existing techniques and the history behind them. I agree that people need to read more to avoid basic mistakes, but it depends on the situation. If you need to write a file just for testing, a basic code example is enough. If you are building a log library like log4net that will be used by millions, so you need to read a lot about how to write files. What we need is to give people the power of choice.
    – Zanon
    Commented Sep 3, 2015 at 16:14
602
votes

I'm concerned about the fragmentation this can cause.

If a project already has awesome documentation that’s easy to search and cite, then there’s no need to duplicate it on Stack Overflow. We’re interested in fixing what’s broken with documentation, not just moving them onto Stack Overflow.

Some documentation sites like MSDN have both good and bad documentation. How do you see people decide on what documentation is good enough to not have to redo it on SO?

Is one of the goals to eventually see work being done here go back upstream to the official documentation of a project? If so, I think attaching a CC license to it could cause a lot of headaches down the line.

What if the official documentation is greatly improved, surpassing the quality of documentation on SO? Will you remove the content on SO?

These are just some questions that spring to mind, I'm sure there are other things to discuss about fragmentation.

37
  • 30
    It could end up being something similar to the sponsored tags - companies may opt to have their docs on SO Commented Aug 31, 2015 at 15:52
  • 67
    This is why I'd rather go to devdocs.io then having a wiki on SO.
    – Domino
    Commented Aug 31, 2015 at 15:53
  • 16
    But won't it be survival of the fittest? If people find the vendor docs are better they will link to that instead. Commented Aug 31, 2015 at 15:54
  • 89
    In the long run, we would like to be the official source of documentation for all the things. That's a very long term goal. We think that the changes we're making to documentation's unit of work, making it community editable, and the training aspects it brings to the rest of Stack Overflow are keys to its success. So, frankly, all the things should eventually be documented here, but for the beginning we want to fix the worst parts.
    – Nick Larsen Mod
    Commented Aug 31, 2015 at 15:56
  • 56
    These all seem like really good problems to have. In that any problem that arises due to having too much good documentation is, in some sense, worth having.
    – Shog9
    Commented Aug 31, 2015 at 15:57
  • 103
    One of the problems I have with even really great documentation is that it tends to lack real-world examples. Lately, I've been using Google to find out how to use language features that I haven't fully grasped. Often one of the results is a Stack Overflow question. I'm biased, but the answers to a real world question tend to provide better help than the often abstract official documentation. Examples are the overlooked (and I think revolutionary) key to this proposal.
    – Jon Ericson Staff
    Commented Aug 31, 2015 at 16:18
  • 115
    @NickLarsen: "In the long run, we would like to be the official source of documentation for all the things." - that's exactly what I'm concerned about. It would become a single point of failure, and a single point of control. Diverse and decentralised systems are safer and fairer. I'd love if you help to provide 21st-century-adequate documentation tools to the developer community, but I wouldn't like if they're hosted by a single company. Even if it's one that is not turning evil.
    – Bergi
    Commented Aug 31, 2015 at 16:48
  • 44
    If the end result of SO documentation is "documentation everywhere else on the internet is better than we could ever provide" then Mission Accomplished. I'll delete the code myself. More practically, I expect that if there's no demand for documentation for X (because X's docs are good) nobody will ask for them, and nobody will create them. Commented Aug 31, 2015 at 17:02
  • 23
    @KevinMontrose "[If] documentation everywhere else on the internet [becomes] better than we could ever provide then Mission Accomplished. I'll delete the code myself." -- That might not be so simple. A regular occurrence at Wikibooks are deletion requests along the lines of "we moved the book to a more appropriate platform, can you delete the obsolete copy here?", with the default reply by the community being "The CC license is irrevocable, we might develop the text in a different direction, there is no reason to delete it". How would we handle such scenarios here?
    – duplode
    Commented Aug 31, 2015 at 17:44
  • 13
    @duplode if the community cannot be convinced the alternative is better, why should the community delete it? And vice versa, if the community is convinced to shutdown a section how (and why) would we stop them? I know we're discussing hypothetical cases, but I have trouble imagining a scenario where a strictly superior alternative is presented and it fails to convince a majority of contributors to move. Put another way: we already delete sites, tags, users, and questions. I'm not too concerned about documentation being somehow (and uniquely) un-delete-able if merited. Commented Aug 31, 2015 at 17:51
  • 10
    So, most of the concerns voiced have been around "where are the lines". I think one thing this answer demonstrates is that we need a follow up post that lays down some more of the "rules and guidelines" we've imagined exist. Would you agree @Stijn? Commented Aug 31, 2015 at 20:12
  • 15
    I’m also not completely convinced that having another prominent contender will not split up the documentation-willing userbase. For example for web stuff, we already have Wikis like WebPlatform and MDN, and other strong platforms like MSDN or even devdocs competing with each other; and neither platform is really exhaustive on most stuff.
    – poke
    Commented Aug 31, 2015 at 21:07
  • 14
    @NickLarsen "In the long run, we would like to be the official source of documentation for all the things." I think this is overly ambitious and will fail. The reasons are that the producer of code is the official source of documentation and that SO has a nice plattform but maybe not the best suited for all ways of documentation. Also it would require an awful lot of effort and commitment which is difficult to imagine with volunteers. I think that smaller goals are more realistic and helpful. Commented Sep 1, 2015 at 7:32
  • 7
    Agreed. I would be much more enthusiastic about this proposal if the goal were to encourage/facilitate collaboration with maintainers of existing documentation (especially--though not limited to--"official" documentation). This would have the dual benefit of improving official documentation and providing SO Documentation a lot of initial content. "Usurping" should be considered a tactic of last resort, or an unfortunate accident. Also, this strikes me as related: xkcd.com/927 Commented Sep 1, 2015 at 18:44
  • 18
    @KevinMontrose: "I expect that if there's no demand for documentation for X (because X's docs are good) nobody will ask for them, and nobody will create them." I worry that rep miners would simply copy the official docs; lots of people will search on the Docs site and find and upvote the copies. I guess the community would flag this and moderators would delete the copy, but it will be confusing to users, and will happen continually. Commented Sep 1, 2015 at 23:20
311
votes

I don't want to be too negative about this idea, but it does make me uneasy. The main issue is how it blurs the line between official documentation and community-contributed content. Explaining a bit further: a while ago someone proposed that Hackage (the main repository of Haskell libraries) should make the symmetrical move and add user comments to the API documentation, perhaps with wiki curation a la Stack Overflow. I replied with the following comment:

I see your point, but when I go to Hackage I expect to find canon, word-of-God from the developers, and not a blooming garden of possibly conflicting advice (as expected in /r/haskell or other discussion platforms).

Evidently the concern is not as serious for what we are discussing here, as Stack Overflow is (at least in principle) not an official part of any project. The core issue, however, is the same. As I see it, documentation, be it good or bad, is canon, information vetted by the developers. Treating user-submitted content as documentation risks confusion, obsolescence and, as Stijn points out, fragmentation. There might be effective ways to avoid that, but I would suggest treading carefully.

32
  • 90
    Fair point. I know I'd be pretty disillusioned if I ever found confusing, obsolete or fragmented information on a developer's official site.
    – Shog9
    Commented Aug 31, 2015 at 16:08
  • 11
    @Shog9 lol. We're being chipper today, aren't we? :)
    – Pekka
    Commented Aug 31, 2015 at 16:09
  • 52
    This whole discussion is bringing back unpleasant memories of installing MSDN from cd-rom.
    – Shog9
    Commented Aug 31, 2015 at 16:10
  • 11
    This is a valid point. Our approach is entirely based on serving the immediate needs of developers in the sense of "I searched google for a problem I'm having right now", with enough effort put into the back end to support the "I want to learn everything there is to know about this thing". "Official" documentation doesn't really matter to the user in the first case, I just want my problem solved and as fast as possible. I'd also argue that usually best practices are the result of people using it how they use it, not just how the developer wants it to be used.
    – Nick Larsen Mod
    Commented Aug 31, 2015 at 16:20
  • 16
    @Pekka웃 But this then brings us to another problem: Who is an "official" contributor? What's the threshold? On the Internet, nobody knows you're a dog. Also, FFmpeg, Libav, or both? Apache OpenOffice vs LibreOffice? eglibc vs. glibc? egcs vs. gcc? Adjudging who is or is not an "official" contributor rapidly brings into play questions of anonymity, open-source project politics and duplication, especially after controversial forks. Commented Aug 31, 2015 at 17:11
  • 5
    I don't think we're blurring the line very much, it's not as if we'll be saying "we're the official .net docs", and we won't be co-opting anyone's branding or anything nefarious. SO Documentation will look no more official than SO Q&A does; if a project wishes to endorse SO they could (I mean, long term; I don't want any endorsements until we're out of beta). Commented Aug 31, 2015 at 17:26
  • 7
    Agreed. A good bad example is the "official" php-doc at php.net.
    – alk
    Commented Aug 31, 2015 at 17:50
  • 1
    How would be handled the foreseeable controversial articles? If mr. X posts his solution and mr. Y posts an opposite one, what it would be seen like? Based upon users voting? Commented Aug 31, 2015 at 19:03
  • 1
    in my experience the examples provided by official documentation rarely provide the use case you are looking for. The official source will provide the "basic" or "1-path" example. Hopefully the SO version will provide the examples for other use-cases and/or for other combinations of code.
    – John M
    Commented Aug 31, 2015 at 19:20
  • 7
    @KevinMontrose - Nick said the opposite: "we would like to be the official source of documentation for all the things". I certainly think there is a need for community provided documentation augmentation, but I've also seen problems arise when non-authoritative sources try to look like official documentation. I think this endeavor can be a great success, as long as it addresses the fragmentation and officiality concerns.
    – gilly3
    Commented Aug 31, 2015 at 20:03
  • 18
    @gilly3 Nick's saying "if, in the future, the actual owners of the product/library/whatever officially declare us to be the docs that would be awesome"; not that we are going to declare ourselves the official docs. Commented Aug 31, 2015 at 20:05
  • 6
    Just because we're not canonical doesn't mean we're not extremely helpful. Just like any other SO answer, it's up to the readers to decide how helpful something is--if it's bad documentation, it will get downvoted or edited. End of story. No real problem there.
    – levininja
    Commented Aug 31, 2015 at 20:38
  • 7
    Also, no matter how carefully you label these as unofficial documentation, we all know how carefully new programmers in a hurry pay attention to that stuff. A project like this will surely create at least some complaints to the developers of a project about "incorrect" documentation" that exists here. It would not have to be a flood of such complaints to really sour the folks developing the tools we'd be trying to "help" by providing documentation.
    – joran
    Commented Sep 1, 2015 at 16:43
  • 1
    The beauty of Stack Overflow is that, even though users can submit a "blooming garden of conflicting advice", the voting system takes care of it. People will upvote what is useful and correct, and downvote what is incorrect or unclear.
    – jtbandes
    Commented Sep 1, 2015 at 20:22
  • 3
    For the php.net example, its docs aren't bad [might be biased as core php-src dev], but it often lacks real-world examples and user comments sometimes are better docs than the actual docs. Also, I feel like php.net is suffering from a too high bar to edit. Yes, there's edit.php.net, but it's clumsy, and nobody likes that docbook syntax... [Sure, once you perfectly know that syntax, fine...]. Hence I definitely can appreciate an attempt for better examples/docs. Might even lead to php.net doc maintainers to search examples here… maybe… IMO, we really need to give it a try and we'll see.
    – bwoebi
    Commented Sep 1, 2015 at 21:57
270
votes

Like Stijn, I'm concerned about fragmentation. However, I love one portion of this: examples. To me, great documentation has non-trivial examples of how a method or group of methods work together. It shows more than a single line of code and explains what's happening.

It's one thing to read a document that accurately describes how a complicated class works or how a method with tons of parameters does its magic. It's entirely another thing to see working examples of how they work.

If this can provide those examples and do it in a way that complements the documentation of popular (and unpopular) projects, I'll be one happy developer.

18
  • 16
    totally agreed. When I google a class or a function, what comes up is often an official reference followed by a stackoverflow question. Most of the times I click on the question looking for a usage example. Commented Aug 31, 2015 at 16:00
  • 167
    So maybe just examples instead of full documentation? And the next step would be tutorials... Commented Aug 31, 2015 at 16:06
  • 5
    So I was thinking along these lines as well. It's the examples that will add true value. But that means that the examples need to be peer-reviewed (duh) but also complete and self-contained. What needs to be there to make the example work needs to be there, or it's not really useful to the person that needs the example. So, there must be enough sample data provided to make that algorithm function, not just the mathematical markup of the theory. Commented Aug 31, 2015 at 16:25
  • 12
    Some of the MSDN I use has lots of detail, but no examples and no guidance on how to use the software. So I support examples and tutorials.
    – AdrianHHH
    Commented Aug 31, 2015 at 16:32
  • 4
    Agreed AdrianHHH - Starting out on Microsoft products without examples and guidance, and just straight up nearly-meaningless (for a noob) documentation on MSDN, is harder than it should be. Commented Aug 31, 2015 at 16:38
  • 7
    Good examples are essential. Not every piece of working code is a good example, so we'll need peer review and editing. An example should be the smallest body of (realistic) code that demonstrates the feature, and everything important should have inline comments. In my experience the push for this comes from two places: trying to actually use the example (and realizing it's lacking in some of this) or trying to *explain the topic in words" (write documentation). We shouldn't be writing tons of text, but we probably don't want "none" either. (And yeah, then there are tutorials.) Commented Aug 31, 2015 at 20:36
  • 6
    Examples may be the best thing about this, but I think it should in no way be limited to examples. If the developers of the product didn't bother to document HOW something works, and someone can provide that based on their understanding of the source code, it would be better to have that than not.
    – levininja
    Commented Aug 31, 2015 at 20:36
  • @Trilarion Yes examples and tutorials are probably a better way to approach this. Documentation is not very helpful without a code structure to go by Commented Sep 1, 2015 at 3:27
  • 1
    I have one major problem with tutorials: they're tutorials. They end abruptly, are full of holes and tend to tell people where to click but not why, or perhaps even more importantly why click there and leave out the part that explains why not to click somewhere else. The people who read tutorials are generally the people who need far more than tutorials (and end up on SO), and the people who can benefit from tutorials generally don't read them because they only actually need a tiny subsection of it that they didn't commit to memory yet. Lets write guides instead.
    – Gimby
    Commented Sep 1, 2015 at 11:22
  • 1
    @Gimby Quite right on some tutorials. But good tutorials can be written to include the whys and the why nots and the alternatives.
    – AdrianHHH
    Commented Sep 1, 2015 at 11:31
  • 3
    @Trilarion and many others. So, we've envisioned Documentation as containing several different "sorts" of pages (all in the same style view, with required examples and optional sections); including short Tutorials (and things like "Getting Started" or "Hello World"). Short Tutorials fit in this model, though long ones (several pages) don't really. I think we'll be expanding upon this, and a bunch of other stuff, in a follow up meta post. Commented Sep 1, 2015 at 15:17
  • @KevinMontrose I see. It might not be what we others here envision. Tutorials are often long. Short tutorials might only be examples. Even good examples might become several pages long. Something that is shorter might be typical use case of a function instead of full blown examples. Maybe that is what you mean? I will certainly follow further meta posts. Commented Sep 1, 2015 at 18:59
  • I applaud this effort, and have often wondered why there weren't more substantive usage examples available. I also realize this is not just for one language, but as a concrete example the major problem i find when consulting Google's Android SDK docs is the abysmal lack of usage examples. My searches almost always necessitate locating a suitable reference elsewhere to see and understand what should actually be done.
    – Zeus56
    Commented Sep 1, 2015 at 19:04
  • 1
    @KevinMontrose - Trying to balance between snarky rhetoric trying for witticism and an actual question, how well documented do you expect Documentation to be? Well-written documentation should have a good style guide; something better than "put examples here". How do you plan to address that, if at all?
    – J.D. Ray
    Commented Sep 3, 2015 at 21:42
  • 1
    Instead of Documentations, Examples and Tutorials are a better choice, IMO. Because we don't come to SO to read a lot of documents, we just want precise answers and solutions. SO was meant to provide solutions and not the background history of why and what. Commented Sep 6, 2015 at 14:48
229
votes

I say the following from a technical writer's perspective. Creating software documentation is my job.

TL;DR at the bottom.

How

  1. Do you know why you see so much documentation like that? Because the technical writers begged the developers to answer an email or show up at a meeting for months, and the developers simply refused. And then it's time to get everything ready for the final build, and what are we supposed to do? Leave it blank? Better that it look sort of okay but not really be too useful than look obviously incomplete, because the devs sure aren't getting fired for failing to do their jobs (yes, documenting your work is part of your job), and we have no plans to take the fall for their failure.

  2. The answer to this is the same as above: everything we get comes from the developers. All we do is turn it into comprehensible English, format it, and just generally clean it up. I'm sure you all know the saying, "Garbage In, Garbage Out"... if the devs don't provide the writers with some examples, the documentation will not contain examples. Since nobody likes doing extra work, the devs will only provide examples if Marketing forces them to do so, which only happens after users have been complaining about the lack of examples for a few releases. And that assumes that the company even has the resources to do this (e.g., "all of the examples for your language-agnostic tool are in language X. I want examples in language Y" when all the devs and writers are already pretty busy).

  3. The documentation is as "complete" as we can make it. Some devs are awesome and provide a ton of clear information that we can easily turn into documentation. Other devs... not so much. Regarding the way that documentation is tied to release cycles: yes, that is certainly true.

  4. That sounds like the sort of documentation that has never been touched by a professional writer. That's not a condemnation - sometimes there aren't any writers available, for a variety of possible reasons. However, that means that the documentation is going to be a direct reflection of the developer's attitude toward documentation. If a developer thinks that Javadocs are enough, that's what you'll get. If a developer sees the importance of a more modern layout (maybe they're a professional technical writer who codes in their spare time, like myself), they might actually spend a small fraction of their development time putting together some nice documentation.

What

  1. One of the things I like about SO is its attempt at concision (think of it as JIT compilation or lazy evaluation): instead of finding all potentially useful pieces of information and making them available on SO just in case, we try to limit it to things that are verifiably useful to some degree. How is that determined? It's simple: if someone actually encounters an issue, that verifies that someone might run into that issue. They then post a question. A "broader place for artifacts to live," however, sounds suspiciously close to hoarding. What if there's a GetRowEnumerator() that no one has ever actually needed to use? Would such a thing belong on SO? Should such a thing be included in Documentation?

  2. Perhaps you haven't realized, but SO has basically become de facto documentation, even for products/projects that do have official documentation. Will you find the very basics; the things that are already very easy to find elsewhere (e.g. basic tutorials or how-to documents)? Nope! But that's okay, because SO doesn't need to duplicate the Internet. We only do the tough parts (ideally).

  3. So, the people who ask a Question instead of Googling their Question's intended title are suddenly going to start Googling, just because there would be even more results in the Google search they don't want to run?

  4. This is known as "kicking the can down the road." When the Stack Overflow Documentation is, through the significant effort of many developers (who are now inexplicably excited about writing documentation), reasonably useful, thorough, and detailed, how will people pay it forward? Adding another cell block to the prison won't improve the K-12 education system or the economy.


Or we’re wrong.

Unfortunately, I think that's the case.

But we think it’s worth having a go at it.

...and you're doing it anyway. Okay then.


TL;DR: I think the concept of adding "Documentation" to SO (or an adjoining site) is deeply flawed. It attempts to solve the problem of "developers don't like writing documentation" by having developers write documentation, and the problem of "people ask duplicate Questions instead of Googling" by expecting people to click a Documentation link in a Google search.

76
  • 17
    We're asking the community about having a go at it anyway, rejection is a valid possibility. Most of this could apply to Q&A I think, many places had Q&A before SO (and many have it now) but their devs don't participate; and yet SO works. If people treat the Documentation section as a job, I agree it will fail. I also agree with What's #1 & #2. Completionist documentation doesn't interest me (I don't care about documenting every .ToString(); only stuff people actually need). And yes, lots of SO content is better than docs; but we also turn away a lot of it as too broad, docs can fix that. Commented Aug 31, 2015 at 18:46
  • 29
    I also think you vastly over estimate how many existing docs, when they show up in Google results at all, actually help you when you click them. Plenty of folks search around, and then end up asking questions anyway; we can't help those that don't Google at all, but we can help some of those who do. Commented Aug 31, 2015 at 18:47
  • 118
    With due respect to your actual experience writing docs, I think that your perspective "It attempts to solve the problem of 'developers don't like writing documentation' by having developers write documentation" is off. There's actually two sets of devs in this scenario: the ones writing the tools, who don't like writing docs, and others who are using the tools and who may indeed like writing them (and may be good at it). The latter, I think, are the people already writing answers on SO.
    – jscs
    Commented Aug 31, 2015 at 18:55
  • 31
    Please, no reductio ad absurdum. Commented Aug 31, 2015 at 18:57
  • 24
    Sorry; I guess I'm a bit defensive about documentation. People pay for software/hardware, not documentation, so it can be difficult to justify a writer's value to their organization - particularly an organization without Apple-tier petty cash. This "SO Documentation" looks like bulldozing a building to fix the broken windows. We could make very nice windows if people would let us. You want to create value by preemptively improving documentation? You can get better documentation by telling the world that documentation has value. Commented Aug 31, 2015 at 20:21
  • 12
    Also, if people saw more financial and practical value in documentation, I would possibly still have a job next week. Commented Aug 31, 2015 at 20:27
  • 18
    @TigerhawkT3, I sympathize, but your position seems extremely biased -- considering you literally feel financial competition by this free alternative.
    – Kirk Woll
    Commented Aug 31, 2015 at 20:59
  • 20
    Of course I'm biased. That is the source of my expertise. However, I'm trying to explain that the reason there's so much bad documentation is because people don't care enough about documentation. It's like telling the construction worker not to bother with the broken windows, and then complaining about the broken windows. And then, of course, telling the construction worker that you don't trust what he says because you think he's just mad about the plastic wrap being used as a window substitute because people really do need windows. Commented Aug 31, 2015 at 21:04
  • 14
    Disagree with current way answer is phrased: the proposal as I see it is to let people who care to write documentation (generally both sides are developers which makes it even more confusing). People who use the product have much better chance to create useful documentation compared to original developer who may have idea how to use the product/library (especially for large organizations). Commented Aug 31, 2015 at 21:33
  • 24
    I think this answer merges two types of developer: those who developer the software and those who use the software. Only the first group matches your explanation. There are many developers who use software written by others and write blogs about what they are doing. These people like documenting things. But that writing is scattered and has little or no peer review. I see the proposal here as providing a place where writers can contribute useful stuff without needing their own blog that may or may not be easy to find and that, probably, has no peer reviews.
    – AdrianHHH
    Commented Sep 1, 2015 at 9:08
  • 18
    While I agree with many of your points and share many of your concerns, a remark regarding the "...attempts to solve the problem of "developers don't like writing documentation" by having developers write documentation" part (in addition to some things that others said about this already) : You seem to underestimate the value of useless internet "reputation" points. Some people really go crazy for some rep. (That's why I think that the rep handling is a crucial point as well in this proposal...)
    – Marco13
    Commented Sep 1, 2015 at 10:51
  • 8
    You seem to be equating the proposed documentation with documentation written internally, whereas a far fairer thing would be to equate it with other third-party documentation/wiki sites. Unless you think no third-party documentation should ever exist? Yes, it'd be nice if everyone in charge of deciding which language/product to use insisted their vendors had good internal documentation written by technical writers, but that's a dreamworld. We live in the real world where third-party documentation is frequently needed by developers, and SO is here to help developers get work done. Commented Sep 1, 2015 at 11:42
  • 6
    Sorry if this cannibalises your job. But honestly, if you think 'the devs wouldn't get back to me' is a justification for opaque, unhelpful writing of any kind, perhaps you should find another.
    – Jonathan_W
    Commented Sep 1, 2015 at 14:53
  • 10
    I see your frustration but, with respect, I don't think the documentation world has to be as grim as you're painting. I'm a technical writer too, and I routinely read source code, use the software, push back against counter-intuitive or inconsistent design decisions, and ask the developers "why?" & "how?". If documentation comes only at the end of the pipeline it's always going to be a struggle; the earlier you can get in there and be part of the ongoing discussions, the better. Also, I get better results from "I see X in the code; is that right?" than "tell me" -- even when I'm very wrong. Commented Sep 1, 2015 at 17:53
  • 18
    It is a little shocking how easily people are slipping into ad hominem. The main takeaway here is not that TigerhawkT3 is concerned about his options in the job market, but that Stack Overflow Documentation cannot possibly be an ultimate solution to the documentation problem, as the pitch for this proposal makes it sound like.
    – duplode
    Commented Sep 1, 2015 at 18:34
118
votes

I was going to post more thoughts in comments, but an answer fits this better.

I am intrigued by this. I think it could go places. I really like the focus on examples than a bunch of words. Bunches of words (maybe) help highly experienced people. They don't help people who are looking for "how do I do X?" and they often don't help the more experienced people since they already know most of the blah blah blah.

Misc thoughts:

  • Keep in mind how people normally arrive at documentation. I normally arrive at it through google, something like "[language] [functionality] [example]" as a search parameter. Unless this documentation is really comprehensive, I will probably still search that way.
  • Ability to close questions as dup of documentation. This would be great, especially if you have a way to incentivize it somehow
  • Reputation: just a general thought, this is still "too early to tell" I'm sure but keep in mind that writing a good piece of documentation or example can be 10x the work of a simple "do this" answer.
  • Design the system for users wanting quality over quantity. Probably the main reason I don't post much on SO anymore is the firehose of low quality stuff. I like writing lengthy answers (which is probably why I like Workplace so much). This system should not be designed for people who like cranking out 20 answers an hour. It should be designed for creating quality content, not just quantity. This seems obvious but SO has a serious problem with this because of the firehose effect.
17
  • 4
    All correct. The thing you left off is "there is only one topic for each thing" so you need to provide sufficient incentive for editing of existing content.
    – Nick Larsen Mod
    Commented Aug 31, 2015 at 17:43
  • 6
    @NickLarsen it depends greatly on what that topic is... if you are talking about, "how do I use an array?" there may be dozens of scenarios you want examples for. Which might be another related comment, this needs to have a clear scope for each topic and how that will all work. You are going to be using very common words to people, "Documentation" is a widely understood phrase, and if SO's model for that will be different that needs to be clearly figured out. Or you'll get the "comments aren't really comments" problem, too.
    – enderland
    Commented Aug 31, 2015 at 17:50
  • 2
    Comments are one of the things that sucks about existing documentation, so we're not really going to have them. Instead there will be a flagging system or you can just directly fix the problems you see. Don't think of topics as one to one with examples, a topic has many examples, but not too many or else you really need two topics. If these kinds of design choices seem interesting to you, please join the beta list.
    – Nick Larsen Mod
    Commented Aug 31, 2015 at 17:54
  • 4
    @NickLarsen I mean more the mismatch between how SE uses "Comments" and how the rest of the internet uses them. I'm pointing out that if this is called "documentation" but is really something different, that'll be a naming and branding problem
    – enderland
    Commented Aug 31, 2015 at 17:55
  • 2
    @enderland I do not believe we should ban short documentations however, as creating a documentation can become a community effort. Someone writes a small example, and someone else adds to it.
    – Jeroen
    Commented Aug 31, 2015 at 19:00
  • 1
    People should use alternative search engines more often. Virtually all posts here mention Google as the only one ☹
    – mirabilos
    Commented Aug 31, 2015 at 19:38
  • @mirabilos I'm still waiting for Google to let me down...
    – enderland
    Commented Aug 31, 2015 at 19:49
  • 1- I'm not sure that closing question as duplicate of documentation is a good idea. 2- What is Workplace ? Commented Aug 31, 2015 at 19:54
  • @XavierCombelle To answer your second question, Workplace is another Stack Exchange site.
    – Kendra
    Commented Aug 31, 2015 at 20:06
  • 3
    @DanGetz I did, but I think the concept of a firehouse is a bit more fitting anyways, I'm picturing a hose spitting out houses which are on fire. Sometimes that is what SO feels like if you browse the "Newest" tabs.
    – enderland
    Commented Aug 31, 2015 at 20:12
  • 2
    @mirabilos: Compare "Kleenex", "Thermos", "Sellotape"/"Scotch tape", or "Xerox". "Google" has become a "genericized trademark".
    – jscs
    Commented Aug 31, 2015 at 23:03
  • 1
    While I would also want to be able to close questions as dupes of documentation entries, I do see the issue that documentation pages are not necessarily as static as they would need to be for that purpose. It’s simple for questions: Nobody is going to edit a question completely, so using other questions as dupe targets is fine. But documentation is likely to change a lot more; for example someone decides to split up an existing page into multiple separate topics (because there is so much more to write about it). That is a good thing, but questions having the page as dupe target will break.
    – poke
    Commented Sep 1, 2015 at 13:24
  • 1
    @NickLarsen My money's on "we don't need comments" being the new site's "we don't need meta". If you don't have comments as comments, you'll need some other mechanism to fulfill the role that comments normally cover, and I'm skeptical that flagging and "fix it yourself" is going to cut it.
    – R.M.
    Commented Sep 8, 2015 at 20:02
  • 2
    The discussion here about the semantics of "comments" cracks me up and is particularly ironic considering the semantic wraparound inherent in meta. Anywhere else on SE, 3+ comments in a discussion flow: Instant banhammer on the discussion under the mantra "Take it to chat, guys"; On meta: [endless, mishmashed, hard-to-parse, semi-contextless chatter -- like this very discussion]; Anywhere else on the internet: [threaded, deliberate extended discussions]. I wonder what will SO's semantic wraparound for "docs" and "examples" and "tutorials" and "comments" be?
    – zxq9
    Commented Sep 16, 2015 at 15:48
  • 1
    I also wonder how many minutes from the moment of launch before any docs site is overrun with god-tier editors with nothing better to do than proclaim themselves Protector of the Realm and render it a Wikipedia-level edit-unfriendly environment. That'll be swell. That and the low-quality firehose (in interesting opposition to one another) are already issues that drive confusion, annoyance, and feelings of repulsion in SE sites. I don't see how docs would be any better, especially since they will compete with official docs. This is a pile of hard problems.
    – zxq9
    Commented Sep 16, 2015 at 15:51
94
votes

If this is to be a success, I think it needs to address concrete problems that active question-answerers currently have with Stack Overflow. Problems like

  • The endless flood of duplicate questions
    • ... which we know perfectly well have already been answered but it's hard to find the canonical duplicate
  • No good place to put canonical explanations of things that someone didn't actually ask about but need to know anyway as a consequence of their question, e.g. "Never use scanf", "The type-based aliasing rules are asymmetric," and "You should consider using something other than a shell script to solve this problem" (to pick three things I find myself saying over and over and over again)
  • The longer you've been on the site, the harder it is to find interesting questions to answer

Address these problems and you're more likely to get a critical mass of interested writers out of the starting gate.

I also want to endorse what several other people have said about making sure that documentation finds its way back to upstream open-source projects. Many such projects know their documentation is terrible but have neither the expertise nor the brain cycles to do anything about it. A community-of-practice that knows how to write good documentation for anything and how to cooperate with upstreams in getting it integrated could go a long way to solving that problem, and the SO community could be that community -- but it will take active cat-herding in that direction. (And I know I would feel better about writing docs on a third-party site myself if there were gnomes making sure it got pushed up to the first party.) Note that the appropriate licensing for docs going upstream is not one-size-fits-all; many projects want explicit permission to redistribute under their licensing and have varying degrees of paperwork that needs filed.

And finally, please look at existing community-contributed documentation for both what to do and what NOT to do. The best existing (semi-)community-written documentation site I'm aware of is MDN,1 and the go-to place for what not to do is of course the official PHP documentation with its cesspit of bad user-submitted advice at the bottom of every single page...

1 I do not know how much of this documentation is written by MozCo employees versus the larger community; I do know there is an organizational unit devoted to making sure it doesn't suck.

9
  • 11
    "making sure that documentation finds its way back to upstream open-source projects" Yes, this. IMO this would mostly solve the fragmentation problem people have been expressing concern over.
    – Ajedi32
    Commented Sep 1, 2015 at 16:26
  • 3
    I've always thought that the PHP documentation is really good, probably the languages greatest strength, as long as you ignore the comments. I particularly like the way you can type php.net/[function-name] into your address bar and get to the right page in one step.
    – rjmunro
    Commented Sep 7, 2015 at 11:12
  • @rjmunro Yes, the PHP documentation itself is fine. It's only the user-submitted commentary, and in particular, the way the PHP core organization neglects it and considers themselves not responsible for its quality, that should serve as a cautionary tale for this proposal.
    – zwol
    Commented Sep 7, 2015 at 14:38
  • Oh good, I'm not the only person who thinks the PHP docco (and comment process) is a cesspit. The problem, as I see it, is that people don't comment to improve the docco - they comment to advertise their fancy workaround/solution/hack/bodge for a bug/feature that may or may not exist. I would rather read experts-exchange than a comment thread on php.net.
    – Juffy
    Commented Sep 8, 2015 at 6:23
  • @Juffy PHP documentation are very good structured (tree structure of reference and structure of each topic itself), has great many versions and languages support, has both good and bad comments and the way to up/down vote those comments. And more valuable it has platform for community to contribute and improve this documentation, i think, it worth having to look at it's good parts and take all good experience it has.
    – Mikl
    Commented Sep 9, 2015 at 22:31
  • @Mikl - sorry, I should have restricted that just to the comment system. As a PHP noob though, the comments are generally massively unhelpful for the page they're on. Trivial example here - this is the friggin' contents page for the Variables section, not the page on how to initialise variables in strange and interesting ways. Why is there any comments on a page with no content other than four links? There's even a specific page for variable variables, but that comment isn't there. /rant
    – Juffy
    Commented Sep 10, 2015 at 1:30
  • @Juffy Why did I click that link. Why. goes in search of the brain bleach
    – zwol
    Commented Sep 10, 2015 at 1:41
  • @Juffy it's a good example of problem with comments management, if you need to divide one page into several and change the page type to category for this sub pages. I think in previous version there was one big page for variables. By the way, this problem can be on every platform, and on SO too, the example is there is some near the same questions that has different number of valuable answers and to read all of this you need to go throw all of this questions.
    – Mikl
    Commented Sep 10, 2015 at 1:58
  • @Juffy (last part of previos comment) In this situation with php docs it's simpler, if you learn php you can just go throw all of it's basic reference (it can be done very quickly), and you will have nearly all information you need at first steps.
    – Mikl
    Commented Sep 10, 2015 at 1:59
94
votes

Name the expansion “Examples” instead of “Documentation”

If you ask most SO contributors if they’re good at writing “documentation”, they’ll say No.

And if you ask most SO users (us) what they’d like to have, they’re not going to say “good documentation“. Instead, as Andy suggested and as Zanon also note, what users (we) always really want are good examples.

And writing good examples is actually what good SO contributors are already good at. Clearly, the best answers to SO questions are very often the ones with great examples.

And in order to provide a good example, you have to not only make the example code, but you have to explain the code—explain how it works, and why.

Giving good explanations like that for examples is, essentially, providing “documentation”. In the end, that’s what good documentation is. The documentation just falls out from the examples.

But calling it documentation doesn’t win us anything. Most of us in our work lives don’t like being asked (told) to produce “documentation” as such—and resent having to spend time on it instead of coding. In fact I’d argue that most of us really don’t even like the word “documentation“.

But we all do like explaining things—that’s why we spend time on SO! And we all do like giving each other examples—and explaining those examples.

So, names can make a really big difference in the success of anything. And given that fact, I think this proposed expansion of SO will have a much higher chance of success and of getting off on the right foot to begin if it has the right name.

So let’s please not name it Documentation. Let’s just name it Examples.

9
  • 10
    I agree. I think they're vastly underestimating the amount of baggage that word carries. There will be very few discussions of this project on its own merits if it has to bear that burden.
    – Frank
    Commented Sep 1, 2015 at 15:32
  • 1
    "If you ask most SO contributors if they’re good at writing “documentation”, they’ll say No." What evidence do you have for this?
    – kdbanman
    Commented Sep 1, 2015 at 18:53
  • 3
    I agree. It seems pretty clear that many of the negative responses here are due to the fact that "documentation" sounds like a duplication. I think that easily searchable "objective-oriented" examples are very useful without duplicating official docs. I also think this follows the Agile principle of working software being more valuable than comprehensive documentation. Commented Sep 3, 2015 at 23:13
  • 2
    I agree. Nobody likes documentation (its always wrong) and nobody likes writing documentation (it sounds too much like "work"). On the other hand, everyone likes examples that work and enlighten. Examples benefit the author because it is an opportunity to show off and help others at the same time. Readers like examples because it gets to the point.
    – TomOnTime Staff
    Commented Sep 9, 2015 at 15:39
  • Exactly what I wanted to propose after reading about the idea. Examples would be the best part of documentation anyway. Documentation as I see it also implies some kind of completeness which will probably never be achieved in SO documentation. Examples do not have this connotation.
    – Mifeet
    Commented Sep 12, 2015 at 15:23
  • And explanations. Most of the Content Management Systems I'm specialised in developing are basically just .Net, but with a rigid framework - so any .Net dev could pick one up easily if they just had a high level overview of the concepts behind the system. And as an experienced developer I sure as hell could use a repository of examples for when I forget what class to inherit or something.
    – Brett
    Commented Sep 16, 2015 at 14:41
  • I'd have to agree with this to a great extent (that "Documentation" might drive some decent contributors away) - not sure whether "Examples" is clearly the best choice, but something along those lines. I don't know - "E.G." comes to mind as having that same meaning, but being similar in tone to "Stack Overflow", "Super User", and "Server Fault" -- but in slightly different words, often what is already available from developers is basically syntax - it's a thing that's built in and testable from many IDEs even! What is most often missing is examples. Commented Dec 4, 2015 at 14:42
  • I do, however think that any such system should encourage syntax to be specified. Smaller software/API projects might use such a site solely to host their documentation. If it ends up making sense, larger and larger projects might migrate to this system or (through some sort of docs/e.g API) include examples from this site in their official documentation, where they simply provide the structure and summaries that are relatively easily testable and then outsource the examples (?!?!?) Commented Dec 4, 2015 at 14:48
  • 200% this. Examples = good. Documentation = been there, done that, bought the T-shirt.
    – NateJ
    Commented May 23, 2017 at 16:57
89
votes

This is a really exciting idea.

But I have a few concerns:

  • "Versions" are Arbitrary

    .NET has major releases, but that doesn't necessarily mean that the individual libraries within the product follow those version numbers.

    For example, .NET 4.5.1 was rolled out fairly recently, but the "Product Version" of the Accessibility.DLL file is 4.0.30319.18020. Meanwhile, on MSDN, the documentation for versions 4.5 and 4.6 of the Accessibility namespace are lumped together, though the URL shows version 110.

    So which version number is correct? Only the authors of the library can truly understand the significance behind a "version" and how that impacts individual parts of a system.

    And then there's open source projects and their many branches and forks. How does one keep track of version numbers in such messy situations?

  • Not all documentation can be neatly tucked under one heading

    The best documentation provides broad overviews and then connects the dots between different parts of the API. Documenting functions and parameters will only ever cover a small part of an API's functionality.

    Recently I tried to wrap my head around OAuth. While the individual query parameters were pretty well documented, what I really needed was a detailed overview of the flow for my particular (uncommon) scenario.

    Looking at .NET again, there are some libraries that overlap one another. I depend on documentation to explain the differences between the libraries and to help me determine which fits my needs. It's just shades of gray from that to a comparison of VB, C#, C++ and F#.

    Would this fit under SO's documentation? Just imagine the battles between those who say "yes" and those who say "no". It's uncharted territory and it's going to get ugly before it gets better.

  • Does SO want to be everyone's documentation host?

    Already a lot of major technologies point developer to Stack Overflow to get their questions answered (in lieu of a standard community):

    enter image description here

    Do we also want projects to abandon their own documentation platforms and move everything to SO? A lot of those documentation platforms cost a pretty penny (if not the CMS, then the hosting and bandwidth), so the idea of a completely free documentation host where the community will help you out (so you can downsize your documentation team) would be very tempting. Do we want that?

  • RTFM just got more complicated

    Is documentation going to be a separate resource from Q&A? If someone asks a very specific question that's already covered in the more general documentation, will it be closed as a duplicate?

  • Incentives are important

    On second look, it seems that reputation will be earned via "contributions" rather than posts. Sounds interesting... can't wait to hear more details.

    How do I earn reputation with topics? Will my "answer" get upvotes?

    Answers to Q&A questions often overlap one another, and the most thorough and correct answer tends to be get the most upvotes. But that doesn't mean that the most upvoted question contains all of the information needed by everyone. This is already an issue with some very specific questions, and will only be compounded by the very "general" nature of a "topic". It'd more important than ever for the community to collaborate and create a single source of truth, like a wiki answer, rather than 30 answers that mostly repeat one another, forcing visitors to read through many posts to find their use-case.

    But users don't earn reputation from wiki answers.

    So back to the question... how do I earn reputation? And if I don't, then why am I spending time working on documentation when I could be getting rep (and warm fuzzies) by answering questions?

15
  • 1
    All these points are spot on, and we're still working on them. We're showing this off early to make sure we're going in the right direction, there will be more details in the future and things are actually decided. We have guesses that will be tested/proven/broken/etc. in the betas and beyond. I'll expand in individual comments because length, and also voting. Commented Aug 31, 2015 at 19:51
  • 1
    Versions are arbitrary. We intend to allow the community to add new versions, and once a version is added it'll be available throughout a topic for both page level and markdown block use. What level of version is worthy of this will be decided on a per-tag basis; for .net the 1.0, 2.0, 3.0, 3.5, etc. level probably makes sense. We'll have to have rules for what happens when a new version is introduced; we have ideas, nothing firm. Commented Aug 31, 2015 at 19:54
  • 4
    We only showed off one topic page for length reasons, but we think Documentation can and should contain many different "kinds" of subjects. There's the class level stuff, sometimes method, but also "Getting Started" and "How do I set this up" and even smaller tutorials (I think multi-page tutorials probably won't work though). I don't think that's hard to convince people of, since it's so common in existing documentation. Commented Aug 31, 2015 at 19:57
  • 4
    We're OK with hosting useful content. I don't think we'll really want to encourage people designating SO as their official docs when they just start of; but we'd be OK with them acknowledging that SO docs are superior when they already exist. What matters is the end quality of documentation on the internet, not so much what (say) Facebook or Google most prefer. Commented Aug 31, 2015 at 19:59
  • RTFM is still a little rough, I could go either way. Right now I'd say "if it really is RTFM, there's probably a duplicate question with an answer that links to the docs already" so use that. I could be convinced to go the other way. Commented Aug 31, 2015 at 20:01
  • Reputation is super important, and making sure we incentivize the right thing. We've got some guesses, but they're so early and have so many known issues I don't think it's quite time to get feedback on them yet. I also want to see how the tools get used in practice. Commented Aug 31, 2015 at 20:03
  • 6
    @KevinMontrose - Good answers. I'd say that you'll have a hard time preventing smaller projects from moving their documentation to SO, or simply discontinuing their documentation site and redirecting people to SO. (I know it was my first thought for my company's documentation.)
    – JDB
    Commented Aug 31, 2015 at 20:09
  • 12
    @KevinMontrose - I'd also like to add that naysayers will always find reasons to not try something. Sometimes the best way to prove something won't work is to try it, and the best way to find the path to success is to walk down a few false starts. "Pursue something so important that even if you fail, the world is better off with you having tried."
    – JDB
    Commented Aug 31, 2015 at 21:45
  • 9
    I think one of the problems this is trying to solve first and foremost is "RTFM" "Where's the FM?"
    – BoltClock Mod
    Commented Sep 1, 2015 at 2:58
  • 5
    Regarding duplicates: it really boils down to how this ends up getting used. In some alternate future, every method that does X has a documentation page detailing its use and corresponding question that asks, "How do I do X?" that mostly just quotes (and links to!) an example from the docs. In some other alternate future, the question comes first and the docs mostly just quote the answer there. And in the grim future of Hello Kitty, there is only war.
    – Shog9
    Commented Sep 1, 2015 at 3:09
  • It's sad that the Facebook devs still can't spell "Stack Overflow". Sheesh. Commented Sep 3, 2015 at 13:44
  • 2
    @Shog9 - In the darkest timeline, Spolsky dies in a tragic stuffed unicorn accident and Atwood is driven mad by the loss of an arm. Atwood recruits Skeet to secretly lace all Stack Overflow answers with SQL Injection and XSS vulnerabilities so that they can impose reputation-based hierarchies of authority on the entire world, and the only useful part of the SO site is the regex tag (where even the insane Atwood will not dare enter).
    – JDB
    Commented Sep 3, 2015 at 14:23
  • @KevinMontrose Versions are one of the main aspect of documentation and examples. It will be great if you could integrate some tools to auto check code snippet in different versions (like 3v4l or travis-ci). With docker containers we can test language or tools in every environment we ever need
    – Mikl
    Commented Sep 9, 2015 at 23:12
  • 1
    Reusing common documentation across multiple areas (e.g. method overloads) is important. For example, Microsoft has a system for doing this to generate their MSDN documentation, and when they don't seem to use it, things can get confusing. I coincidentally bumped into an instance of this shortly after seeing the SO documentation proposal. Commented Sep 13, 2015 at 21:22
  • 2
    I would say that little projects hosted on github will definently want their documentation on SO. It is really clumsy to keep a good documentation up on github.
    – inimene
    Commented Sep 14, 2015 at 20:57
86
votes

I did contribute to some (open source) documentation, and I prefer to contribute to official documentation rather than posting some example, explanation or whatever on some third website, wiki, or forum....

  1. APIs can evolve for six months to six months, sometime with some minor changes which make your example obsolete. So if you have your own documentation, on your own website, you have to keep it up to date... Now imagine with a large number of APIs... You'll spend your life on that...

  2. Making a good example isn't so easy. Let's take a basic example: You want to show how to load a 3D model in some 3D engine. Okay fine, you have to create a camera, light... set the scene... and also to set the input, which requires a third library...

  3. If after crawling in the API, you feel like there is something missing, maybe it would be more beneficial to contact the authors than posting somewhere else. By doing that we limit one problem when you're searching on the Internet, the entropy.

  4. Closed source code (if you really can't use open source): pointing the lack of documentation to the authors is still possible and my 1) is more than ever true.

  5. you want to centralize APIs, the idea isn't bad in itself, but the fact is, ALL APIs are actually already centralized... on what people called the web. SO is right now doing something complementary of forums or mailing lists there is no structural need (my opinion) of what you are proposing, since it's already done.

  6. Almost everytime I had to contact some authors, I got some answer. I have no doubt that authors like to be contacted. Often I got some thanx when I pointed some problem/lack in the documentation. Maybe your idea can a little upset some authors and contributors (I'm not talking about my case, I always contribute for small things). Don't forget some of these people may the ones who help on SO...

Your idea sounds like to me like a wrong good idea. But I'm just debating, and I'm open to the discussion; you can convince me otherwise.

9
  • 1
    Examples could come with the API version attached they are valid for and it would always be easier to adapt them for a new version than to start from scratch. But I agree that good examples can sometimes become really large. And I also agree that the goal should be to complete the official documentation, not to build an alternative documentation. A permissive license might allow this kind of feedback. Commented Aug 31, 2015 at 16:39
  • 4
    Making a good example isn't so easy. Of course it's not easy; if it was easy it would be in the official API documentation / all over the Internet already! But the users of the software can often provide more useful examples then the developer, simply because the developer 1) has a narrower focus on the precise API syntax that he/she worked on, and 2) is affected by the knowledge the internal workings.
    – Zev Spitz
    Commented Aug 31, 2015 at 22:00
  • 4
    Let's take a basic example. This proposal is less about basic single-method examples, and more about how collections of API parts can be used together, precisely like your example.
    – Zev Spitz
    Commented Aug 31, 2015 at 22:02
  • @ZevSpitz sorry but i'm not agree. If you want to show how to load a 3D model by using some function, you have to show the model in a window, with light and stuff... Commented Sep 1, 2015 at 18:19
  • What if I just want to load a 3D model, without a burning desire to use specifically function xyz in module abc? I would also want to know all the other details as well (if not in this example then at least an easily findable linked example). Official documentation examples are often unhelpful in this respect, because it is easiest for the developers to arrange the documentation by module and function, and the example is usually tied to the specific function.
    – Zev Spitz
    Commented Sep 2, 2015 at 7:00
  • This is actually one of the things MSDN gets right in the documentation of the Office API, VBA and some other APIs (generally the Automation APIs). Documentation is often split between How do I, Concepts and Reference -- Word, VBA, WIA. (It is admittedly almost impossible to find unless you know it's there; that is something this proposal also aims to solve.)
    – Zev Spitz
    Commented Sep 2, 2015 at 7:20
  • There are some languages or tools which has no documentation (online documentation) at all (phpdbg for example). If it would be a place to make docs with large experienced devs community, it'll be great place.
    – Mikl
    Commented Sep 9, 2015 at 22:44
  • @Mikl if you make a documentation for (E.G) phpbdg, I'm sure the authors will add it to the link "documentation" of the web page you pointed. Of course, I understand that if there is no doc at all, it would be better to add some somewhere. But honestly, I don't think that the case for many common APIs to don't have any documentation. So, I'm agree with you in the case there is no doc at all, but the question/proposition here is quiet more general... Commented Sep 11, 2015 at 3:00
  • You'll spend your life on that... No you won't. The users of your project will keep the documentation up to date, not you (the developers of the project).
    – Marsh
    Commented Nov 20, 2015 at 19:25
68
votes

Contribute BACK, instead of duplicating effort (and COPYing).

In my opinion, this is largely duplicated effort.

Most of the questions here concern something which is more-or-less open source. There are very few closed source things that have an API and enough users such that we would ever achieve quality.

However, for open source projects, the documentation should at least be eventually contributed back into the original projects. This may however mean we would need different license agreements for different APIs...

I'm against duplicated effort. I'd appreciate a Wiki-like effort that could import the existing documentation similar to translation/l10n efforts, involve the community in improving it, and eventually be merged back into the original project. This may also help with handling different versions. Think of e.g. Cyanogen, which has to translate strings of their Android version to many languages.

Also, it will prevent a lot of copyright issues, if it is setup such that it can legally import the existing documentation. If you start from scratch, a lot of users will copy the existing documentation even just to change a spelling error. It's already happening all the time on SO that people copy examples from other sources which may constitute a copyright violation. It happens on Wikipedia all the time, too. Users are concerned with usefulness, not with legal issues.

7
  • 5
    Counterpoint: MSDN is enormous, sprawling, and most if not all of it is closed to comment. I think I agree with you that duplication of effort is bad, and would in general think this whole idea is silly if not for MSDN. The ideal outcome for all this in my mind would just be that Microsoft open up its docs to comments that provide useful examples, descriptions of edge-cases, etc. After that, Warlords of Documentation can go away as far as I'm concerned. Commented Sep 1, 2015 at 20:15
  • 1
    But MSDN is just a subset. Think of jQuery, Java and such. JavaDoc never allowed comments. MSDN is a single provider, so to speak. That would be a warlords of MSDN. Commented Sep 2, 2015 at 1:33
  • 1
    You're right. jQ is another example of which I was reminded reading through here, plus Java docs for the folks who work in the larger shops which still use and build Java-tools heavily. I had a decent idea for addressing the effort-duplication issue... (see my response). But the copyright issues are a much harder thing to solve (partly because the courts have not really caught up to the idea of what coders do, and just how much of what they do is the same no matter who does it – see "copyright trolls" who succeed esp. in the software realm) Commented Sep 2, 2015 at 18:16
  • 4
    I came to say this - we should be encouraging fixing the documentation itself wherever possible, instead of simply creating a new set. That way all users of the libraries/languages/frameworks benefit, not just those that use StackOverflow. Commented Sep 3, 2015 at 13:30
  • How would this work in the real world, with thousands of different platforms, documentation standards, hierarchies, etc., without everyone migrating their docs to one unified platform?
    – Pekka
    Commented Sep 4, 2015 at 22:05
  • 7
    As a dev of a major project (matplotlib) I think this is the best response. Effort that goes into SO based documentation should be directed upstream.
    – tacaswell
    Commented Sep 6, 2015 at 4:04
  • MSDN, at one point, was a lot more encouraging of community content. The typical contribution consisted of a technical support question, rather than helpful content. I'm sure the cost of moderating sealed the fate of community content on MSDN.
    – Alan McBee
    Commented Sep 16, 2015 at 19:42
57
votes

One problem touched on in a couple of other answers is that documentation needs to evolve with the language, library or tool it's documenting. Apparently obsolete answers are a pretty big problem here, and so would likely be a problem with documentation as well. One particular problem with dealing with obsolete answers, is while they may deal with older versions, many people may still be using the older version making the answer still useful.

I think that means that the new documentation feature is going to need to handle multiple versions of a topic explicitly. There can't be just be one version the Python topic for urllib, there needs to be at least one for each of Python 2.7 and Python 3.x. And no, just going with 3.x isn't really a good option, given that the 2.7 tag is more popular than the 3.x tag. On the other hand there are probably enough Python topics that would be same in all versions that completely partitioning Python documentation by version wouldn't be a good idea.

One advantage of having topics tied to specific versions (and not moving targets like Python or Python 3.x) is that they won't rot on the vine. Obsolescence becomes much less of a problem this way.

More generally I'm worried about the overall quality the documentation, I don't think there's necessarily the right expertise here to create better documentation than the web already offers.

5
  • 5
    How about a version tagging system? Topics which were correct and relevant in multiple versions of a language could be tagged with all of them. When a new version came out, all topics could be flagged as needing checking to see whether they could be tagged with the new version or not. Commented Sep 1, 2015 at 8:11
  • 6
    We have some thoughts on versioning. They're less complete than some of what's presented here (and everything presented here can still change), but the gist is "master version table for each tag, every Topic has a list of versions it applies to, within in each Topic you can further mark individual block as applying to particular versions, when a new version is released we infer [heuristic TBD] which pages get it outmagically." This will let us handle searching for versions, and let us do things like "when this version was added, what was the state of this Topic page." Commented Sep 1, 2015 at 15:28
  • 1
    I've often thought that online documentation should be like CSS, or derived classes, with a baseline set of facts as paragraphs, then a superset which is overlaid upon that superset. So the base text shows through unless it's been superseded by later information. To see older info just peel back a layer (casting?) where some of the baseline may peek through or a prior version might still overlay that. Then in SO fashion or like a wiki, in one "view" each layer gets peer reviewed, upvoted, and edited, while in a more "consumer-oriented view" the doc is just readable as any other flat text.
    – TonyG
    Commented Sep 4, 2015 at 5:09
  • 1
    Versioning: I totally agree that there should be a handy mechanism for both, see for which target version a doc is handy as well as for 'marking' the right version while providing such a snippet. This discussion here reminds me pretty much of the Postgres documentation. What I like there is that the pages of a 'topic' (e.g. SELECT) stay the same but you can easily navigate to your specific target version. With this in mind, on SO, there are many answers for Postgres query questions telling 'this example is valid for PG < 8.1, for > 8.1 better use ...'. Maybe this could be some inspiration?
    – bully
    Commented Sep 7, 2015 at 13:28
  • 1
    @KevinMontrose For me, the silver bullet for overcome versioning problem is providing the full environment specification for each code example (it can be hidden under some Env icon in the corner of code snippet block and pops up when it clicked), go further if it will be integrated with auto testing platform we can have results without time wasting (it can be hidden under some Test Result icon), for that test suite need to be done. And more, we can give full environment snapshot (system image) to instant run with one click (docker containers can do this magic)
    – Mikl
    Commented Sep 10, 2015 at 0:17
55
votes

Stack Overflow already has severe quality and maintenance problems:

  • Wrong or harmful posts do not get downvoted and remain for everyone to see and copy-paste from.
  • Posts with content problems receive comments about those problems, the comments pointing out these problems receive upvotes, the problem remains.
  • Users don't care about quality; answerers care about their reputation and askers just want to get their problem solved.
  • The majority of the userbase is not quite proficient in English.

These problems, though maybe slightly exaggerated, need to be fixed before starting yet another site.

Also, documentation (or rather, class or function documentation) is not the place for everything. You shouldn't want to explain the entire concept of a "file", or a "database", or a "socket" at the File, SqlCommand or Socket class documentation pages. There are separate resources that thoroughly handle such subjects. If users don't want to educate themselves but "just want a working socket implementation example", and this proposed site is going to cater for that, we're going to have a bad time.

As others have pointed out, writing good documentation is hard. As I try to explain above, writing it in a context comparable to Stack Overflow is, again, IMHO, impossible to get right.

Maybe without the gamification of "fake internet points" it has a chance, otherwise I can only see this as a race to the bottom.

6
  • 1
    The problems you've mentioned may be correct if you look at each of them seperated. My english isn't the best for example. But as we have a collaborative platform here we are able get the best out of it. What are your suggestions? Your post isn't very constructive. Do you like to teach all non-native speakers better english? Or do you want all non-native speakers to stop giving answers?
    – Kai
    Commented Sep 1, 2015 at 12:37
  • @user I tried to address real problems that currently exist and that will propagate to the new site if not solved. If I had the solution to those problems, I would have mentioned them.
    – CodeCaster
    Commented Sep 1, 2015 at 13:00
  • 8
    @CodeCaster I'm not sure that the problems listed would inevitably propagate to the documentation area. Certainly, the incentivisation and privilege structure for documentation needs careful thought, as does the peer review system, but given the focus and structure would be different (i.e. it's not a place for people to ask for solutions to their problems), you wouldn't have the major issue of loads of low quality questions being asked. Poor English can be edited, and I don't see that it's a huge barrier. Commented Sep 1, 2015 at 13:20
  • 2
    For some languages, libraries and tools there is no documentation at all. I would be happy to have an opportunity to make it. As for the language i think it would be great to have multilingual versions of documentation, because you can be good in coding and not good in english, and translation of good article in different language to english is much easier then write good article (it can be done by translator alone without coding experience).
    – Mikl
    Commented Sep 9, 2015 at 23:40
  • 1
    This answer seems to best outline my concerns. Extending upon your concerns regarding examples, which examples will be selected for the documentation? It seems like there will be emphasis upon examples solving common problems, degrading the quality of the documentation for obscure problems. Additionally, suppose you have one large group of people who insist upon using an outdated, probably inaccurate resource, a smaller group of people who insist upon using more up-to-date, credible resources and many in between who don't care... This already happens among the realm of academia regarding C.
    – autistic
    Commented Sep 11, 2015 at 0:11
  • I fully agree with your first 3 points. I see so many posts that have accepted answers that either are not the best answers, out-dated, or provide insecure code. I guess my main fear is with users chasing reputation and degrading the proposed documentation system simply to earn points. I have no solutions to these issues but more attention given to them could surely benefit SO and the proposed documentation system. Commented Sep 13, 2015 at 7:30
54
votes

I think this idea certainly has value, primarily in the realm of GitHub-wiki style documentation of general topics and tasks surrounding a specific library or tool. There are a few important things to consider here though.

Advantages of Official API Documentation

When it comes to language API documentation (for example, classes, method names and signatures, etc.), the proposed approach has a number of significant disadvantages when compared to existing solutions. Or rather, it lacks a number of the advantages that many existing solutions possess.

Can be generated from code

Often when I see documentation for an API in a programming language, things like method signatures, class names, and return types are pulled into the docs using an automated tool. This has a number of advantages.

Completeness

Generating API documentation automatically practically guarantees that all methods and classes are at least mentioned in documentation, even if they aren't thoroughly described.

This also has the positive side effect of making lack of documentation for a specific method highly visible, so it's clear what areas of the documentation need to be improved.

More resistant to change

Tying documentation to code means that the documentation is inherently version-specific. There are documentation available for all versions of the codebase, even intermediate revisions not part of an official release.

Additionally, documentation generated from code usually pulls descriptive text from annotated comments in the source code itself. This helps ensure the documentation stays up to date, because whenever a developer updates the code they have a clear opportunity (and responsibility) to update the documentation along with it.

Supported by the software's developers

Others have already mentioned this, but official documentation has the advantage of the ultimate experts on the system, the developers, being the ones writing it.

Advantages of the Proposed System

This proposal is not without its own merits though. Specifically...

Less friction for community contribution

Official documentation can often be difficult or impossible to contribute to. Even with open source systems, submitting a pull request isn't quite as easy as making an edit in a wiki-style system like the one you are proposing, and pull requests don't scale as well.

With closed source it's even worse, as there's often no opportunity at all for community members to contribute to the official documentation. In such a situation, this proposal could be an enormous improvement, especially if the existing documentation sucks.

Examples

I really like the idea of examples shown in this proposal. I often find that a short example helps me understand how to use a feature far quicker than any textual description ever could. So much so that I've often found myself ignoring the text and skipping straight to the written examples when skimming over documentation.

When is this system better?

The way I see it, the proposed system is better than official documentation in the following situations:

  • When dealing with topics more general than simple API documentation
  • When describing how to perform a specific task, especially where developers might be unaware of what methods to use for performing that task (there's a lot of overlap with Stack Overflow here)
  • When the the official documentation is horrible and the community can't do anything to fix them

Can we get the best of both worlds?

If the main goal of this proposal is to "improve developers' lives on the Internet" by greatly improving documentation, I wonder whether it might be possible to get the best of both worlds. Can we keep all the advantages of official documentation, while also getting the advantages of examples and frictionless community contributions?

I'm not really sure. I wonder if it might be possible to pull in auto-generated documentation from existing tools (like RDoc in the case of Ruby or Javadoc in the case of Java). Maybe Stack Overflow could expose some kind of API allowing documentation to be pulled in from an external source, and later pushed back with included community improvements? Or maybe it's better to stay away from API documentation in favor of more general topics? I don't really know. Does anyone else have any thoughts on this?

10
  • 3
    This is an interesting line of thought, because no matter what we'll be living in a world with both at launch. Commented Aug 31, 2015 at 22:58
  • 4
    @hek2mgl I don't think the response here is really so much a "no" as it is a "proceed with caution". Obviously there are some potential problems with this idea, but I don't think they're unavoidable.
    – Ajedi32
    Commented Sep 1, 2015 at 16:06
  • 4
    I really like the idea of pushing or at least having the ability to push back. Very important for being able to push back is the right license. A dual licensing (CC for keeping the content here and a license allowing pushing back) might be in order. This of course means that one in principles says goodbye to the dream of SO being the one and only documentation source. Commented Sep 1, 2015 at 19:02
  • @Ajedi32, I think there's much to be said for the tying documentation & code together, like you mentioned. I question whether you could import official docs across a variety of project documentation solutions and maintain any sort of quality.
    – xdhmoore
    Commented Sep 4, 2015 at 0:02
  • @xdhmoore That feature (if implemented) would have to be initially limited to specific languages. Kind of like how code snippets only work for JS CSS and HTML right now.
    – Ajedi32
    Commented Sep 4, 2015 at 2:46
  • I think it might be harder than that. JS, for example, has multiple documentation solutions. And some documentation solutions are customizable.
    – xdhmoore
    Commented Sep 4, 2015 at 18:18
  • 1
    @xdhmoore Yeah, sorry. By "language" I really meant "topic". Like NodeJS would have one solution, and the JS DOM might have another. That's also why I suggested that SO expose a standard API for importing/exporting documentation. That way third parties could write tools to import basically any kind of documentation into the system, making the whole idea much more flexible and scalable.
    – Ajedi32
    Commented Sep 4, 2015 at 18:40
  • If I generate my docs instead of hand-write them (which is pretty common), what happens when some major changes happen and I need to update them? Do all of the user-contributions get killed? Commented Sep 7, 2015 at 5:43
  • 1
    @Qix Not if you pull in the user contributions first. Think of the user contributions as a branch in git. That's how I'm envisioning it anyway.
    – Ajedi32
    Commented Sep 7, 2015 at 14:32
  • 1
    @Qix major changes meant that you have a new version of your app, the docs for old version, i think, should remain and both versions should be accessible, and no deletion is needed :)
    – Mikl
    Commented Sep 9, 2015 at 23:56
52
votes

I want to brainstorm from the science of motivation perspective. Why would people be willing to contribute to Stack Overflow-documentation, and how to make their experience less frustrating?

Consideration #1: There is a very popular meme that Stack Overflow community is unfriendly, the atmosphere is toxic, the questions are routinely closed by insecure and troubled people with deletionist attitudes, and moderators are authoritarian and love censorship. (For example, see this Reddit thread and the amount of sarcastic comments about duplicates).

It doesn't matter, how accurate this meme is. If Stack Overflow-documentation is anything like a wiki, there will be even more hatred and frustration. On Stack Overflow everyone writes questions and answers with their own style, their own examples, and their own opinions. On a wiki everything is supposed to be canonical, so people would constantly fight over which example is more canonical, which wording is more appropriate, there will be lots of references to more and more rules and style guides. It will be like Wikipedia. And this might provide bad incentives: wins the one who is more stubborn.

Consideration #2: Michael Snoyman published a post with thoughts why people are willing to send pull requests with documentation improvements, but not contribute to a wiki. Please read this post.

For a wiki: maintainers think they are encouraging the community to write documentation, contributors are intimidated by the wiki, because they are afraid they aren't justified in editing it, readers rightly expect incomplete, unstructured, and messy information.

For documentation that is improved through pull requests: maintainers deal with documentation in atomic fashion using tools they know, contributors don't worry about inadvertently doing harm, because their contributions are checked by the maintainers, readers know that the information is canonical, because somebody reviewed the contribution before publishing it.

Consideration #3: When you contribute to a wiki, you always feel that you are stepping on somebody's turf. It doesn't matter, if wiki maintainers explicitly encourage you to contribute, it still feels like you can break something and make someone silently irritated.

When you contribute a PR, the worst that can happen is that it would be rejected. Stack Overflow-documentation must make sure that the worst that can happen to your contribution is rejection or downvote, not silent aggravation of the community, or edit wars.

Consideration #4: There is a psychological reason why I contribute to Stack Overflow and not Wikipedia. I believe this reason boils down to:

  • Autonomy and ownership: My questions and answers are largely untouched by the community (they can be downvoted, but downvotes are less psychologically offending than somebody rewriting your words). My questions and answers are written in my own literary style, with examples of my choosing, with the idea and structure that I envisioned. On Wikipedia there's none of it.
  • Persistence: Subsequently when I write a question and answer, and they are minimally conforming to Stack Overflow rules, they are going to stay forever. It feels like I contributed to the knowledge of humanity. It feels like I did something immutable. On Wikipedia my contributions are constantly under thread of futility.
  • Atomicity: One answer means one indivisible chunk of contribution. It feels like I contribute knowledge brick by brick. My contributions feel tangible and measurable. They don't feel like opaque Sisyphean toil, where you don't know if you are actually contributing or just fighting against the wind.
  • Visualization of work and gamification: Not only do I do atomic chunks of contributions, these chunks are explicitly measured by the system. These can be simple measurements in the form of "number of answers": yesterday I had 100 answers, but today I wrote 101th, yay! These can also be scores, badges.
  • Visibility and recognition: Everybody can see that my answer was contributed by me. On Wikipedia my contribution is lost in the long list of commits on the history page. When I write answers on Stack Overflow I feel that my answers are recognized, that people see them and see that it is I, who wrote them.

Consideration #5: The following is quoted from Doing Good Better on how to find a job that maximally satisfies you, based on scientific evidence. This directly applies to motivation behind contributing to documentation. If for some reason you don't get your kicks, you won't do it. (BTW, the book is fantastic, read it now!)

Research shows that the most consistent predictor of job satisfaction is engaging work, which can be broken down into five factors (this is known in psychology as the ‘job characteristics theory’):

  1. Independence — To what extent do you have control over how you go about your work?
  2. Sense of Completion — To what extent does the job involve completing a whole piece of work, so that your contribution to the end product is easily visible, rather than being merely a small part of a much larger product?
  3. Variety — To what extent does the job require you to perform a range of different activities, using different skills and talents?
  4. Feedback from the job — How easy is it to know whether you're performing well or badly?
  5. Contribution — To what extent does your work ‘make a difference’, as defined by positive contributions to the wellbeing of other people?

As well as job satisfaction, each of these factors also correlates with motivation, productivity and commitment to your employer. Moreover, these factor are similar to those required to develop flow, the pleasurable state of being so immersed in an activity that you're completely free of distractions and lose track of time, which some psychologists have argued is the key to having genuinely satisfying experiences.

3
  • 8
    Excellent point! I've stopped contributing to Wikipedia because my carefully sourced contributions were replaced by tripe. The problem is that the tripe peddlers are legion and have plenty of time on their hands to peddle their tripe. The experts are few and usually have more fruitful things to do than wage edit war with the tripe peddlers, so the peddlers win. The editorial practices on SO are such that if an expert posts an answer, the expert can expect this answer to not be defaced by a tripe peddler, but on Wikipedia all bets are off.
    – Louis
    Commented Sep 3, 2015 at 0:45
  • 2
    Motivation is a concern. Engineers who know a topic well aren't usually inclined to write docs, and developers notoriously can't write well. So I wouldn't want the average hack writing docs. That leaves it to those with knowledge And writing skills. Why would these folks spend time documenting software here? I write a ton of docs for FOSS and commercial software, but quite often I (and my wife) ask why, when I get paid for code and consultation. I like the topic here but will always need to weigh the value of time on SO vs elsewhere. Recognition and warm fuzzies have limited attraction value.
    – TonyG
    Commented Sep 4, 2015 at 5:49
  • 1
    I often recommend to people who are trying to establish a reputation, or gain experience, that they go join active open source communities and write documentation.
    – Andy Dent
    Commented Sep 8, 2015 at 12:25
50
votes

I like the idea, even though I'm not sure if it'll work well. The general idea has been around for a long time, another place in the SE system to put content that doesn't fit into the Q&A system. To some extent this can be used for canonical answers, blog posts, tag wikis, tutorials and similar content.

One concern I have is the increased potential for plagiarism. Tag wikis already receive a lot of suggested edits that are taken verbatim from Wikipedia. I would suspect that this new feature would receive direct copies from existing documentation by users trying to gain badges or reputation. This is of course already an issue with the regular Q&A, but I fear that it might be an even bigger issue if there is an obvious place to look for content to copy, the original documentation. I'd think about ways to support the users checking suggested additions for possible plagiarism, or maybe even an automatic system for that.

Related to that is the issue of users duplicating effort where good documentation already exists. With reputation on the line, I could imagine users adapting existing information without need just to earn some reputation on SO.

The other issue is assigning reputation for collaboratively edited content. So far SE has avoided this, community wiki posts don't give out any reputation. This is a pretty hard problem, and anything I can think of has severe issues. But I assume the SE team has something in mind here, I'm curious to hear the details at some point in the future.

Another consideration is the licence, it might make sense to think about an even more permissive licence to make it easier to integrate documentation created here into the official documentation, if the project wants to do that.

2
  • 3
    With plagiarism being such a huge problem on SO, hoo boy.
    – BoltClock Mod
    Commented Sep 1, 2015 at 2:59
  • 9
    otoh, if the documentation of my tool is good enough that people plagiarize it on SO, why not set up my own account (if I don't have one already) and just port the whole documentation on block over. No more bandwidth fees, no more hosting fees. And a horde of people who want to improve on it. I'd do it. Commented Sep 2, 2015 at 10:01
47
votes

I generally agree with Stijn. There is already documentation out there for many things - some of it good, some of it bad. I think that his points need to be addressed for this to make sense.

What worries me the most is that this is a very SO-centric feature. I don't generally have a problem with this, but I do when it's eating up resources that could be devoted to improving something that would benefit every site: tag wikis. There are many suggestions to improve tag wikis out there, from improving visibility to mobile support for tag wikis to general improvements. The ability to create, maintain, search, and use tag wikis - improving a feature that already exists across the network - seems like it should take precedence over a feature that will benefit a few sites. I'm not sure all of what should be done with tag wikis - I'd like to see more attribution, more searchability, more rewards for working on them, more moderation ability (queues and such related to new tags and tag wiki updates) and maybe even the ability to create tags and tag wikis without attaching them to questions.

Since this is a network of sites, I'd like to see viable answers from other members of non-SO communities as to how they'd potentially use this on their site. I'm just having trouble coming up with good ways I'd want to use this on Programmers or the other sites that I frequent. If this is indeed an SO-centric feature that adds little value across the network, I'd like to see some kind of work on things that impact the other sites in the network as well.

9
  • 1
    I think for other sites like some of the ones under the "Technology" group (Mathematica, Blender) could use this directly. And with a bit of tweaking, even some other sites like Arqade (console commands?), ELU (grammar rules), and Seasoned Advice (measurements/terminology) could see some benefits as well.
    – ryanyuyu
    Commented Aug 31, 2015 at 16:21
  • @ryanyuyu Couldn't some of those sites also first benefit from tag wiki improvements, for example? There may be some sites who can use some form of this. I'm talking about making choices to (a) fix features everywhere that would benefit most sites or (b) design, implement, and test a brand new feature that would only benefit a smaller number of sites. There's not enough of (a) happening. Commented Aug 31, 2015 at 16:24
  • 5
    I really sympathize with the need to improve tag wikis. But I'm afraid that tag wikis have so many problems that we should at least consider alternatives. In particular, I don't think adding more features will help. At this point, it's too early to evaluate whether the documentation concept will be relevant to other sites. I think it will, but we're going to be using Stack Overflow as the guinea pig first.
    – Jon Ericson Staff
    Commented Aug 31, 2015 at 16:24
  • 5
    @JonEricson What problems do tag wikis have, other than the fact that they aren't available on mobile, they aren't searchable from the site, and they don't do a good job providing attribution to contributors? Fixing those three things would go a long way to making community contributed non-QA content so much better for everyone. Commented Aug 31, 2015 at 16:26
  • 8
    @ThomasOwens: Those are all part of the problem. I'd add that there's little incentive to update tag wikis, they are of wildly varying quality, making synonyms and deleting tags causes wikis to drop off the face of the site, there's no way to create anchors to individual sections or split them into pages, etc. and so on. Frankly, if tag wikis aren't outright broken, they are holding together with duct tape.
    – Jon Ericson Staff
    Commented Aug 31, 2015 at 16:33
  • 4
    @JonEricson Honestly, I'd be really happy if the team sat down and took a look at usage on other sites. Look at a use case on a non-SO, and even a non-tech site. Look at Gaming, Cooking, Academia, or maybe a different kind of tech site like Apple or Unix & Linux or a softer site like The Workplace or Programmers. Maybe you're right and tag wikis are broken and it's not worth fixing them. But if you're going to build a new feature, I'd like to see it thought through for everyone and not just SO so that it can not only be rolled out, but be useful to everyone on the network. Commented Aug 31, 2015 at 16:36
  • 4
    I think the other sites could actually use this more than SO. Poor documentation is better than no documentation, and we have at least poor documentation for almost everything that SO covers. But, what authoritative online resources are there for musicians or cooks? I would love to see a community authored open source cook book that lists how long to boil an egg to avoid a runny yolk, what temperature is medium rare for what meat, and other such things. Or, a musical reference with things like the difference between a time signature and a key signature.
    – gilly3
    Commented Aug 31, 2015 at 20:39
  • 2
    @gilly3 - For the cooking, there are various attempts at open-source cookbooks already available (not to mention Seasoned Advice). For the musical reference, I think you may be describing Wikipedia. Commented Aug 31, 2015 at 20:59
  • 4
    Perhaps this proposal would actually replace tag wikis, as the documentation in this format is far more flexible.
    – Zev Spitz
    Commented Aug 31, 2015 at 21:42
44
votes

Some thoughts:

The documentation sample enumerates a class's constructor overloads and their parameters. I don't think this is a good sort of thing to include, and could even be outright harmful. I think we should avoid anything that resembles standard documentation of functions, their parameters, their return types, their error conditions etc, for several reasons:

  • It will always be a less authoritative source than the official documentation. For example, imagine if the official documentation says that a method may throw a IllegalStateException in some obscure multithreaded scenario but the Stack Overflow "documentation" leaves that exception out, and a developer thus designs their code on the assumption that the method cannot fail, just who is liable when the exception occurs? Is it the developer, for trusting the popular Stack Overflow documentation? Is it the Stack Overflow contributor who documented things ever-so-nearly-completely but not fully-actually-completely? Is it the API developer, who, realizing that everyone now depends on the exception not occurring, is faced with the prospect of reimplementing the API to cater to the common usage, whatever the cost? With third-party documentation, blame is diffused and no-one in particular is responsible.

    On the other hand, official documentation is more than just an explanation of what things mean. It's a promise about how things work, a contract that the API writer makes with the API users to support a particular usage. No-one other than the API writer can make such a promise, because no-one else is responsible for writing the code that honors it. If they don't honor it at least you have someone to blame.

  • It will always be less complete than official documentation (which, even if it's auto-generated, will at least include mention of every API member, whereas rep-driven documentation writers could leave obscure things out).

  • I fear it will struggle to cope with changes between API versions.

  • Overall, I can't imagine that it will be better than the "Gets the row enumerator" style documentation it seeks to replace, although it will be better in some places and worse in others.


If there is value in user-contributed documentation, it lies in creating the examples and tutorials of real-world usage.

This could be good. I'm tentatively in favor of the experiment. However, I'm worried by the overlap with the Q&A format. I envisage a lot of argument about what belongs as a documentation topic and what should be presented as Q&A and/or tag wiki. New users will be especially confused. I've read this page several times and I'm still confused. If the line can't be drawn clearly then it's going to cause so much fuss that we should not bother with the feature, and should stick to Q&A and tag wikis.


Addendum: I'm not looking forward to the inevitable gold rush when the feature goes live. It is already the case that Stack Overflow rep is based much more on post visibility than on post effort, and a big part of visibility is being first to snipe in with an answer or question. (We all know this, and we all do it, even though we like to think our own rep scores are based on nothing but pure cleverness.) I expect that opening up an entire new section of the site will cause a new race to snag the common issues and popular topics. Speed and quantity will be rewarded with rep more than quality. It's going to be a race to grab land to plant the seeds of future rep growth, more than an altruistic collaboration to build ideal documentation.

4
  • 3
    The line is that documentation is general and questions are specific. An example I've used internally, if there is a documentation topic for adding classes to elements in jQuery with sufficient examples, and someone comes to the site and asks how to add a class to an element in jQuery, it could be closed by pointing to appropriate documentation. If the question includes the exact html of the posters use case, it is specific enough to warrant a question with a link to the relevant docs page. Almost all integration type questions are specific enough to be questions.
    – Nick Larsen Mod
    Commented Sep 1, 2015 at 1:27
  • 3
    Let's be honest: it's always the developer who is liable. Hence the common rejection of liability in EULAs...
    – Shog9
    Commented Sep 1, 2015 at 2:17
  • 2
    Re: rep gold rush. I've been working on exactly this problem. Effort is worth about as much as it actually helps people, so there is value in visibility. There are 2 clear fundamental differences in docs vs Q&A, 1) docs are broad and should typically help more people, of course yes there are still some less used tools and features to document, 2) there really should only be one topic for a thing, not 10 answers for it, so editing the existing thing needs to feel correct in this system.
    – Nick Larsen Mod
    Commented Sep 1, 2015 at 3:05
  • 2
    Because these things are so different, we're open to testing new rep systems completely, but we're holding off until we have some actual usage data from beta before we waste too much time modeling fantasies.
    – Nick Larsen Mod
    Commented Sep 1, 2015 at 3:07
34
votes

There's quite a few answers for the nay-sayers. There are answers for the yay-sayers. There's also a few answers highlighting specific doubts.

This answer is for people, who share my view:

  • Cautiously optimistic;
  • Skeptical (in the good sense);
  • Willing to give it a fair chance;

Basically this answer is for those who think the proof is in the pudding. So regardless of my skepticism, please let me have some of that pudding so I can decide whether I like it or not.

pudding Source

12
  • 11
    Sorry, but no green pudding for me.
    – Taryn StaffMod
    Commented Aug 31, 2015 at 20:30
  • 2
    @bluefeet Would blue pudding be better? The pica is licensed CC so nothing a hue filter won't fix... ;-)
    – Jeroen
    Commented Aug 31, 2015 at 20:38
  • 11
    What is that dark stripe?
    – hek2mgl
    Commented Aug 31, 2015 at 20:39
  • @hek2mgl Dunno, just picked the puddingiest pica from the puddings category on wikimedia.
    – Jeroen
    Commented Aug 31, 2015 at 20:41
  • I think they are inner shells of pistachios.
    – Buddy
    Commented Sep 2, 2015 at 15:24
  • Could also be almonds, since en.wikipedia.org/wiki/Pistachio_pudding says so. :)
    – Matt
    Commented Sep 3, 2015 at 12:28
  • 13
    Eh... what is this answer for? Commented Sep 3, 2015 at 13:45
  • You've told us who this answer is for, but you haven't told us what the answer is.
    – Caleb
    Commented Sep 8, 2015 at 4:43
  • 3
    Well, as often on meta, the question isn't immediately clear, so the answers will not be either. I think the question can be assumed to be at least one of ["How would documentation on SO help documentation, and vice versa?", "Do you think this will work?", "Will you please register for the beta?", "Do you already have some feedback?"]. I think my answer fits any of those, summarized as: I'm positive yet skeptical, I don't know if it'll work until I've tried, but I'm certainly willing to give it a try.
    – Jeroen
    Commented Sep 8, 2015 at 6:51
  • What are those "doubts" you mention?
    – Kerrek SB
    Commented Sep 15, 2015 at 9:29
  • @KerrekSB Not sure if you're asking a real question or whether that's sarcasm; there's 80+ answers, quite a few of which express 'doubts' about this idea (ranging from "this will never work" to "have you thought about such and such").
    – Jeroen
    Commented Sep 15, 2015 at 10:10
  • I agree. Seeing green pudding, I'd sniff it first. Prod it a bit to make sure it's not alive. Dip the spoon tip in it and tentatively lick it. If it isn't too bad, I'd try a mouthful - and, hey, perhaps it turns out to be surprisingly good!
    – Jongware
    Commented Nov 8, 2015 at 11:36
32
votes

I love the optimistic If a project already has awesome documentation that’s easy to search and cite, then there’s no need to duplicate it on Stack Overflow. Yeah, right.

I'm a big fan of using simple diagrams to explain things so please please include something like Doxygen's use of Graphviz, PlantUML or any textual format for diagramming. Obviously a bias towards ease of use is needed.

Versioning is probably the biggest issue and I'm glad to see the comment that you have plans to cope already. It needs to be possible to not only search by version but also to see how things change between them so a parallel viewing option would be great.

0
30
votes

First, a little background.

I have some experience on Stack Overflow. One could call that a form of documentation. But I also am the primary contributor to another form of documentation: the OpenGL Wiki. I personally transformed it over the course of years from a dumping ground/crappy FAQ into a legitimate and genuinely useful resource.

Not to toot my own horn, but I think I know a little something about documentation.

The Forms of Documentation

All forms of documentation seek to provide knowledge. But the hardest part is knowing what form you need and how to index that form.

Reference documentation

The simplest form of documentation is what I call Reference documentation. These are often derided by newbies as being "only useful if you already know the answer." However, anyone with any real experience knows the importance of reference documentation.

Reference documentation is, essentially, taking each API or basic element of something, and explaining everything you can do with it. If you look up an API function's reference documentation, it should explain what the inputs mean, what the outputs are, and most importantly what the function does.

But the newbie's perspective on reference documentation is not unreasonable. Using my field of expertise (ie: OpenGL) as an example, take the function glTextureStorage2D. That is a solid piece of documentation. It tells you what the function does. Namely, allocating storage for a texture object.

Here are just a few of the things that it doesn't tell you:

  • What's a texture object?
  • What does it mean for a texture to have "storage"?
  • What are mipmaps?
  • What are array layers?

And here's the thing. No matter how important it is to understand those concepts, reference documentation should not explain them! That is simply not its job.

The newbie perspective is not entirely wrong: you absolutely must understand the basic concepts of a system before reference docs can help you. And it is important to have such documentation, because reference docs become a lot less useful if they have to spend lots of time explaining such concepts.

The strength of reference docs are also their primary weakness: when done right, they're assuming you already know a lot about the subject matter.

Another weakness is that it often involves a lot of duplication of information. Again taking OpenGL as an example, just look at the text on glTextureStorage1D and glTextureStorage2D. They are two separate pages, but they're almost identical.

Tutorial/Example documentation

Example-focused documentation is basically someone writing out some (presumably functional) code, and then explaining how it works.

Among the other things I've done for OpenGL is write this. I used to think of it as a tutorial, but I realize that it went quite far from being a pure "tutorial". One of the things I encountered while writing that was that I was constantly having to stop and explain how various elements of some feature worked.

Here's what I mean. In Chapter 2, I introduce the ability to interpolate colors across a polygon's surface. I explain that there are three ways to perform that interpolation: smooth (the default), flat, and noperspective. But... I couldn't really talk about the difference between smooth and noperspective. Why?

Because I hadn't introduced perspective projection yet. And without that, there is no difference.

I could have introduced perspective projection earlier, perhaps. But then I would have to hold off on having any per-vertex parameters interpolated across a primitive. That significantly limits the amount of stuff you can do.

I also could have introduced perspective correct interpolation when I introduced perspective projection. However, that chapter was already gigantic, and adding a seemingly random discussion about something that wouldn't be followed up on (the genuine uses for noperspective are few and far between) hurt the overall pacing of the work. It just didn't flow very well; it always felt kinda out-of-place.

The strengths of tutorial/example-focused documentation are that it's example-focused. The user sees code that they can download and run themselves. They get to poke at it to see what happens. And so forth.

The weaknesses of it are:

  • They're generally no less impenetrable than references. Oh, there can be beginner focused tutorials/examples. But other than those, they will always assume some degree of familiarity with the subject matter. So beginners still need not apply

  • Unlike references, they're usually not comprehensive. It's hard to provide a single example that comprehensively explores a subject. I'm more-or-less an expert in OpenGL, and I could never write a single, simple example that explores everything that glTextureStorage2D does.

  • They can require a lot of boilerplate. Let's say I want to write documentation for how image load/store works. Well, I can't just do that; I have to contrive an example. I also have to create and possibly load images.

  • They often have requirements other than code. OpenGL is a huge offender here, because to do anything beyond toy examples... you need data. You need meshes. You need textures. You probably don't want to write all your shaders inline, so you need files for them too. Web applications often have database needs. So even if you write an example, how do you deliver it? How do you deal with the large number of C and C++ build tools that exist? Is it just code on a website or is it something people can run?

Concept documentation

Unlike the others, the nomenclature for this is purely mine.

Concept documentation refers to documenting, not the individual behavior of a system's APIs, but the behavior of a system's concepts. That has been my general goal with the OpenGL Wiki: each page is about different concepts of OpenGL. Indeed, the only reason I imported the reference pages into the Wiki was because filing bug reports to get references fixed was (and still is) taking way too long.

Concept documentation fills a very important gap. Unlike reference documentation, it focuses on concepts within the system. Unlike example documentation, it can explore a concept comprehensively. My goal in writing, say, the OpenGL Wiki article on Vertex Shaders is to explain everything about them. Every option is presented, either directly in text or with a link to more details.

It is also a very searchable form of documentation. Not the OpenGL Wiki, but that's more due to MediaWiki's search being crap. People tend to think in terms of concepts rather than API functions that they may not know exist. People may not be able to tell the difference between glTextureStorage2D and glTextureParameter, but they've heard the word "mipmap" before. So even just the headings and subheading will get quite a few hits in search engines, let alone the content.

Conceptual documentation is often bundled with reference documentation. In Doxygen parlance, these would be written as either Pages or Module/Group documentation. The Direct3D documentation has a reference section and a conceptual section, though the concepts tend to be more of an overview.

The weaknesses of this documentation form are:

  • It can involve a lot of text duplication, in the desire to be comprehensive. I ran into this a lot in my work on the OpenGL wiki. I try to use MediaWiki templates and other magic to reduce actual textual duplication where possible. For example, the Vertex Shader page has a section that describes the built-in inputs to the VS. But there is also a page that describes all of the built-in variables for each shader stage. Both pages are separate concepts, but share some data. So I made a sub-page and simply included it into both pages.

  • It's hard to know where to start when you want to read through concept documentation. Concepts often refer to one another, but there's no logical beginning point. I've tried several times to come up with a starting point for the OpenGL Wiki, but as you can see from the main page, the best I've been able to accomplish is a giant list of links.

  • Even if you explain everything about one concept, you still haven't necessarily explain how they all fit together. Example/tutorial documentation is better at assembling the pieces.

Learning materials

These are tools you're meant to read from beginning to end. You're expected to know more or less nothing when you start.

These are typically books, written by actual authors.

On Documentation.SO

I submit that, while each form has its flaws, every form is important. There is a time and place for each form of documentation.

But Stack Overflow is different. SO is collaborative. So, which documentation forms fit into that collaborative ideal the best?

Reference documentation

This fits quite well. Once thing about collaboration is that it has to effectively work with drive-by users. Someone who isn't really invested in helping, but maybe they have a few minutes and wants to drop something off.

Reference docs make that happen. There is very loose coupling between different reference pages, so they can get filled in quite quickly. The C++ reference site is probably an excellent example of this. 3 years ago, it was nothing. Now, it easily crushes cplusplus.com as the go-to site for standard C++.

It is also good when dealing with curation. That is, it makes it easy to accept changes, and then have those changes smoothed out by the much smaller number of primary editors of the site.

Tutorial/Example documentation

On the one hand, a person can write an entire example and document it by themselves. But on the other hand, editing someone else's examples become a problem.

You will get code style wars; mark my words. You will get people who absolutely cannot stand one particular indentation style or whatever, and they'll just go in and "fix" it. Or worse, you'll get lots of different coding styles across examples.

I think a bigger problem here though is the lack of comprehensiveness. And OpenGL makes for a good example of this.

How many OpenGL programmers can write an example of buffer object usage? Lots. How many can write an example of Image Load/Store usage? Far fewer.

Which means that you're going to get lots of examples of ways to do easy/trivial stuff, with very few examples of the harder things the API offers. You'll see plenty of examples for "my first texture", but far fewer for "projective texturing". What's worse is that you could get examples of shadow mapping without examples for projective texturing, even though projective texturing is required for many forms of shadow mapping.

I just don't think a tutorial repository is going to work collaboratively.

Concept documentation

I think this can work collaboratively. Wikipedia is a great example of concept-based documentation being created and edited collaboratively.

It also shows many of the potential pitfalls of it. Everyone wants to put their own stuff in, but nobody wants to organize it. You'll never be quite sure that it's truly comprehensive. And so forth.

Learning materials

Good God, no!

Again, leveraging my authority on the subject, I would say that building learning materials by collaboration is a doomed proposition. A good work for learning requires planning and careful consideration of what new users do not know. At the very least, a good learning work requires someone coming up with an outline.

See, the best learning books introduce ideas, then build on them more and more. With each step, they add new concepts, but they are built upon previous ones.

I structured my "tutorial" series very carefully in this regard. Or at least, I tried to. Each tutorial tried to use functionality that was introduced in the previous one, and thereby reinforce lessons learned before.

That's not something you can do collaboratively, among a group of equals. That's something that 1-3 people need to sit down and actually accomplish.

Required technology

Making good documentation in HTML is easy. Well, it's possible. Making good documentation in not-HTML... that's a bit harder. Each documentation form has its own needs as far as formatting, and not all of them are available in Markdown.

Reference documentation

Reference docs are centered around API functions. Even class-based docs like JavaDoc or Doxygen are still centered around the documentation of each function. So there must be some way of formatting function signatures.

Of course, every language has its own needs for function documentation. That's going to be a nightmare to work out in terms of formatting. DocBook makes a good show of it in its funcsynopsis type, but even that is focused on languages that look like C.

Not to mention, functions are often aggregated into classes or just conceptual groups. Not only does this need to be a part of any reference documentation scheme, it has to be able to import part of the function's documentation. This allows Doxygen/JavaDoc-style brief documentation that gives a quick summary of the function.

There has to be some facility for dealing with overloads. This is the absolute bane of Doxygen; having to find a way to document 5 functions that all have the same name, but different parameters. It wants to make them 5 separate entries, but no human being actually likes that. If Documentation.SO wants to handle reference docs, there must be a solution for this.

I guess my point is that formatting is really important for this, and not having it isn't optional.

Tutorial/Example documentation

The formatting needs here are actually quite minimal. The reason being that we already have more or less what we need: the ability to write blocks of code in a specific language.

Probably the biggest need that isn't available is some form of callouts. That is, the ability to label specific locations in a code block, and later refer to them in your text.

There's also the issue of breaking examples up. For longer examples, you will often want to present part of the example, talk about it, then present another few lines, talk about that, etc. So... how do you download the whole thing? Does there have to be code duplication, where the user writes the code into markdown and into some source file?

Concept documentation

There are fewer technology needs here, but there are still some needs.

First, as I experienced on the OpenGL wiki, inclusion is crucial. Being able to include a page in another page makes the whole thing far more legible. There are many articles on the wiki that, if you turned the inclusions off, would become a lot less easy to read. Even if you made the inclusions links, you still have to follow those links to get the whole story. Inclusion makes it easy to avoid duplication and repetition.

Also, linking needs finer granularity than "article". Section linking is crucial. At the same time, it's important to be able to turn a section into an article if it's become too big. MediaWiki's ability to make redirection pages helps here. You don't link to sections directly; instead you use redirects to go to needed sections. I imagine that they could come up with other solutions, but there does need to be some solution.

Oh, and the ability to manipulate the wiki with external tools is also important. Again, I speak from experience. I have made many "bots" for the OpenGL wiki, and the ability to rename pages alone made leaning some small bit of C# worthwhile.

Also a tool for automatically building a glossary would not go unused.

Learning materials

Who cares; we shouldn't be trying to do that anyway.

The take-home point

Documentation is hard. Specific kinds of documentation exist. Some can be built collaboratively, and others cannot. And they all have technology needs that Stack Exchange doesn't provide yet.

1
  • 3
    "There's also the issue of breaking examples up. For longer examples, you will often want to present part of the example, talk about it, then present another few lines, talk about that, etc. So... how do you download the whole thing? Does there have to be code duplication, where the user writes the code into markdown and into some source file?" -- Anybody with thoughts on how to do that, please weigh in on this tech-writing question on Writers. Commented Dec 28, 2015 at 5:03
29
votes

I completely resonate with stijn's point on fragmentation.

I can infer from the "How would adding Documentation to Stack Overflow improve Documentation?" section that this project is driven by two main goals:

  • Questions too broad for SO should be answered somewhere.
  • A community-driven documentation repository should be available to anyone, featuring what's best, filling the gap in lacking official documentation and (my take) even challenging vendors to compete by improving their own docs.

I'm omitting the rest of the points listed in the question on purpose:

  • Point 3 is about duplicate questions and providing better docs won't fix a thing in my opinion. If a user is too lazy to search, they are too lazy to search. Rewarding them with spoon-fed solutions doesn't help anyone.
  • Point 4 is very narrowly pointing out Javadocs use an ancient format. In my opinion, that works albeit ugly - in fact the ugliness helps focus on content, so Javadocs are ultimately what you make of them. But all in all, I think that's a minor point.

Conclusion

What if, instead, there was a SO tutorials site?

The idea being, instead of competing with existing documentation (bad as it may be), the contributor provides community-verified tutorials to get people started with a relatively narrow scope for each topic, whereas the requestor asks for a tutorial on a specific scope.

That would help with the broad questions as long as they have any practical scope, and could grow into a network of related tutorials by SO's aggregation algorithms.

Then again, I might have omitted something crucial...

3
  • 8
    I think a tutorials site would be a great idea, and wouldn't have to be competing with, duplicating, or fragmenting the official documentation.
    – kitti
    Commented Sep 1, 2015 at 15:27
  • 3
    Check out learnopengl hello window, it contains tutorial, documentation, example, all in one (Note: when you hover the mouse on a function it brings up a box of documentation and example). Some inspiration could be taken from that.
    – Jossi
    Commented Sep 5, 2015 at 15:07
  • 2
    A much better idea - its sure beats the "cargo cult of copy and paste" that an examples site would create that conflicts with official API documentation. This would be more geared towards understanding a product or feature as a whole before heading to the official references.
    – gbjbaanb
    Commented Sep 7, 2015 at 10:47
29
votes

I think this generally sounds like a good idea. php.net does a cut-down version of this, where there is commentary plopped in on the bottom of the documentation pages. The commentary is kind of free-flowing (and upvoted/downvoted), but the documentation is still owned by the project owner.

1) It must be opt-in, not opt-out

Some people control their own technology and documentation and don't want a community-run documentation site. Those wishes must be respected. You don't want to be like getsatisfaction.com was, a while back.

2) Handle 'ownership'

What if you deliberately choose not to document something because you're going to be phasing it out, or you know it's going to change? And then someone comes along and is 'helpful' and documents how it works today - and thus sends everyone careening towards a dead-end? Maybe you need an 'owner' who gets some kind of infinite voting reputation - maybe hook it into GitHub and let the project owners do that? "Benevolent Dictatorships" are especially common in the open source community.

3) Versions are critical

When you're documenting how something works in version x.y, it may be completely different or nonexistent in y.z.

4) Hybrid strategies?

Is there a way to let the project owner/product owner host the documentation, and then put Stack Overflow controls on/around it (A la Discourse or something like that) - but still allowing the project owner to control those changes? Will there be a way for someone to decide to 'import' their documentation back into this new thing? A way to export out?

10
  • 1
    :+1: For Hybrid strategies. Official documentation has a number of advantages that this system can't match, and it'd be great to be able to get the best of both worlds.
    – Ajedi32
    Commented Aug 31, 2015 at 20:26
  • 4
    1) opt-in/out: that's interesting and we'll have to think about it. My first thought is, do you want to opt out of people asking questions about your thing on SO? but it's not exactly the same thing. 2) I think the case you point out here is very limited in practice, if it existed and people used it, it should be documented, once better thing is here, old page should direct to new way to success 3) along the same lines as #2, 4) if a project owner blesses it, it's possible we might allow it as long as it's up the rest of our standards, export will be data dump as with the rest of the network
    – Nick Larsen Mod
    Commented Aug 31, 2015 at 20:27
  • 4
    I absolutely disagree with the opt in/ out. But the hybrid strategies is a very good idea
    – MCB
    Commented Aug 31, 2015 at 22:13
  • Long term all this stuff will be in our API, so anybody could re-host live. The trick is, an API needs to be stable... and we'll be constantly breaking things as we respond to feedback. So... eventually hybrid is a thing, no matter what; for initial launch? I'm not sure it's possible. Commented Aug 31, 2015 at 22:54
  • 2
    @NickLarsen Sometimes people find methods and classes that were intentionally left out of the documentation because they were intended for internal use or weren't guaranteed to be supported in future versions, and then suddenly when people are using them they have to be left in for backwards-compatibility (see the Windows API for an example). Are there any provisions that would allow the project owners to say "don't use this method" or "don't rely on this behavior because it's not guaranteed to remain" even before the new version is ready for release?
    – Troyen
    Commented Sep 1, 2015 at 0:58
  • Check out the history behind "getsatisfaction.com" - people could open up 'comment boards' and it looked like it was an official forum, and then they (getsatisfaction) would send emails to the project owner saying, "Hey, look at all these unanswered questions!" - it looked like extortion. If I have my crappy documentation, but that's the official documentation, I don't want your thing to make stealth documentation on top of it. That's confusing and awful. And feels, also, like "extortion." Knowing you guys, what you make will be good enough to make people switch without forcing their hand.
    – Uberbrady
    Commented Sep 1, 2015 at 1:29
  • 1
    @Troyen if something made it out in the wild for any amount of time and people used it for whatever reason then it's probably best to say something about it in the docs, but it seems totally fine to mark it as deprecated or obsolete as appropriate. There will mechanisms for those cases.
    – Nick Larsen Mod
    Commented Sep 1, 2015 at 1:35
  • 3
    I don't think 'opt in' is a good idea. Because I think the people who should be 'opting in' are also the ones that won't, simply because of the nature of the problem.
    – Sobrique
    Commented Sep 1, 2015 at 16:10
  • 6
    Here's my "nightmare scenario:" You have a project. You make a shiny documentation site for it. You try to make solid documentation. Somebody else (someone being "helpful"? Someone who dislikes your doco for some reason?) sets up a "StackUnderflow" documentation site (or whatever it's called), and puts some shoddy documentation on it. Because of SO's spectacular Google-juice, it gets ranked higher. People yell at you about your bad documentation. You don't want to use StackUnderflow. But too bad. You get a bad reputation for having shitty documentation. And none of it is your fault.
    – Uberbrady
    Commented Sep 1, 2015 at 17:56
  • @Uberbrady I kind of agree with what you said and it really makes me think point 1 and 2 would be very important. I'm trying to drive traffic to my own projects for example and might not want SO overshadowing me with their "Google-juice". Plus, personally some of my projects have "methods and classes that were intentionally left out of the documentation because they were intended for internal use or weren't guaranteed to be supported in future" and don't want to deal with "helpful" people pointing those things out. Commented Sep 13, 2015 at 7:41
28
votes

As a developer on an open source project, I have mixed feelings about this idea. I'm sure there are many places where it could be useful - some projects just don't care about documentation. But the issue is that I don't want to see documentation for our project on SO.

Our code is on GitHub, along with all of the documentation. Anyone can come along and submit an edit to the official docs, and while it might not be quite as intuitive as a platform which is designed solely for creating docs, it's not too difficult with GitHub's inline editing and ReStructuredText support. Plus, the edits get to appear in the official documentation. If that's too much for someone, or it's more of an example than actual documentation, we also have the GitHub wiki open to submissions.

I also have a decent amount of rep in the associated tag here on SO. But I won't write any docs on SO. I won't approve any submissions by users who do not have enough tag rep and need to use the suggested edits platform (because if it's worthwhile, I want that added to the official documentation instead).

The permissive CC BY-SA license would make it possible for us to directly copy the submissions on SO documentation and incorporate them in our official documentation. But that just furthers the fragmentation issue, and creates more work than if the improvements were submitted directly to our organization in the first place.

But I do agree with the sentiment. There are many times that I have turned to SO, wikis, and other resources because the official documentation for something was so sparse.

Opt Out

I think this is likely the best approach, if the documentation site takes off. Allow users with high rep in a tag to opt the tag out of the documentation site, and provide links to places to submit official documentation. Alternatively, allow someone who can prove they are with the project in question (i.e. listed on the web site, and confirmed via the email on the site) to opt the tag out. This allows projects like ours to still receive community-submitted documentation, without another site competing to do so, and maybe even find some new contributors who may not have thought about submitting the improvements directly. But it also means that organizations which do not keep the documentation up to date, and are not open to community submissions to the official docs, would get extra community coverage here.

10
  • 2
    I think this is really worth consideration. At the same time, I would be concerned about letting people connected with a project be the final point of decision on whether documentation can exist here or not. If a project stops having good/up-to-date official documentation, but the project owner won't allow it here, then it's unhelpful for developers who use that project and ultimately unhelpful for the project. Commented Sep 1, 2015 at 16:06
  • It's been pointed out elsewhere that documentation won't be for all tags, so it might not affect small projects, anyway. And maybe the state of the documentation elsewhere could be taken into consideration when it's being decided whether documentation should be switched on here for a tag? Commented Sep 1, 2015 at 16:07
  • 2
    @JoDouglass I agree with that concern. That's why I like particularly the idea of the opt out being determined by high tag rep users, as these are people who do care about SO and tend to help out here, so they're less likely to opt out for malicious (or less than honorable) reasons.
    – kitti
    Commented Sep 1, 2015 at 16:11
  • Agreed - I definitely prefer that to the project owners having the final say. For small projects - if they even qualify to have documentation switched on here - I would think that if they already have successful collaborative documentation then there's a good chance that high rep users here will already know about/contribute to/use it. It might even encourage the teams behind them to be active here so they can have a say! Commented Sep 1, 2015 at 16:24
  • 1
    Important remarks. Too few of the answers here are from the perspective of open-source developers.
    – duplode
    Commented Sep 1, 2015 at 18:45
  • It would be interesting to somehow give moderator status to project-owners.
    – xdhmoore
    Commented Sep 4, 2015 at 0:05
  • @JoDouglass - I'm amused that you and Ryan think a developer would have 'malicious' reasons to opt out here. By 'malicious' I assume you mean they won't be sufficiently humbled by SO's (ridiculous) attitudes towards information duplication and (unhealthy) obsession with rules and procedures. It's alsmost like you're aware already that directing someone to documentation that's been annotated by 500 people arguing over the wording of the first sentence might not be totally awesome.
    – Derf Skren
    Commented Sep 7, 2015 at 6:08
  • 2
    @DerfSkren Malicious was Ryan's word. My main worry is inactive projects which have opted out at some past in the past, or projects which started out well documented but have since become out of date. Whatever your complaints are about SO, I'd rather have some documentation than none. Commented Sep 7, 2015 at 7:31
  • @DerfSkren If you're that unimpressed by SO, then maybe you should find a different platform on which to rant.
    – kitti
    Commented Sep 8, 2015 at 14:47
  • @RyanP That was part of the point I was making. Searching in Google these days for programming help seems to yield nothing but StackOverflow results, many of which are simply restating (or worse simply linking to) parts of existing manuals or specs. Then there's the arguments. The point system that pays 10 credits to someone for taking "Thanks" off the end of your post. The people who claim every new post is a dupe in 10 seconds. Yes I do find SO annoying but I seem to end up here all the time. So yeah, call it a rant if you want but I for one will be extremely disappointed if SO does manuals.
    – Derf Skren
    Commented Sep 9, 2015 at 8:28
27
votes

This seems like a good opportunity for collaboration -- some developers are great at coming up with examples but have trouble with (a) paring those down to the important parts and (b) writing the explanations that ought to go with them. In this model, a less-experienced developer (who might not have written the example at all) could take examples written by others and build out better doc. That seems worth experimenting with.

This means we'll need to award rep at the section level, not just at the whole-topic level. Contributing a usable example should earn rep. Writing a good explanation should earn rep. These might be two different people.

1
  • Examples and topics will award rep separately in our current rep model. We've decided not to post it now because we'd like to see how people actually use the product before we make any crazy decisions that affect rep.
    – Nick Larsen Mod
    Commented Aug 31, 2015 at 16:27
24
votes

An issue I see with this is that while Stack Overflow Docs may become the de-facto source for documentation, it can't be the authoritative source if official documentation exists. In some cases, like actual standards documents, the documentation is correct by definition: if ISO publishes a new Technical Corrigendum to the C standard that contradicts what's written on Stack Overflow, the Stack Overflow documentation instantly become incorrect, no matter how well written.

Even if the official documentation is considered non-normative, you still potentially can end up with situations where Stack Overflow documents the way a system actually works, but contradicts the official documentation. It could well be that the official documentation is still correct and there's a bug in the system. The best course of action in such cases is to contact the author and inform them of the inconsistency so they can deal with it, not to pick one of the inconsistent options and document that. If Stack Overflow becomes the de-facto source for documentation, it may create situations in which the bug can't be removed without confusing everyone who uses the Stack Overflow documentation.

Normal Stack Overflow works fine, since we can answer questions about a specific scenario that isn't mentioned in the documentation, and then reference the document (or set of documents) that relate to the problem. It's more or less explicit that the answers are subordinate to the formal documentation.

That said, I do think there is room here to supplement the official documentation in a way that the existing Stack Overflow does not. If Stack Overflow Docs concentrates on examples of common uses (carefully edited so as to not become exhaustive to the point of uselessness), this would help address a weakness of much of the existing documentation.

Several others have mentioned tutorials; I think that would be excellent, especially if said tutorials referenced the relevant parts of the official documentation in each section. Such references, coupled with the existing voting and commenting system, could help keep the tutorials and examples listed here at a higher level of accuracy than the ones that are basically "This is what I was told when I first learned how to use it, and I never questioned it".

So in summary, I think that creating a set of well-written, reliably-accurate examples and tutorials would greatly benefit the overall level of online documentation without running into the fragmentation issues that duplicating the documentation itself, since there's a clear division of purpose: Stack Overflow Docs is an introduction; the official documentation is the reference manual.

5
  • 12
    I think MDN provides a useful example here... It's the official docs for mozilla, but not the official docs for ECMAScript, HTML, etc... Much less any platform other than Mozilla's. Yet, it is frequently the best reference for ALL of these. Wouldn't it be nice if there was such a thing for C? For Java? For SQL...?
    – Shog9
    Commented Sep 1, 2015 at 2:10
  • Mozilla can avoid a lot of the issues I mentioned by virtue of being a major implementation of those standards. An equivalent situation would be if gcc had documentation of the C dialect it implements (which it does, although in that case, it doesn't repeat the standard but rather defines the implementation-specified aspects and gcc extensions). Both are the authoritative documentation for that implementation. Hopefully they also sync up well with the documentation for the standard, since if even the docs don't agree with the standard, I'd be skeptical of the implementation itself.
    – Ray
    Commented Sep 1, 2015 at 2:45
  • 1
    A similar case would be man pages for standard libraries on Linux systems. They frequently contain GNU libc or POSIX extensions. If you're writing for those specific platforms, those man pages are authoritative. If you're developing fully portable code, the ISO docs are. Stack Overflow doesn't contain an implementation for which it can be the authoritative implementation, so all it can do is repeat information from the existing docs, possibly introducing errors or as it goes, or just getting out of date as the real specification/implementations change.
    – Ray
    Commented Sep 1, 2015 at 2:49
  • 3
    I should've provided an example; here's an arbitrary page on MDN: note that it documents the syntax and behavior, links to the standard, documents deviations from the standard for various Mozilla software, documents support for other major browsers, documents deviations from the standards for those browsers... IOW, it's a one-stop shop: if I'm using that property, I wanna read MDN even if I don't particularly care about targeting Mozilla browsers!
    – Shog9
    Commented Sep 1, 2015 at 3:00
  • 3
    The equivalent would be reading GCC's docs when using Microsoft's compiler, just because they do a better job of documenting the behavior than MSDN. That's why I say use MDN as an example here... They do it right. All documentation should be like MDN. But of course, it isn't; generally you're silly-lucky if a vendor even documents their own product well; expecting them to document how they deviate from the standard (if one exists) is heaven, expecting notes on deviations from other vendors is... What's too good for heaven?
    – Shog9
    Commented Sep 1, 2015 at 3:00
22
votes

I have a few thoughts:

Name. A lot of answers are hung up on the use of "documentation," but it seems to me that the humbler name of "wiki" fits better and will ruffle fewer feathers.

Scope. Along the same lines: to me, it looks like "topics" can cover anything worth documenting (e.g., "how to collapse matrix columns in R"), not just separate docs for each and every function ("colSums", "colMeans" and more). However, the OP can be read different ways on this point.

If it's just function documentation, it will truly be useless for R, where the per-function documentation is excellent, but the function names are all over the map, making it hard to identify the set of tools that can do the job.

Structure. I agree with @IVlad that it would be nice to have some structure. I'd suggest:

  • Language. Each language is a silo, totally split off from the others.
  • Area. Within each silo, the gold-badgers manage a small set of top-level tags that can be applied to topics. (For R: "estimation", "visualization of data", "reshaping data", "interface", etc.) Tags are voted on by gold-badgers, and are automatically deleted after accruing enough downvotes (and maybe blacklisted from re-proposal for a month).

I think (1) piggybacking on SO tags would be forcing a square peg through a round hole; and (2) any fancier hierarchical structure would just lead to scuffles, and later, apathy. Edit: Based on @KevinMontrose's comment on other programming languages (below), it sounds like even this simple hierarchy won't be possible, so we will be piggybacking. I suspect that tags designed for Q&A will not naturally extend to this new environment, though, and hope the idea of using a different structure will be revisited if this project takes off.

11
  • 2
    My only immediate positive thought relative to R was that it might be a nice place to expand on the Examples section in the existing specific R documentation pages, which can sometimes be pretty limited.
    – joran
    Commented Aug 31, 2015 at 20:06
  • 1
    For scope - we're imaging most things allowed in existing docs would also be, basically anything that can fit in a single page. Not just function/class/module level, but mini-tutorial (single page) and things like "Getting Started". Commented Aug 31, 2015 at 20:21
  • 2
    Structure is tricky, I prefer a 1-to-1 with tags (but requiring some census to create an area off of tag) because then we've got an easy way to "transfer" between Q&A. Not so much moving text around, but reputation, badges, search, and linking all have clear relationships. Language > area also breaks down around .NET (many languages, single area), Java (many languages, many areas), iOS (two languages, single area). Commented Aug 31, 2015 at 20:24
  • 1
    There are some tags I think 1-to-1 would be really bad for. Simply as an example, we have database, database-design, database-schema, data-modeling, and relational-database. There is bound to be overlap. We need a structure which ensures we don't have competing topics related to different tags, resulting in some tags being incomplete, or contradictory information between related tags. Maybe topics could be associated with multiple tags? Or both tags and the documentation area could reflect hierarchies? Commented Sep 1, 2015 at 11:55
  • (Continued from above.) For instance, if the .NET tag were set as the parent of C# and VB.NET, then going to the .NET documentation would display the topics associated with .NET itself, but with the ability to get to the C# and VB.ET specific documentation as subcategories. Going directly to the C# documentation would just take you straight to the main C# documentation page. Commented Sep 1, 2015 at 11:58
  • @JoDouglass something I could have been clearer about is that not all [tag]s will get documentation, there will be a "switch" (exact details TBD, maybe something Area 51-ish; maybe just a critical mass of Q&A). Things like [database-design] probably don't get docs, that content is better in DB-specific tags. I don't really think listing Topics is a terribly interesting feature, because there will be so many of them. Much more interesting is mining cross-links for relatedness, bubbling that up in search (and perhaps some navigation...) because the sets are much smaller. Commented Sep 1, 2015 at 15:35
  • 1
    @JoDouglass I think there's a meta-point here which is that "hierarchies are never perfect, and the way people navigate these imperfect hierarchies is through Google searches." If this is true (and I really believe it is) then burning effort on hierarchies is something of a waste; we're best going with the simple things that have immediate use. Commented Sep 1, 2015 at 15:37
  • 1
    @KevinMontrose That's fair, but I hope an open mind is kept during beta and after go-live as feedback is received. I definitely click through tree views and the like in documentation elsewhere, but maybe I wouldn't if good quality "related topics" links were available. I am still concerned about information being duplicated (and potentially inconsistent) in multiple Topics. Commented Sep 1, 2015 at 15:49
  • @KevinMontrose As far as which tags get documentation - I hope it's not ultimately related to Q&A count. As I've said in a comment elsewhere, there are quiet tags which I suspect suffer from the fact that SO doesn't look like a good source of information for that tag, so people don't sign up and ask questions about them - documentation could drive usage. There are quiet tags that suffer from a high percentage of fairly similar "newbie" type questions which it'd be great to pre-empt with documentation. Completely get focusing on high activity tags first, though. Thanks for the replies! Commented Sep 1, 2015 at 15:56
  • @JoDouglass We'll have to triangulate on the rules, since we just don't know enough believe anything we say now will last. I don't have my heart set on any particular approach, just a bunch of ideas for things that are worth exploring. A hard Q&A count does have problems though, I agree. What I'm imaging when a say "critical mass of Q&A" is some amalgamation of all Q&A activity along with a time window; so questions, answers, voting, # of users, total reputation, etc. within some period of time. Commented Sep 1, 2015 at 16:02
  • 1
    Language. Each language is a silo, totally split off from the others. I'm not sure if I agree here. What if we need to have some examples / documentation on how to wire different technologies together? Or in general for some integrational stuff. From my opinion, especially on this topic some good, well-funded examples would make sense as even with good official 'onboard' documentation for the single systems / silos, the wiring gets complicated pretty fast. Plus, this is a field where experience is very valuable. With silos, we could not benefit from that experience though SO user have it.
    – bully
    Commented Sep 7, 2015 at 16:39
21
votes

YES!

Even the best documentation I've seen so far has its limits - they are either proprietary-built and therefore lack user contributions to keep them updated, or lack a committed user base. The most notable documentation sources I can recite will be MDN or jQuery API pages, but even those documentations doesn't help programmers efficiently - That is, to land, [optionally] understand the contract, [optionally] understand the implementation, [optionally] determine if it's the right method to use, and how to use it.

Several reasons I think the new Stack Overflow Documentation feature would help with this:

  1. Narrow fields (Bungeecord Spigot, for example) which its official documentation is lacking can attract its users to SOD and therefore collaboratively build a wiki to help each other as well as the future readers.
  2. Even fields that are big can benefit as well, as linking to Stack Overflow questions from Documentation would easily cover every bit of obscure behaviour and knowledge.
  3. Usage examples demonstrates behaviour more concisely than text.
4
  • 7
    There are many more. php.net, cppreference.com, ... It's not like SO would be the first to discover that documentation could in principle be a community driven project. Commented Aug 31, 2015 at 16:36
  • 4
    "but even those documentations doesn't help programmers efficiently" -- The main purpose of documentation is being an authoritative reference on what some piece of software does. While it is a nice bonus when examples and other extra materials are effectively integrated into it, trying to cover all bases can lead to mission creep.
    – duplode
    Commented Aug 31, 2015 at 17:33
  • 3
    Please, please, don't call it SOD :)
    – mirabilos
    Commented Aug 31, 2015 at 19:38
  • 3
    @Trilarion I would not take php.net as an example of good documentation. There are a lot of bad things in it (even if by being a not bad developer you can avoid the trap) Commented Aug 31, 2015 at 19:48
19
votes

Some thoughts, mostly related to the tags I am most active in, but I think they are fairly generic.

I think the documentation format should have more structure than what is currently presented. Otherwise, it's not much better than the "Share your knowledge - Q&A style" option where you answer your own question immediately.

For example, take the tags algorithm, data-structures and any programming language. You can have algorithms in pseudocode, you can rarely fully separate the algorithm from the data structure, and then you'll also have implementations in each language.

In this case, and probably others, there should be a way to link documentations. If you read the documentation for a Binary Search Tree for example, I think you should only read about it in pseudocode initially, but have links to implementations in various languages that users have contributed. Something like "Available implementations (according to your tags / according to popularity): ... | Browse all".

So I would add more structure, not just "Examples" and "Remarks". Perhaps:

  • Topic: the topic documented, for example: "C++ iterators", "C# Lists" etc.

  • Parent topic: make the documentation hierarchical, so it reads like a book and it is easier to find stuff if you're not exactly sure about keywords. Have a table of contents. For example, "C# Lists" might have "C# Containers" as a parent topic.

  • Child topics: "C# Containers" can also talk about dictionaries, hashsets etc. This should all be displayed clearly somewhere, perhaps at the bottom, so it doesn't obscure the gist of the documentation.

  • Related topics:, or Suggested topics for you:, or both. I'm thinking something dynamic. If I'm very active in the C++ tag and I'm reading about Python lambdas, suggest that I give feedback about the C++ counterpart. If I'm only so-so active in C++, suggest that I might find the C++ documentation for lambdas useful as well. What I mentioned at the beginning about algorithms and programming languages can also go here: "BST in Python" should not be a subtopic of "BST" or of "Datastructures in Python". I would introduce entities called "Proofs of concepts", where a certain concept is demonstrated by a minimal working example. This would be separate from examples, in that you would need to provide a fully working program with the minimum requirements for running it. In an example, you would only provide snippets.

    For example, "Creating a database using Entity Framework Code First". This would be a proof of concept, and something separate. Entity framework can be talked about conceptually at first, and this linked to. Don't mix too much code with the theory: a little is fine, more can be posted in a separate place dedicated to runnable code.

  • Documentation body: I would leave this free form mostly, not everything has syntax or performance. Have guides about what should go here, but leave it a huge textbox for people to enter the actual documentation in. The good content will eventually bubble up to the surface.

  • A way for good content to bubble up. Make a staging area for people wanting to contribute to documentation. I should be able to comment on what currently exists for a topic, or even suggest something entirely new, not just edit it. What if two people come up with very good documentations, but quite different ones, for the same topic? Upvotes should decide which is the better one. I'm not sure how to approach this exactly, but maybe have some "verified" status for something that has been approved as the final form (which can still be edited, just not changed dramatically) and "Subject to change" for something that is still being debated.

4
  • 1
    Hierarchy is hard. We've found this with tags, is the appropriate hierarchy for List; Containers > List, or Enumerables > List, or Enumerables > Containers > List, or Enumerable > Writable Containers > List, or .... A flat hierarchy kills all debate. Related Topics is definitely a thing we need though; I think cross-linking can serve as an adequate substitute for hierarchy, especially if we build with search in mind (something we did a poor job of with the original SO beta). Commented Aug 31, 2015 at 22:47
  • 1
    Documentation body is, I think, just Remarks with a different name. It's free form, completely unstructured (unlike the other sections). We entirely intend for people to able to suggest new Topics; we aren't going to restrict unprivileged users just to edits, though naturally someone will have to review their submissions. We do intend for drafts of Topics (new or edited) to be sharable before submission for formal review. Commented Aug 31, 2015 at 22:51
  • Rosetta Code is a place that lists such alogoritms, even in Forth. Commented Sep 1, 2015 at 18:31
  • One of my questions is whether documentation can be done well without hierarchy. I would think the hierarchy would be very specific to each technology. And whether a community-driven environment can produce high quality, consistent hierarchies.
    – xdhmoore
    Commented Sep 4, 2015 at 0:08
19
votes

ONE FORMAT

I have a dream, I dream of ONE format, just one format across different languages...visually and meaningfully one format please.

I am tired of wasting time on differences in the format.

(Or at least we can start by including documentation on HOW TO READ specific documentation)

7
  • 7
    Humorously, when I was doing research on this I came to hate every new format I ran into for documentation. Like, 1/2 the world uses javadocs-style three frames; the other 1/2 invents weird combinations of columns and tree views. It's so frustrating moving between different documentation sources. I'm not trying to sell consistency as a win mostly because that assumes we take over a lot of documentation, which is not a given; but if we get there it's a big win for everyone. Commented Aug 31, 2015 at 22:39
  • 1
    I should add that we have considered the case where the styling is the point of the documentation, in particular for css frameworks like bootstrap. It's not cut and dry across the board, for a large part of the documentation world, consistent presentation is a huge win.
    – Nick Larsen Mod
    Commented Sep 1, 2015 at 1:39
  • @NickLarsen I totally agree about the styling but want to remark the meaningfully one format. It's a tougher task to harmonize e.g. how and where optional arguments (to a function) should be listed across Python and Java. Let's not talk about man pages...
    – Oleg
    Commented Sep 1, 2015 at 20:46
  • 7
    Beware of xkcd.com/927 though, which is where all of the previous ONE FORMAT dreams have ended up.
    – amalloy
    Commented Sep 3, 2015 at 20:09
  • @amalloy That's a good one! Well, I hope that at least we can have a reference in one place on how to read all those formats :)
    – Oleg
    Commented Sep 3, 2015 at 20:42
  • @KevinMontrose one format is a great thing. If we are about style of visual representation then it will be great to have ability to select themes (and to modify or build own themes) in profile settings. In perfection we should have the ability to change view of each language or tool documentation representation. It would be the great feature.
    – Mikl
    Commented Sep 10, 2015 at 2:46
  • @KevinMontrose on other hand, one format, if it means terminology is hardly achievable, because every language can put different meaning to the same terminology. In this case, we should be able see all the meanings of concrete word in different languages(platforms,systems,tools and etc). And more over, terminology must be the vital part the beginning of each documentation
    – Mikl
    Commented Sep 10, 2015 at 2:56

You must log in to answer this question.

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