24

The selling point of Documentation, and what made it so attractive and sexy was this:

Documentation will complement documentation where it falls through

I'm unsure where I read it, there's another quote that is more recent:

Docs is intended to solve the problem of bad documentation for various frameworks out there.

The important part here is that that was practically the only motivation (if anyone has tried reading MSDN some years ago, here's another victim) I had. BUT! There are documentation that is just that good, that anything more just spoils it. I'm unsure how to signalize that. Is there a way we can just redirect people that lands on certain topics to those documentation?

12
  • Linking helps for some part, but search could include direct MDN docs also (in the case of CSS/HTML) or whatever the main docs for the specific tag is. As, when you search docs [in general], you typically want to find both types of things, depending on your search query.
    – bwoebi
    Commented Jul 26, 2016 at 17:02
  • @bwoebi supposedly, docs traffic should come from Google mainly... I think MDN ranks high enough
    – Braiam
    Commented Jul 26, 2016 at 17:13
  • MDN ranks high, but not higher than W3Schools. Not much SO can do about that though...
    – ivarni
    Commented Jul 26, 2016 at 17:26
  • @ivarni totally anecdotal, but the order is normally MDN, W3Schools.
    – Braiam
    Commented Jul 26, 2016 at 17:28
  • 1
    Not sure that redirect is appropriate. HTML tag and MDN docs however are great example right now of people trying to insert topics and examples that attempt to duplicate MDN but come across as lesser quality if not just for consistency of formatting and organization but also MDN cross references to specifications. It's still not clear if this sort of practice that was started in Private Beta should continue or not. If not, how to educate people ?
    – charlietfl
    Commented Jul 26, 2016 at 17:30
  • 2
    @Braiam Lucky you :) I have to add "mdn" to all my google searchs and I'm not allowed to install the Chrome-extension that blocks W3S (or any extension for that matter), but yeah. It was a bit of a derailment. Back on topic, I agree. It would be good if we could just redirect to existing documentation that is already good enough. In the Javascript topic I've seen lots of docs that are way worse than their MDN counterparts and even if they weren't worse they'd still only contribute to increasing fragmentation instead of reducing it.
    – ivarni
    Commented Jul 26, 2016 at 17:31
  • And if the link ends up not being good enough, we should be able to flag it just like examples to pinpoint what needs to be fixed. This would make it easier to accomplish the goal of "fill gaps, don't copy".
    – davidism
    Commented Jul 26, 2016 at 18:33
  • I think css-tricks.com is an example of what documentation should be.
    – tbodt
    Commented Jul 26, 2016 at 20:06
  • 1
    @tbodt Except updated every once in a blue moon, too. ;-)
    – TylerH
    Commented Jul 26, 2016 at 21:04
  • 1
    This could backfire. I can totally imagine masses starting to spread w3schools links across the whole docs.so, and getting negligiently approved. Commented Jul 27, 2016 at 5:42
  • 2
    @JanDvorak we can always ban w3schools links network wide ;)
    – Braiam
    Commented Jul 27, 2016 at 6:00
  • @Braiam doit! doit! doit! Commented Jul 27, 2016 at 6:03

2 Answers 2

5

Being as it is my first post, I wanted to take the opportunity to introduce myself. I am Vasudha, the new product manager for SO Documentation. Am super thrilled to be here and I can’t wait to work with all of you to get Documentation to the right place!

The question you raise is a good one and one that we have been talking about on the team as well. We recently went through an extensive round of user research where we interviewed both users (with different levels of activity on Docs) and non-users of the product. A bunch of patterns emerged and we identified the top barriers and motivations to the use of Documentation. As part of that, the need for features that enable better attributing, linking and referencing of existing documentation, came to light. While SO Docs is example focused, and aims to provide users with more ways to apply the said topic; providing context, definition and enough information to make the topic clear and complete is a must.

The lack of such attribution tools have manifested in other ways - one of them being plagiarism, since some of our users that really like the content on a different site, choose to paste it onto SO.

We have also seen some good ways our community has gotten around this hurdle -

  1. enter image description here

  2. enter image description here

  3. enter image description here

Until we make attribution and linking officially available within the product, I’d be a proponent of the above approach.

Without a doubt, we still stand true to what Kevin Montrose mentioned in our first post to the community about Docs -

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.

We realize we need to make it easy for the community to be easily able to point to such references. And that’s exactly what we intend to do!

3
  • 3
    "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." there should be almost nothing about JavaScript on Docs.SO then. What are we supposed to do about the largely substandard content that many users have "worked" to build on Docs.SO?
    – user4639281
    Commented Apr 10, 2017 at 20:10
  • @TinyGiant: Having some way to call out links to official (or just better) outside documentation ought to help with both of those problems. It'll help folks avoid duplicating the content of other documentation and make it more clear that existing SO Documentation is not as good as what's available elsewhere. Highlighting quality external documentation in the software ought to help avoid unnecessary duplication (and plagiarism) while also helping editors fix (or delete) examples that don't measure up.
    – Jon Ericson StaffMod
    Commented Apr 10, 2017 at 20:44
  • As long as you can delete the crap and link to the proper documentation in the same action, I'm all for it. @JonEricson
    – user4639281
    Commented Apr 10, 2017 at 20:47
0

Here is a suggestion of a light-weight way to do this. I think we actually need two distinct ways of sending the reader to the right place.

  • A Topic Alias is just an alternative name for an existing topic in the same "Book". It shows up in the "topic finder", but when the reader clicks on it, they end up on the primary (aliased) Topic. This could be implemented as extra metadata on the primary Topic.

  • A Redirection Topic is a "reduced functionality" Topic. It would have a title, and a remarks section, and nothing else. It would (should) not allow people to add examples, syntax, etc. The recommended way of using it would be to put a brief summary of what the topic is about, with links to other Topics in this and other Books where there the real material exists. Typically, there would be multiple links.

For example a "Unit testing" redirection topic in the "Java Language" would link to the separate Books on "Junit" and "TestNG", and possibly to a hypothetical Topic on unit testing in a hypothetical book on Software Development Practice.

The same model could be applied at the Book level as well.

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