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

17
votes

Definitely don't do some kind of mass import of APIs, and produce a parallel documentation effort to what the official efforts are. Moreover, don't do it on a different domain or subdomain...fragmenting the experience and make you feel like you've "left StackOverflow".

There is probably something that's "not that" which could succeed and get people more directly to relevant information if they're searching on an API name. But...it's "not that". It would be more like a tag wiki, where it emerges on demand for an API that is "notable" enough (as Wikipedians would say) to be able to have reasonable maintenance for quality.

The problem StackOverflow Q&A managed to address already had thriving proof that people wanted to do the thing the site was to be for. Forums existed, and people would contribute to try and help each other. It wasn't that the will to participate in Q&A was missing, they simply weren't organized (and the site that had become search-dominant for organizing was sketchy, so they were relatively easy to replace).

This effort faces a different situation: more-or-less-anonymous community-written documentation is not fun, and developers do not like doing it. There are not huddled masses yearning to write more eloquent phrasings for what an API parameter is called, just looking for a place. Many responses here have pointed out the steep cliff tag wikis already fall off of when going outside the Q&A sweet spot, and that should be (relatively) fun. This goes further and is not.

...aaand StackOverflow's core functions have not seen hardly any major feature updates for years. This despite countless feature-requests with upvotes. As others have pointed out the site is not doing well "meme-wise" for being a place where the personalities in control are trusted. So yet-another-new-site before keeping house on the main one's problems with simple proposals seems misguided to me.

1
  • 1
    "more-or-less-anonymous community-written documentation is not fun, and developers do not like doing it" And yet, there are many examples of community-written documentation that works. cppreference being one of the major ones. So I disagree with the idea that people don't want to write such documentation. I think that many people don't, but some people do and they haven't had a place for that. Also, just because a "simple proposal" gets upvotes does not mean it should be done. Commented Dec 28, 2015 at 14:28
16
votes

Beside the concerns named by others, note that documentation is always bound to a certain release version of software. If a version is released, the documentation is supposed to be available immediately with the release, meaning it is written during the development cycle, before the release. Since only the developers understand the software or a new feature before the release, usually developers are the authors of documentation, which makes sense, doesn't it?

Having this you can only duplicate or improve documentation. Duplication makes no sense; I hope this is clear. Even the license of most products wouldn't allow this. If you want to improve the documentation, you are already free to support the development teams in various ways: Some allow to comment below the documentation pages, some are wiki-style, but at least every open source software project allows submittting patches. (Which were happily appreciated, in all situations where I submitted such patches.)


Another thing. Over the years a large amount of small (or larger) blogs have created nice documentation and explanations either behind the scope of the official documentation or in order to explain features that the official documentation missed to explain properly. Or simply, with different words. I like to enter 30 to 100 blog pages a day while searching for information. That's an Internet culture which I would like to see surviving.

16
  • 2
    There's plenty of stuff that's stable but that falls through the cracks of even decent official docs. My most highly voted answer on SO (which is far from being my favorite: FGITW, anyone?) is basically documentation of something that hasn't changed in more than 15 years, and apparently it's something that a fair number of people have been looking for and haven't found in Apple's reference material. My next most highly voted answer is similar, although the comments below it are amusing in this context.
    – jscs
    Commented Aug 31, 2015 at 19:28
  • 1
    Have you tried to improve the official documentation? There were two times when I entered such a situation - an undocumented feature - when answering a question on SO. I've answered and created a bug request (both times PHP). Both bug requests had been accepted and had been fixed.
    – hek2mgl
    Commented Aug 31, 2015 at 19:34
  • It's a fair question, but the official documentation says substantially the same thing as my answer. To improve it would only be to make it more searchable, and I don't believe that I have any ability to do that as an outsider.
    – jscs
    Commented Aug 31, 2015 at 19:39
  • @JoshCaswell I don't believe that I have any ability to do that as an outsider. You can! :) Believe me, mostly such requests are highly appreciated (Add a link to your answer on SO, this makes the problem more clear).
    – hek2mgl
    Commented Aug 31, 2015 at 19:41
  • @JoshCaswell There is a feedback button on the page. I guess it is made for that purpose. ;)
    – hek2mgl
    Commented Aug 31, 2015 at 19:46
  • 2
    "I like to enter 30 to 100 blog pages a day while searching for information. That's an internet culture which I would like to see surviving." -- This wish is not just a quaint personal preference; your final paragraph makes a very important point. There are many ways one can write about software: API references, examples, tutorials, books, opinion pieces, polemics... Believing that any site can become become a satisfying one-stop shop for all information about software would be an illusion.
    – duplode
    Commented Aug 31, 2015 at 19:55
  • 1
    Apple doc improvement suggestions/requests go through their bug reporter. It's unclear to me how "you need to improve your Google juice" is a constructive, actionable suggestion.
    – jscs
    Commented Aug 31, 2015 at 20:01
  • @duplode Yes, that are my concerns too. And, thinking it to an end, I'm afraid of it.
    – hek2mgl
    Commented Aug 31, 2015 at 20:07
  • @JoshCaswell I still think it should be possible to report that issue - if you really want it. However, is a single error on a single documentation page a reason for a takeover of all technical documentation?
    – hek2mgl
    Commented Aug 31, 2015 at 20:09
  • @hek2mgl for me the reason to make such a platform for documentation, at least, is projects that has no such at all (example phpdbg and many more open source projects which have no resources for that), and general position of developers is that you can see all you need just in source code (hopefully it's open source)
    – Mikl
    Commented Sep 10, 2015 at 2:10
  • @hek2mgl If a version is released, the documentation is supposed to be available immediately with the release. It's not necessarily true, because of not all developers will suddenly update to the latest version, because they already start there projects on a stable version, and update is always can be dangerous on working projects.
    – Mikl
    Commented Sep 10, 2015 at 2:16
  • @hek2mgl Since only the developers understand the software or a new feature before the release, usually developers are the authors of documentation, which makes sense, doesn't it? Not always. If it's open source, anyone can understand, and more over, before release, there is almost always beta, and while beta you can make documentation.
    – Mikl
    Commented Sep 10, 2015 at 2:20
  • @Mikl Why do you need Stackoverflow to improve the documentation of phpdbg? I mean you can help to improve the documentation directly on phpdebug.com. Have you tried that? Have you asked krakjoe (the author) what he thinks about that? Are you even expert enough to improve the documentation? I don't take your remaining concerns seriously, sorry I can't.
    – hek2mgl
    Commented Sep 10, 2015 at 15:22
  • @hek2mgl As i have mentioned in other comment in this question, the one of the main problem which leads to lack of documentation is that it's really to much efforts it will take from me to contribute to it. This is so called high level of entrance or some sort of barrier, which stops the most part of people to contribute things whey realy can to with no pain (if it will be as easy as writing an answer or comment on SO).
    – Mikl
    Commented Sep 10, 2015 at 17:10
  • @Mikl I don't think that the entrance level of contributing to open source projects, especially their documentation, is that high. Have you tried it? If you still feel that you are not on that level already, then hey!, accept it and improve your skills. Also please note, that if you don't understand documentation, this is mostly being the case because your background isn't funded enough. You should have some patience, enlightenment needs some time. Btw, you can kindly ask about phpdbg in the PHP chat room. The author and other contributors are frequently active there.
    – hek2mgl
    Commented Sep 10, 2015 at 18:38
15
votes

I worry about the same thing as duplode does. One example that I imagine SO's documentation mirroring is "clojuredocs": it's an unofficial community-edited documentation site for clojure, but has an official-sounding domain name and is linked to often enough that new users often think it is the official documentation. Some of the examples there are okay, but mostly they are not great or well-explained. Often they are in fact wrong in some way.

I speculate that this is because the users who most urgently feel that more documentation is needed for function f are those who were trying to use f and couldn't find enough documentation. They find some mediocre documentation somewhere, cobble together something that addresses their use case, and now that they have a hazy idea of what f does, they want to contribute an example of how to use it. This is all very noble, but the problem is they don't really understand the function yet and are likely to mis-explain it or choose a bad example; meanwhile the folks who understand a function well enough to document it are mostly unaware that documentation is insufficient.

Maybe the proposed "request for topic" system avoids this, but on the whole I am concerned that poor documentation would flourish on a user-edited documentation site.

1
  • That's why examples should piggy-back on SO. A question of "how do I do this" attracts knowledgable answers. Then, you have fewer cases of well-meaning noobs writing examples. Commented Sep 2, 2015 at 6:30
14
votes

I remember how a project of mine came to an abrupt halt because of the missing documentation pages in the tools website. I struggled around for weeks trying to find out proper information regarding the tool, but I failed. In the end I had to change the whole model, and use some other tool, even though the new one fitted my project in a much better way.

My answer would be: It's a great idea. But my concern is, there are a lot of developers who are really good at writing code, but suck at producing documentation (including me). So, there might be fewer number of contributors comparatively. But all in all, it's a good idea. It's going to make the life of many developers easy.

8
  • 14
    there are a lot of developers who are really good at writing code, but suck at producing documentation I think part of the value of this feature is that the people writing the documentation don't need to be the same people writing the code.
    – David Robinson Staff
    Commented Aug 31, 2015 at 17:05
  • 8
    @DavidRobinson I was going to say: There are a lot of developers who are really good at writing documentation, but suck at writing code!
    – fredley
    Commented Aug 31, 2015 at 17:55
  • @DavidRobinson Ya, but people who write the code, would be the best candidate for writing the documentation. And, what i was pointing at, the number of contributors will not be even with the number of developers.
    – Haris
    Commented Sep 1, 2015 at 4:29
  • @TomMedley I dunno if they should be called developers or not. I may be being a little to harsh, but it is like people who write the statistics for a newly developed car model being called automobile engineer.
    – Haris
    Commented Sep 1, 2015 at 4:32
  • @haris people who write the code are also good candidates for answering questions about its use- and yet Stack Overflow has proven that others can answer those questions as well. And would you say "People who answer SO questions are not real developers, because they didn't write the programming languages they're answering about"?
    – David Robinson Staff
    Commented Sep 1, 2015 at 12:28
  • @DavidRobinson are there people answering questions about languages that they have not written code in?? o_0
    – Haris
    Commented Sep 1, 2015 at 12:43
  • 1
    @haris Not that they haven't written code in: languages that they didn't invent (Jon Skeet didn't invent C#). Similarly, people writing documentation about a library, API or package would typically be people that had used the library, possibly very extensively. Would you say that only Guido van Rossum should be allowed to answer Python questions on SO? Then why should he be the only person allowed to write documentation for it?
    – David Robinson Staff
    Commented Sep 1, 2015 at 12:46
  • 1
    @DavidRobinson Ok, i understand what you are pointing at. Definitely people will be able to write good documentation for code that is written by others. Thats true.
    – Haris
    Commented Sep 1, 2015 at 12:48
14
votes

I support the creation of an online resource like this. What I don't currently understand is how this is meant to integrate with any Stack Exchange site, especially the ones that aren't Stack Overflow. In fact, I don't understand why the proposal is to make this part of the Stack Exchange network at all, rather than some totally separate project like Discourse.

We already have blogs on every Stack Exchange site, yet most sites don't do anything with them. How do we know this feature won't also be widely underused? The fact that it's called "Documentation" implies it has no intended use cases outside of highly technical sites like Stack Overflow, so even other sites like Seasoned Advice which have an obvious potential use for it (cooking recipes) may fail to use it.

The implication that the beta is Stack Overflow-only tells me that it probably will be as underused as the blog (except on Stack Overflow). Unless this is meant to be for Stack Overflow only and never get rolled out to other sites (which isn't clear to me from this post), we should really have a non-technical site in the beta as well to prove whether or not this feature as currently designed makes sense outside of Stack Overflow.

5
  • 5
    Yeah, I get the sense that "documentation" is a bad name for what they're proposing. It could just be called a wiki with some very particular rules.
    – Frank
    Commented Aug 31, 2015 at 19:11
  • I think this is designed specifically for Stack Overflow, similar to code Snippets. It may never be activated on any other Stack Exchange sites other than the localized Stack Overflow sites.
    – Greg Bray Staff
    Commented Aug 31, 2015 at 20:30
  • 1
    I don't know... Graphic Design might want some documentation for Photoshop, Lightroom, Illustrator, In-Design, etc. It could be applicable across some sites if it's not limited to API documentation.
    – canon
    Commented Sep 2, 2015 at 15:28
  • @GregBray it can be activated on any site which needs some examples (snippets, tutorials, guides, howtos, patterns, use cases, algorithms, best practices, practical advices, tips and secrets for andvanced, overview, comparisons and test)
    – Mikl
    Commented Sep 10, 2015 at 2:30
  • I doubt this will roll out to all sites; I had the impression it would be it's own SE site - perhaps DocsOverflow? DocExchange?
    – brichins
    Commented Sep 11, 2015 at 17:06
14
votes

How to reduce fragmentation, duplication, and copyright issues:

SO-docs should be a 'tool' and not a website

Or at least more than "just a website", as that inherently raises concerns of fragmentation and duplicated effort, as others have mentioned. This stems primarily from being on a different domain/page for some part of the documentation which was created by a community, versus the official stuff, which may be good in some places (requiring no community additions) and bad in others.

How about a browser-extension to make this all a bit more seamless?

Showing supplementary docs on-page or at least linking to SO-community documentation on sites which don't natively offer editing or commenting would address the issue of fragmentation on docs such as jQuery and MSDN wherein there are no on-site tools for contributing information on the pages which need to be supplemented.

Having a way client-side to get access to additional help based off of the current URL would be a wonderful thing to have!

Contextually linking or inlining community contributions would solve fragmentation-issues

I've thought countless times that if there were some sort of a Wikipedia-for-URLs wherein discussion about a given page – its quality/validity/merits/demerits etc. – would be extremely helpful. Similar to the way that Facebook or Disqus threads can be allowed at the bottom of a page by the creators of a page, it would be an interesting endeavor to provide similar functionality and display this content as if it were a part of the site.

Obviously, we'd want to restrict the service to sites of interest, and not allow discussion of things that aren't actually docs. This could probably be done by domain with a little thought.

5
  • I think this is an interesting idea. I wonder how far you can take this. Google Translate transforms existing pages without hitting copyright issues. Will such transformed pages show up in search results? How far would we go in transforming them? Commented Sep 2, 2015 at 6:19
  • @AleksandrDubinsky SO has a good record of attracting hits through search-engines. If original page-titles are duplicated along with the right metadata, we could probably get it so that the comments/examples/revisions would show up in search-results as their own page, right above or below the original document assuming relevant search-criteria. Comments could be done as threads, atomic comments sorted by score (like SO answers or comments on PHP's docs) or for actual revisions: a git-style commit for a given page, treating the original page as the basis commit so we wouldn't have divergence. Commented Sep 2, 2015 at 18:07
  • I agree with the general idea that this idea is best pulled off as a collaboration between the existing docs sites and Stack Overflow. Possibly by means of some sort of widget or API. Or maybe the solution is the build a documentation site engine of sorts that links with SO on some level so that questions and answers linking to topics can be marked to indicate that the linked documentation has changed, but also be able to look back at it's state when the link was made. This could help avoid the duplication/fragmentation issue and still solve the problems that are proposed to be solved.
    – nbering
    Commented Sep 3, 2015 at 5:13
  • Beside mere "comments", we could have edits (changing the text of the page), links (like are used on SO), mouse-over-links/annotations, examples, and related questions on SO, all hosted around the original page. It would be a wonderful abuse of copyright. Commented Sep 5, 2015 at 17:26
  • 1
    @AleksandrDubinsky The copyright-issues would definitely need consideration... however, since having on-page annotations would reduce plagiarism, one might argue that it is a safer way to go. In most cases it should be hard to make a legal stand basically saying "Someone made a site that lets people discuss my content and I'm mad about it so they need to stop." as opposed to "Someone made a site without my permission that duplicates content I and/or my organization worked hard to create." Commented Sep 6, 2015 at 23:55
11
votes

We already have a form of documentation in the tag wikis. Now consider what problems there are with the information in tag wikis:

  • It is most often incomplete, if non-existent, and always worse than what can be found from more official sources.
  • The quality of the information is questionable. Most often it is just copy/paste from Wikipedia, until that was discouraged. So now instead, it is most often of lower quality than a copy/paste from Wikipedia.
  • The main purpose of tag wikis: to prove usage guidance, is often missing. And when it is there, it might just be the musings of a single user and not community consensus.
  • The cause of the problems is the low amount of people actually reading, let alone contributing to and proof-reading tag wikis.
  • In addition, tag wikis is often just a collection of links to the official sources.

I can easily see how this documentation project would end up with the very same problems.

In addition: if I currently need technical documentation about anything programming-related, there's Wikipedia. Why do we need Wikipedia 2?

Or if you are not making Wikipedia 2, then what are you making? A low-quality shadow of it, without any clear usage guidance or quality concerns? Wikipedia struggles with quality concerns and they have far more traffic than you can hope to achieve with this documentation system.

The only use I can see of this documentation system is that it would allow companies to move their documentation and support underneath Stack Overflow, as many companies already attempt. That may be of benefit for Stack Overflow and those companies, but it is hard to see how the site users would benefit from that.

3
  • 7
    Creation of quality tag wikis isn't incentivised by the current rep system. Nor is peer review very good. Editing doesn't bump the change in front of tag experts. Commented Sep 1, 2015 at 7:35
  • 4
    Tag wikis aren't great, but it seems odd to me to complain that because tag wikis have problems, a new system that's clearly going to work differently and looks like it would address some of those issues is doomed to failure. Tag wikis are pretty limited in scope and organisation, and aren't incentivised; the documentation suggestion seems to me to address those issues. I also don't see how this overlaps with Wikipedia, which rarely has examples as discussed here, and doesn't aim to document all features of programming languages, or cover issues like feature changes between versions. Commented Sep 1, 2015 at 10:10
  • 1
    @JoDouglass I think the comparison to tag wikis is a good one. It's an example of StackOverflow stepping outside of the Q&A sphere and giving a space on the side to write a less fleeting piece of information. The "community wiki" feature and "tag wiki" features are about making an artifact that people curate and work as a group on, which documentation is more like than it is like Q&A. So if there's anything odd, it's the oddity that StackOverflow believes users here are equipped/qualified/interested in gathering to supplant official documentation, and do so under the SO banner. I won't. Commented Sep 3, 2015 at 0:34
11
votes

Sorry, I can't comment or edit, so I have to answer ...

Someone else may have addressed this, I didn't read everything, but I read a lot and didn't see it. Just thinking, if this does come to be - and I'm generally in favor - it would be great to have a mechanism for cross pollination; e.g., I am answering a question on SO, and my answer might serve as good documentation because it includes an example. Maybe this is just automatically harvested, or maybe it would be good to have a button in the answer/comment, where a user can tag an answer as being documentation for X, just as they can upvote it or comment on it. Then, maybe it can be tied to documentation without replicating, just with linking.

11
votes

Will we have some kind of notification after the "six-to-eight weeks" ?

This post is growing and growing, and I think only a fool can keep up and read all the answers and comments on this post. I did it for a little, but then I lost all hope.

To the fool(s) who read everything, no offense meant!

I filled up the form and registered on "Register and help Make Docs Suck Less", but the only thing I received was "Your request is being submitted" or thereabouts.

Sorry for the dumb question, just to be sure, will we receive an email or a notification on Stack Overflow or something similar with the confirmation of have accessed the private beta?

10
votes

enter image description here

Image Source

To me it looks like the other half of a tasty pie.

What exists in SO is essentially the largest programming FAQ database ever compiled. What's missing is a standardised documentation platform to link it to.

It would be great if docs.SO became the platform of choice for creating documentation. The only real issue/barrier to success I can foresee is in the way ownership of content is defined.

As long as it feels publicly owned I think it will thrive, but if SE appears to take ownership of the content in some way, then developers may have cause for resentment.

What many here are missing is that a consistent UX/UI design across all documentation will increase their productivity immeasurably. Consistency is a pillar of good design, and should not be underestimated.

It's also nice to see such a huge initiative come out of nowhere. Great stuff.

9
  • 7
    We need tutorials. When you see a user ask 13 questions over the span of a week, all about tableViews, and the questions are all are duplicates about cells and reusability, you want to be able to point them to a resource that explains the basics, instead of educating someone point by point through a series of questions. Some people help by flagging and closing questions. Some people help by writing documentation. I feel less comfortable doing the first, and more comfortable doing the second.
    – user4151918
    Commented Sep 1, 2015 at 18:20
  • 3
    @PetahChristian True is (obviously since your comment is subjective), "I need tutorials". Let me add, ... because I'm not able to use Google and the Internet at all
    – hek2mgl
    Commented Sep 1, 2015 at 21:21
  • 1
    @Dom And? What kind of tutorial are you missing?
    – hek2mgl
    Commented Sep 1, 2015 at 21:29
  • @hek2mgl Water follows the path of least resistance. The easiest thing is to ask someone else to answer your question, even if you don't grasp the answer you were given. I'd rather see someone learn and grow. Tutorials might help in that regard.
    – user4151918
    Commented Sep 1, 2015 at 21:29
  • 2
    @Dom If an example explains what the code does, then it's no different than a tutorial. A new/favorite resource for me is lilbitesofcocoa because they're concise and easily digestible. When I want more details, I turn to NSHipster. Both are super examples, but one just happens to be more detailed.
    – user4151918
    Commented Sep 1, 2015 at 21:35
  • 1
    @PetahChristian Have you ever bought (or rent) a book about a topic you are about to learn? Have you ever felt that goodness to learn more than you are asking? With 100s of good examples? I mean, what you are asking for already exists, in various releases. Don't you see that?
    – hek2mgl
    Commented Sep 1, 2015 at 21:42
  • 2
    @hek2mgl Not sure why that's directed to me. I make use of many resources. But I know how and where to find help. The specific SO problem is that when someone needs help, we can't say "Here's the resource that explains that!" We have to hunt it down, then refer people to that resource. The tutorials are out there, but the problem is, they're out there. Where's the compilation of great tutorials that we should refer users to? Just because it exists, that doesn't imply it's easy to find. (I'm still looking for a great up-to-date Core Data book!)
    – user4151918
    Commented Sep 1, 2015 at 22:01
  • 1
    Hmm, the term "Core Data" was completely new to me, but it took me ~5seconds to find good tutorials. What are you complaining about? Plus (20 seconds later) I found an O'Reilly shop.oreilly.com/product/9781937785086.do .. Did you tried that?
    – hek2mgl
    Commented Sep 1, 2015 at 22:08
  • 1
    @hek2mgl you're coming across as if this a feature request and our idea that we're pushing. We're just giving our thoughts to the discussion. I don't know why you're cherry-picking hypotheticals to counter but it's not really having any impact on the bigger picture.
    – Dom
    Commented Sep 1, 2015 at 23:24
9
votes

In addition to code samples, there is a need for supplemental docs on best practices and recommended usage scenarios.

It is all to common for official documentation pages (such as, cough cough, MSDN) to provide all of the "what" without any of the "why". Extensive listings of classes, members, and required parameters are provided without critical information about intended usage or best practices/security concerns. This, in my opinion, has a heavy influence in misleading the community at large towards creating applications that are poorly designed.

A great example is the MSDN page about Application Domains. It provides a nice brief description of "what" it is, but it has no information about "why" it exists or when to use it. Incredulously, there is special disclaimer that this information should be viewed elsewhere, and the link to that information is broken.

See:

enter image description here

1
9
votes

This potentially has applications outside of Stack Overflow too.

One of the biggest sources for gaming instructions are community-written wikis, usually hosted on sites such as Wikia, etc. They are frequently terrible. Often there are multiple wikis with different information.

This could kill those sites completely.

I appreciate that this is a Stack Overflow-specific thing for now, and that's absolutely the right way to do it, but can Arqade be top of the list for sites that get it next?

1
  • I would love these fragmented wikis for video games be killed, but this would only happen if SO-documentation software would be significantly better than terrible MediaWiki. Otherwise, SO-documentation would only increase fragmentation. Commented Sep 8, 2015 at 23:38
8
votes

I really like this idea and this would be great for those obscure projects with old documentation, or minimal documentation and you basically have to read 20 source code files to figure out the purpose of an item or how to implement it.

However, for larger projects that have good decent documentation, I'd add as a requirement/feature linkbacks to the relevant items in the official documentation. I find it important that original documentation still will be the de-facto standard so we teach young coders that not everything is cut and paste. Learning to read bad documentation teaches you why to write good documentation :-)

For example:

        try {
            File file = new File(filename);

            BufferedReader in = new BufferedReader(new InputStreamReader(
                    new FileInputStream(file), "UTF8"));

            builder = (JSONObject) JSONValue.parse(in);
            in.close();
        }

This is a fun example of how to read a JSON file from org.json.simple from a file. But we have many objects here. I'd propose a regex filter on top of this, with a table that can be defined in a form that turns BufferedReader into a link pointing to the official Java documentation. And JSONObject pointing to the documentation on code.google.com

So basically you'd construct a table under your post (in YAML to allow multiple links perhaps?) with:

APIDOCLINKS:
    BufferedReader:
        java7: http://docs.oracle.com/javase/7/docs/api/java/io/BufferedReader.html
        java8: https://docs.oracle.com/javase/8/docs/api/java/io/BufferedReader.html
    JSONObject: https://code.google.com/p/json-simple/wiki/EncodingExamples#Example_1-1_-_Encode_a_JSON_object

And all toplevel elements appearing in the text will turn into links if only a link is supplied, but if there are multiple links supplied it will give a dropdown of choices when clicked which version of the documentation you wish to watch/read.

2
  • 1
    If we added a link to the original documentation on line as a searchable meta field then it would be a trivial extra for someone to code a browser add-on to pick the appropriate pages on SO-docs when someone was browsing the documentation web site. e.g. if a documentation/example has a link back to php.net/docs/some-function then a browser add on could pick up that the URL in the current browser was that URL and provide a pop-up list of SO-docs pages relevant to that function.
    – delatbabel
    Commented Sep 8, 2015 at 2:18
  • That would be a nice feature. Especially when browsing java docs, which come with the bare minimum of examples or implementation details Commented Sep 8, 2015 at 6:52
8
votes

I am surprised no one has brought up the following issue:

If the documentation gets so good on Stack Overflow, why should developers of the languages spend as much time writing good documentation of their own, or worse, updating documentation at all?

The long term goal of this proposal is that the documentation and examples written by the community will be the place everyone goes to reference a language. Is this necessarily a good thing? In order to write examples and documentation here on Stack Overflow, we need to look through the official documentation of that language. But what happens when all of PHP, for example, is covered here? Traffic to php.net/manual decreases drastically, and maybe the developers decide to leave documentation up to the Stack Overflow community. But, what happens when new versions come out? Will completed official documentation of a new release be delayed, lacking in quality, or worse just plain ignored? How will the community be expected to update documentation here on Stack Overflow in such a case?

I really do love the idea of community documentation. In many ways, I believe that is what Stack Overflow already is - to an extent. Actually creating an official grounds for this idea would be so beneficial initially, I am simply worried about the long term. As a PHP developer, even just the user comments at the end of each doc on php.net are useful, imagine an entire network of users coming together to make documentation better, for all languages.

2
  • 2
    Agreed. I rather believe in something like readthedocs.org - YES, facilitate community contributions to improve the quality of documentation. NO, don't completely outsource it to a community and centralize it, for the reasons you mention (official supplier will be less inclined to provide solid documentation), because it would often cause duplicate (and hence inconsistent) documentation, and/or would cause 'up-to-date' documentation to become fragmented. All in all, I think it's a terrible idea. Commented Sep 14, 2015 at 7:10
  • I disagree with it being a terrible idea, I think there is a middle grounds that can be found. I do agree with every other point you made though
    – samrap
    Commented Sep 14, 2015 at 16:11
7
votes

Make code samples public domain

While CC-BY-SA is a good license for documentation, please add a mention making this new site's code samples public domain (CC0).

Nearly everyone copy/pastes samples into their code and then modify them. You would not read this, say "I see!" and proceed to rewrite it without looking, introducing a few typos and bugs in the process.

By the way, copy/pasting any code sample from Stack Overflow is illegal unless your software is CC-BY-SA (which is not a good license for software). Even trivial code like this has been cited successfully in infringement cases.

7
votes

Please add equation support, preferably in the form of MathJax. It might not be needed for most Ruby documentation, for instance, but languages like R, MATLAB, Julia, etc. require equations in the documentation.

1
  • yes, please; some contributors have started to work around this via codecogs.com but it's incredibly clunky.
    – Ben Bolker
    Commented Jul 25, 2016 at 20:36
6
votes

It sounds like an amazing idea in theory, and it could save a lot people a lot of time. But like Stijn and the other skeptics, I'm not sure whether or not this will be good in terms of fragmentation.

Let's remind ourselves that Stack Overflow was explicitly created to be a Q&A site (from my knowledge), not for documentation. Another implementation is to have this as a separate Stack Exchange network (like the ones on Area 51), where it go through its own paces before becoming official.

I don't know, it could work out alright and all, and I'd love to have my doubts proven wrong in this case.

6
votes

First off, I think this is a great idea, and could really help contribute to resolving some of the points right now where we're repeatedly fielding questions which are reasonable enough but not a good fit for the site, or where the asker needs to gain some basic knowledge of a topic. This could help cut down on the clutter that many people are concerned about, and give a very quick place to link to when people comment on/flag/vote to close some questions. I think this is the best of both worlds, because people would be helped - but in a way which encourages self-learning - and at the same time the overall quality of the question/answer part of the site would be improved.

A couple of potential ideas which either I haven't seen in answers so far, or have seen but have other thoughts on:

Flagging functionality for various tasks which need doing

This fits in with some of my other suggestions, so read everything to get a full picture of this.

I think it would be useful if various tasks needed on topics could be flagged up in the system. In some cases this would be manual (i.e. someone notices an issue with a topic, and flags it up), and in others it would be automatic (i.e. situation X occurs, and the system has rules set up to mean that in this situation, a set of topics needs flag Y setting). Once someone took the necessary action and their changes had been reviewed/approved/whatever, the flag would be removed.

Is it official?

If the creators of something we have documented here want to consider the SO documentation as their official documentation, it'd be great if we could have something which displayed which documentation was "official" and which was not. I don't know whether this would be something you'd decide on at a language level (i.e. it's all official or it's all not), or at a topic level (i.e. a language's creators would have some sort of review capability topic-by-topic where they could certify that each topic was still correct). If the latter, the flagging functionality discussed above could be used to flag topics which needed to be reviewed by the language's creators.

Version tagging

I know the issue has been partially covered in a few places, but I'd like to see version tagging - i.e. each topic can be flagged with multiple versions of a language, so we don't need to rewrite documentation for features which are identical between different versions. When a new version of a language is added, the flagging system above could be used to flag each topic to say it needs checking against the new version, and then as people went through and confirmed whether each topic worked with the new version, those flags would be cleared.

Where people confirm that a topic is not the same in the new version, a flag could be created to make a topic discussing that feature in the new version, if suitable. That could be manual, to avoid unnecessary flags requesting topics for obsolete features - i.e. a person responds to a flag saying a topic needs checking against a new version. They find the feature is different in the new version, so they check a box saying a new topic is needed, and save. This clears the "new version" flag and adds a "topic needed" flag which lets people know a topic mirroring topic X but for the new version is needed.

Copyright issues

I don't know the full ins and outs of this issue, but have seen it raised repeatedly as a concern. Could it be worth flagging up content for specific copyright reviews, where people are asked to check the new/modified content, do a search for anything similar, and then remove or cite (as suitable) any content which has been copied? If so, would everything be flagged after modification, or might it be possible for a system to be added which does automatic plagiarism detection, then only flags those topics which problems have been found?

Related questions and related documentation

It would be good to see links from both parts of the site pointing to related information in the other. Much like we have "related questions" when we're looking at questions now, I'd like to see links to "related questions" when viewing documentation topics, and "related documentation topics" when viewing questions.

Dealing with related tags

A couple of discussions have come up about how to relate the documentation area back to the Q&A area. We seem to be at least starting out with this based on tags - but many tags are related to one another. 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.

The two thoughts I've had on this are either allowing topics to be associated with multiple tags, or associating documentation areas on a one-to-one basis with tags, but setting up tag hierarchies.

A simple example for the tag hierarchy idea: If the .NET tag were set as the parent of C# and VB.NET, then going to the .NET tag's documentation would display the topics associated with .NET itself, and show a list of subcategories in documentation - C# and VB.NET would be listed. Going directly to the C# documentation would just take you straight to the main C# documentation page. There should be something to indicate in the C# documentation area that it's possible to go up a level to .NET, also.

(Please note, these are just two pretty rough ideas on the tag/hierarchy point - this is a complex issue, and these are pretty much just starters. I'd love to see some more thinking through of the design on this point so we don't get stuck with something that's difficult to navigate or results in poor quality documentation.)


Those suggestions given, I have one concern so far that I haven't seen mentioned:

Low activity tags

I spend most of my time on low-activity tags. I've seen people mentioning ideas where people with gold badges in a tag would have more documentation privileges for that tag. For low-activity tags this would be a killer; there may well not be enough (or any!) active gold badge holders. Please keep this in mind when figuring out how privileges will work.

3
  • That's an interesting idea about nesting tags; I hope something along those lines is feasible, but really don't know enough about the broad world of programming languages to judge. Regarding low-activity tags, I would suggest that they not enter docs.SO unless they become high-activity. Like CodeCaster, I think quality is a real concern, so opening this up broadly is a bad idea. And also, we don't need so many editors (or voters) in docs, I think.
    – Frank
    Commented Sep 1, 2015 at 12:56
  • 1
    @Frank As far as nested tags, thanks - it's only a rough idea, but the relationship between tags/documentation areas is an issue that deserves attention if we want this documentation to be high quality and easy to navigate. I think working through a few examples of related tags would reveal where there are problems with my suggestion and any others that have been made, and lead to a stronger eventual design. Commented Sep 1, 2015 at 13:06
  • 1
    @Frank And as for low activity tags, I do think it would be a real shame if that happened. I can completely understand focusing on the high activity areas first, but I think in some cases the low activity areas suffer for the quality of information available. If people don't see SO as a good destination for that type of information, they may not ask their questions on SO. Some tags could desperately use some documentation covering basic topics that get asked about repeatedly. Commented Sep 1, 2015 at 13:12
6
votes

For me the missing part of documentation is always quality examples, and those need regular software development practices and tools, so I can't imagine that without using a DVCS and a local copy in an IDE.

So, for me a perfect universal third-party documentation resource would feature documentation browsing capabilities coupled with a DVCS management solution for code examples similar to GitHub or GitLab and a CI build environment combined together to demonstrate the runtime outputs of the test cases.

Such an framework would facilitate existing VCS and IDE skills as well as development practices, using SO-Documentation-Examples as some kind of an issue tracker.

A Git repository would resemble a large topic or a top level namespace in a class hierarchy.

An answer to a problem in code examples would require a pull request in a test suite or a demo project, which then could be merged to the body of reviewed examples, if supported by enough votes in the QA part.

With a DVCS working copy an implementor would be able to work in an environment of choice without the need to move back and forth between the IDE, numerous xFiddle and xPad environments and Stack Overflow itself with enormous amount of snippet copy-paste operations to provide a quality piece of code.

Many problems require cloning a known opensource project from GitHub just to browse for the snippets of code and tests for example usages of some library so the SO-Documentation-Examples with DVCS-based examples would probably serve that purpose better.

5
  • Interesting proposal. I'm not actually sure this is a good idea. I mean, to have full, compilable projects that have a lot more code than necessary for the given question. I'm thinking examples of how to use a Java Spring Framework annotation. It would take a web app project to run, or perhaps a stand-alone project (even though that's not a common use of Spring). Just to show how one annotation works. And it gets worse if we try to cram multiple examples into a single compilable project. Perhaps these sample projects could be an extra, or a part of a tutorial. Commented Sep 2, 2015 at 6:25
  • 1
    @AleksandrDubinsky The main concern of having just a code snippet is that it needs to be copy-pasted from some other environment, where you have actually set up a solution already at least to compile and get some program output. If this job is already done, why bother copy-pasting, when you can just push a changeset? And, when it's done, how to keep it in sync and accurate? Commented Sep 2, 2015 at 7:51
  • That's a good point. But we must have short to-the-point examples, How about this: a markup syntax inside comments to cut up a compilable, unit-tested project into individual examples. Commented Sep 5, 2015 at 17:03
  • Very good idea, in addition we can use VM or containers (like docker) to save the full environment of script it needed to run, and problem with many versions of language and libs can be solved this way. Each container for each version, and more over for different platforms and dependency builds. We can have working example fully functional out of the box just in few clicks.
    – Mikl
    Commented Sep 10, 2015 at 3:46
  • @AleksandrDubinsky I think, examples can be of different sort (snippets, tutorials, guides, howtos, patterns, use cases, algorithms, best practices, practical advices, tips and tricks, secrets for advanced, concept, technique, tools, overview, comparisons and test). And all of this examples types are glad to be structured and easily found. Without an active community it's unachievable. I think, SO is the best place for it to happen.
    – Mikl
    Commented Sep 10, 2015 at 3:55
6
votes

As far as examples, I think it should be more of a task of curation than generating new content. I don't think it makes sense for a contributor to open a topic page and start writing, "well you can do this, and then you can do that." The question-answer format is superior for a few reasons:

  • Concrete questions yield relevant examples.
  • Users suggest alternate ways of writing something, and the best way is voted (or at least the best way, which was added long after the question was asked and has no hope of getting enough votes, is somewhere on the page).
  • A feeling that you're participating in a discussion with people.

I would like to flag good questions as something that belong as an example, and the link between SO question and doc example would be two-way. The place to propose new examples would be in the question, and the doc topic would host the example(s) chosen by the community.

1
  • I agree. I'm not even sure that people will use documentation so much as just keep asking questions and answers anyway. I'd also be worried about the proposed "Topic" layout of documentation leading to a lot of duplicate or over-lapping topics, the same way questions are now.
    – nbering
    Commented Sep 3, 2015 at 5:18
6
votes

Rather than community written docs to supplement official docs, what if the docs are more like 'how-to guides', examples of how to use/write code using a specific language feature/api. I think is a specific example of what format the documentation could take?

6
votes

There is a difference between

What all can a [class] of [language] on [platform] do?

and

How to do [something simple] using [class] in [language] on [platform]?

The second scheme is why Stack Overflow is sought for, famous for. The difference is not big, just the way information is looked up these days.

So rather than try to repeat The Docs ™ (top down, packages, classes, methods) shouldn't the effort be focused on the reverse linking and transforming ? The "how" part ? The answers are already there.

Documentation will emerge automatically. Dynamic, updated, curated, reviewed, commented, admired and hated.

Java -> nio -> Path -> getAbsolute() -> is ?
> The Answer // one of the answers, not a classic documentation page
> Answers    // Stack Overflow has many of these

Stack Overflow should do one thing it already does: provide answers.

I'm not opposing developer documentation on Stack Overflow (it'd be great), but I think the way they are to be created, can be what will make Stack Overflow different from traditional documentation sites.

5
votes

The proposal could be improved by adding a section for How To or Step-by-Step in addition to Examples.

I write tutorials for an open source project. Tutorials are valuable because they show how to implement something from start to finish. Good tutorials provide context, like a recipe, showing what ingredients are needed and a procedure for combining the ingredients (sequence or order is often important). As it stands, the proposal doesn't offer the structure needed for a tutorial.

You've called this a proposal for Documentation. And you've duplicated the structure of the formal documentation that is often written for a programming language or API. But the problem with language or API documentation is granularity. You can read the documentation for a method call and see the syntax and all its permutations without learning how to use it. Examples aren't enough because they don't provide context. What has to happen before the method is called? And what result should you expect? This is why people turn to tutorials.

You may argue that providing a platform to write tutorials is out of scope, too ambitious, or duplicates the effort of every blog writer on the Net. But the value of SO is to provide a popular destination with a consistent and well-thought-out structure for Q&A and this could be true for tutorials as well.

All you need to add, to begin providing the benefits of tutorials, is a section for How To or Step-by-Step in addition to Examples.

4
  • 4
    Consistent and maintained by the community? I don't really think that's possible, what with the variety of approaches people have to pedagogy. We'd just see a proliferation of tutorials from different perspectives, none maintained by anyone.
    – Frank
    Commented Aug 31, 2015 at 21:17
  • This isn't ideal. Each developer would follow their own methodologies. So maintaining tutorials would be too difficult Commented Sep 4, 2015 at 7:19
  • How to and step-by-step are really just aliases for Examples. Commented Sep 4, 2015 at 14:34
  • Great answer, totally agree. I think, examples can be of different sort (snippets, tutorials, guides, howtos, recipes, patterns, use cases, algorithms, best practices, practical advices, tips and tricks, secrets for advanced, concept, technique, tools, overview, comparisons and test). And all of this examples types are glad to be structured and easily found. Without an active community it's unachievable. I think, SO is the best place for it to happen. I wish it would be a big base of code snippets for all tasks i can imagine in all environments and languages.
    – Mikl
    Commented Sep 10, 2015 at 4:33
5
votes

As a fresh developer, I am seriously excited about this crusade. The idea of peer-reviewed examples and openly edited documentation can solve so many problems for existing and future developers. Think about all the people who would now gladly and efficiently go read the manual.

Seeing how platforms like Wikipedia, with enough community participation, can become actual reliable sources of useful information, I am convinced SO can do the same to documentation.

This seriously has to be the next big thing in programming.

5
  • 3
    I'm having trouble understanding why this post is so negatively received. Commented Sep 3, 2015 at 7:35
  • While I didn't downvote it, I guess those who did objected to the language. "Crusade" suggests an impious enemy. While it isn't truly offensive to half-jokingly say that SO was created to fight an enemy, who would be the enemy here? The evil, feckless open-source developers who write terrible documentation? And "the next big thing in programming" sounds too much like empty marketese.
    – duplode
    Commented Sep 3, 2015 at 15:05
  • 1
    @duplode Well I guess maybe as a less experienced developer, I am way more excited about this than the sceptics. The "crusade" part I thought about editing, but the reason I put it there in the first place is because of the title of the post: "Warlords of Documentation". Anyways, thanks for the input. :) Commented Sep 3, 2015 at 23:01
  • 2
    "the reason I put it there in the first place is because of the title of the post" -- I see. It makes much more sense now, though it does remind me of the old adage saying that humour doesn't always translate well over the Internet. It is often true, unfortunately, but keeping po-faced all the time would be even more unfortunate :)
    – duplode
    Commented Sep 4, 2015 at 4:45
  • @AdamJensen: This is basically a verbal upvote for the question; either downvoters disagree that the proposal is good, and thus disagree with your answer, or they don't think that your answer really adds anything to the discussion, since there's not much argument put forth.
    – jscs
    Commented Sep 6, 2015 at 18:16
5
votes

Another way that having all the documentation in one place could be beneficial would be cross referencing languages' API for people learning their Nth language.

For example, coming from Ruby to Objective-C dealing with strings took longer than it should simply because I didn't believe what was required when I found the documentation.

So you could have a direct link from Ruby's string manipulation page to Objective-C's string manipulation page, and vice versa; or iterating over an array in Python to Ruby's enumerables, and Swift's, and JavaScript...

And if you included basic/ common algorithms people wouldn't have to try to guess if it's implemented (i.e. Ruby's each, or Swift's for x in y), and what it's called in that language. And since the user will likely be familiar with their native language's documentation it will be trivial for them to find what they want to do, and then follow the link to how that's done in the new language.

I had an idea for doing this myself for a while. But since you're taking this on anyway implementing simple many-to-many relationships would be a simple addition.

4
  • Brilliant! We need standard examples (eg, how to write an array to a file) that can be collated between languages/libraries into a single "crash course" page. Of course, while some standard examples are easy to define for languages, two domain-specific libraries will need to agree on some domain-specific examples to have in common. Commented Sep 2, 2015 at 6:27
  • 3
    This sounds pretty much identical to Rosetta Code. Commented Sep 2, 2015 at 7:51
  • @PeterTaylor I hadn't seen it, but yes it does seem very similar. And I'll probably use it moving forward. However the organization, presentation leave a lot to be desired.
    – MCB
    Commented Sep 2, 2015 at 13:47
  • @PeterTaylor , Tasks in RosettaCode are much more complex when simple examples of language API usage. However, it can be used to find different implementations of the same task (algorithm). All the difference can be in the way of how you achieve the needed information. Cross-linked references of many languages is very good idea for me.
    – Mikl
    Commented Sep 9, 2015 at 19:51
5
votes

Special attention need to be paid to versions of APIs in this or it's going to get really confusing fast.

It needs to be split into a language-name/language-version/api-name/api-version/package/ split along with tags to make it easy to find things related to various topics.

Also it would probably be nice for each user to be able to create a "project" of sorts, and then include only the documentation related to that particular project within that space, so as not to have to include the full brunt of all the things related to the documentation, but to be able to choose when browsing that documentation, the documentation which relates to that particular project, if that makes any sense. I do this already using Tiddlywiki when I'm learning something new, and I only need some parts of the functionality of a library for my project, and not all of it.

5
votes

Since I didn't see this mentioned yet: couldn't this be a job better handled by a search engine? There were a number of people talking about fragmentation. The documentation doesn't have to exist in one place for it to be aggregated in one place.

Couldn't you propose / promote a microformat, and urge search engines to surface that format in search results? Or create a JSON index format, and allow people to integrate their documentation into any documentation aggregator, not just SO? I think the original post makes the assumption that SO would end up being the best place to aggregate. That may actually be true, I'm not sure, but why make it the ONLY place to aggregate / add corrections? Walled gardens are necessary sometimes, but I don't see why they'd be necessary for searchable / indexable text documents.

5
votes

Instead of creating documentation, can we leverage the SO database? this requires new flags or some sort of nomination that proposes a thread for either great example and/or great explanation. Nominated threads would go to a process that cleans them up (for example, removing comments and problem specifics) so that what is left is a description of problem (with test data if appropriate) and solution. Some additional tags may be added for searching. These answers are then stored and receive priority in the 'have you looked at these answers' when writing a question, and can be passed on to the documentation teams for the underlying product.

1
  • This definitely seems like the way to go. In fact, the site has already tended this way with the better tag wikis (see scala for example.) Commented Sep 8, 2015 at 4:15
5
votes

This feature is fundamentally true to the nature of the site and its users. It provides a platform for truly high-quality, peer-reviewed information on the tools that programmers love.

I feel like this is what a lot of users have always wanted Stack Overflow to be. Great documentation has no duplicates, it has no useless information, and the information is correct and helpful. It sounds like what those users expect of questions and answers on the site, and often work hard towards.

The problem has always been that Stack Overflow continues to grow rapidly, but the number of concerned users doesn't grow nearly as fast. Quality control on the Q&A site is analogous to attempting to stop the tides of an ocean. You can't stop oceans from making waves.

I like this idea, because I think it gives users a more effective place to enforce that standard of quality. There will still be plenty of users to enforce quality on the Q&A site, and certainly most users will frequent both parts of the site. But maybe this will be a chance to reevaluate what we expect of the Q&A site and how we want to let that part of the site grow differently than it has thus far.

5
votes

This is not an answer, really, but something documentation-related that I'd like to get off my chest.

In many areas, documentation has gotten WORSE over the years. Whereas 20 years ago, technical writers would be hired to write well-organized manuals, that expense is largely foregone these days.

What I've noticed recently is that with the increasing use of technologies like Bootstrap et al., which are designed to enable a single code base for content that can be displayed on a large monitor or a smartphone, there is a strong tendency to privilege the smartphone at the expense of the large monitor. If it can't be read easily on a smartphone ... does it really need to exist? Imagine a "twitterized" Stack Overflow!

This leads to content that looks great on a smartphone and also "looks great" on the large monitor EXCEPT for the fact that on the large monitor there is less information shown in REALLY BIG FONTS. "Documentation" often lacks the necessary information density to do the job. Imagine trying to read a GOOD javadoc on a Smartphone (or to code on one, for that matter).

This is another point that needs to be considered by anyone proposing to create a repository of documentation.

You must log in to answer this question.

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