What is meta? ×
Meta Stack Exchange is where users like you discuss bugs, features, and support issues that affect the software powering all 133 Stack Exchange communities.

I'd like to propose a new feature for StackOverflow Markdown: documentation links. There are a couple problems with adding documentation links right now:

  • Links can die, leaving them almost useless for people visiting old questions.
  • People often post locale-specific documentation. A link to the German documentation for PHP's urlencode(), for example, isn't as useful to me. This is especially the case with PHP, and it can easily be solved by being non-specific and using http://php.net/<function-name> as the link address.
  • It's time-consuming to go look up the right documentation on a reputable site and copy the URL.

So here's my proposed syntax:

See the [documentation for <something> at <site>] for more information.

where <something> is a fully-qualified class name, method name, or whatever will fit in the URL and <site> could be a site name or possibly a language, whatever's better. For example:

  • msdn/vb.net, c# (http://msdn.microsoft.com/library/<name>.aspx, locale-nonspecific)
  • mdn/javascript (https://developer.mozilla.org/en/JavaScript/Reference/<something>, this one's tricky and I can't seem to make it locale-nonspecific)
  • php.net/php (http://php.net/<name>, perfect and easy)

etcetera. This would really encourage people to link to the documentation, which is always helpful, and would help to avoid certain poor online resources that people keep posting in answers and comments.

Good idea? Not good idea?

share|improve this question
    
I'm not sure I follow what you're proposing. Are you suggesting that SE figures out link structure at MSDN and other doc sites instead of having a user just paste a direct link? What about official docs from non-mainstream locations (e.g. framework-specific documentation hosted on the author's site)? –  Anna Lear Dec 29 '11 at 3:12
1  
@AnnaLear: Just for some major and commonly-used documentation sources. The link structure isn't so difficult, usually. As for official docs from non-mainstream locations... they could still paste a direct link, I suppose. It would just be a very convenient feature to have. –  U2744 SNOWFLAKE Dec 29 '11 at 3:14

2 Answers 2

up vote 2 down vote accepted

How would you programmatically get from [documentation for the FormClosed event at MSDN] to the (at the time of this writing) actual link: http://msdn.microsoft.com/en-us/library/system.windows.forms.form.formclosed.aspx?

Asking the poster to spell out the full namespace of the link could work, but I think it'd make the answer harder to read. In general, if a doc link is broken it shouldn't be a big deal as it should be easy to look up what it is again.

Further, what if some of the links changes but not all? Then updating the shortcut likely wouldn't be as simple as adjusting the link template.

All in all I don't think this is worth doing. There are many other links that are just as likely to fail and arguably harder to replace (diveintohtml5, anyone?) and I think it's best if users work links into their posts naturally. It comes down to following the usual guidelines: a link in the answer should only be a supporting reference, not a substitute for a real answer. That way if a link dies we don't really care and links can be updated if/when necessary.

share|improve this answer
1  
I was thinking more along the lines of [documentation for System.Windows.Forms.Form.FormClosed at MSDN], but I see your point... –  U2744 SNOWFLAKE Dec 29 '11 at 3:27

Links can die, leaving them almost useless for people visiting old questions.

Can't links still go dead?

People often post locale-specific documentation. A link to the German documentation for PHP's urlencode()

Don't see that very often. Actually only seen it once and fixed it.

It's time-consuming to go look up the right documentation on a reputable site and copy the URL.

Don't know what you mean by this...

Overall what you are proposing seems to be like a hell of a job to get working. And if a site changes over time for some reason it has to be revised again. Not to mention all the different sites for documentation and their own setup of the url's and / or not matching functionnames vs urls.

I neither see the problem as you stated.

share|improve this answer
1  
Well, if a documentation link stopped working, SO would just change the link template and all the links would follow suit instead of laboriously changing each one and missing many. As for locale-specific documentation... I can't help that you don't see it a lot :) I certainly do. –  U2744 SNOWFLAKE Dec 29 '11 at 3:16
1  
Are you sure you aren't on stackoverflow.de??? ;) –  PeeHaa Dec 29 '11 at 3:17

You must log in to answer this question.

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