5

Based on previous topics on meta.stackoverflow.com, there appears to be a gap how we can better assist users when answering questions by providing direct links to documentation (supplementing the answer itself being provided). mario has already released a very helpful add-on that inserts generic links, which is helpful, but still (in my eyes) remains in the "third party solution" realm.

I'd like to see both a more advanced solution, but also something that could possibly be a "helping hand" to the SO developers themselves which would make seeing this embedded on the site that much more plausible (or so that's the idea).

Having said that, I felt I would take a step in the direction of a [permanent] solution while also tackling the problem at-hand. So I've come up with a WebService implementation of an AJAX look-up for tag-specific documentation. The premise is simple: expose a method we can access with browser plugins using a library such as jQuery and JSONP calls, but (with minimal effort) can be altered to work as an embedded solution that the SO team can tie in directly with the existing UI.

Currently, most of the groundwork is done; I have a simple project with the WebService itself and a class that takes advantage of the Managed Extensibility Framework (MEF) (so this can be completed in a modular fashion). The service is passed two (well, three if you include the JSONP callback) parameters and a JSON object is returned with the matches. In addition to this project is a simple library exposing two main interfaces:

using System;
using System.Collections.Generic;

namespace SO.DocumentationLookupInterface
{
    /// <summary>
    /// Defines what service(s) a look-up module should provide
    /// </summary>
    public interface IDocumentationLookup
    {
        /// <summary>
        /// Perform a lookup based on the search term, and return a list of results.
        /// </summary>
        /// <param name="term">Term to search for</param>
        /// <returns>List of results matching the <paramref name="term"/></returns>
        IEnumerable<IDocumentationResult> PerformLookup(String term);
    }

    /// <summary>
    /// Defines what a single result (match) from a look-up should include
    /// </summary>
    public interface IDocumentationResult
    {
        /// <summary>
        /// Resulting term (property, function, method, etc. name-- basically the match itself)
        /// </summary>
        String Term { get; set; }

        /// <summary>
        /// Language this term is associated with (e.j. jQuery, .NET, etc.)
        /// </summary>
        String Language { get; set; }

        /// <summary>
        /// Brief description of the match (may be a prototype, quick synopsis of what the match
        /// does, etc.)
        /// </summary>
        String Description { get; set; }

        /// <summary>
        /// Direct link to this item's documentation page
        /// </summary>
        String ReferenceUrl { get; set; }
    }
}

From these interfaces, a class library can be created with (basically) the following footprint:

MEF may be a little overboard for this, but I was trying to make this as modular as possible, and switching over to a static system if SO decides to take this on/implement it shouldn't be that difficult. So, given that information, is anyone up to the challenge of writing (even the simplest of) look-ups? I plan to tackle at least a couple just to get the ball rolling, but I certainly am going to need help.

If enough interest is shown I should be able to host this up on a server somewhere for anyone that wants to develop. I (undoubtedly) don't have the bandwidth for the entire SO community, but should be able to at least provide a sandbox for people to test/play (unless localhost is okay with people). I'm also thinking a codeplex is probably in order considering the collaboration unless anyone else has a better idea.

I'd love to have feedback. I'll post the solution (VS2010) most likely tomorrow, but feel free to leave me comments on the direction that is ideal for this.

2

0

You must log in to answer this question.

Browse other questions tagged .