5 Replies Latest reply: May 24, 2012 3:08 PM by Christopher Deschenes RSS

Rethinking the FAQ

Dan Allen Master

Now that we've gotten past publishing arquillian.org and getting the introductory guides written and translated, it's time to look at what other information is still in hard to reach places. One of the items on that list is the FAQs. Recent FAQ contributions (1, 2, 3 and 4)* by a community member drew attention to the fact that it's not very clear how, or where, to add FAQs.

 

Currently, the FAQs are stored as articles in the faq subspace and listed on that space's index page. (See Arquillian FAQ) I used the best solution I could come up at the time. My choices were Magnolia and SBS. I decided to set it up in SBS because at least the content could be edited by anyone in the community (though until recently the permissions were locked down to space admins, so we didn't end up with many contributions). However, the system is quite cumbersome, not really searchable and hardly interactive.

 

Let's use this thread to brainstorm a better approach to FAQ.

 

We can start by defining the purpose and some requirements.

 

The purpose of the FAQ is the curate answers to common questions and helpful hints into a central location to circumvent frustrating experiences with the platform (esp over the face-palm problem).

 

Here are some of the requirements off the top of my head. Feel free to revise this list:

 

  • Adding an FAQ should be a simple task (if it's hard, then contributors will not bother and the knowledge will be lost)
  • Code syntax highlighting should be supported and not require a lot of fiddling
  • Users should be able to offer alternative answers and reasoning to the FAQ (ala stackoverflow)
  • Users should be able to vote up an FAQ and each of its individual answers
  • Contributors (and perhaps users) should be able to tag FAQs
  • Hot and popular FAQs should bubble to the top
  • FAQs should be searchable (if a google search works, we'll take it)

 

I don't necessarily think that FAQs should replace forums, because forums tend to have way more information than what is needed once the issue is solved. (The "Correct Answer" feature of the discussion forums in SBS at least partially solves this issue), but the whole thread is still a lot of baggage for an FAQ I think.

 

We may want to explore the idea that an FAQ can be converted into an issue report (i.e., JIRA). Though, if we do that, why not forum posts too?

 

Here are some possible open source Q&A solutions that I'd like to put forth.

 

  • AskBot (requires Python and Django)
  • OSQA (requires Python and Django)
  • Shapado (requires Ruby and MongoDB)

 

We can easily run these on OpenShift if we want. Of course, there's the possibility JBoss IT will run it for us, but I think first we sort of need to know if these are even the right solution.

 

The other possiblity is that we use a hosted solution, such as Quora or StackOverflow. I shy away from StackOverflow for our "official" FAQ because I don't think we can have a branded space. I really want to be able to promote the curated answers easily, so that they are found. If StackOverflow would serve this purpose, feel free to make a case for it.

 

* I likely move these into the FAQ catalog in the short term.

  • 1. Re: Rethinking the FAQ
    Aslak Knutsen Master

    Just adding some thoughts..

     

    I think a Q&A solution, frequent Q/A or not, will help alot.

     

    Guides:

      Overall picture of getting started with something

     

    Reference:

      Every possible configuration option on Extensions/Protocols/Containers + some general how core works (90% generated)

     

    Q/A: Small snippets of concrete knowlegde.

    How can I:

      - add Libraries to be my Deployment?

      - setup multiple containers with Maven?

      - test a secure EJB?

      - test HTTPS with Selenium in Drone?

      - clean up a database per test class?

      - test async EJBs?

     

    Even things like:

     

    - configure Chrome in Drone? -> see ref doc xxxx

     

    If we tag the Q/A's correctly, we should be able to add a 'Q' section to the guides. Matching what the Guide is about with other Q/As related to the topic. Possible a 'yes helpful' button for the Answer would be useful to rank the listing.

     

    Idealy, we should be able to 'tag/convert' a Forum post/Answer to a Q/A, but they probably need to be reformatted/rewritten anyway. I don't think using the Q/A solution as a forum is such a great idea, as it will most likely flood the content and thin out it's value. Basically a Q/A solution should have a Q with a A and not just a bunch of Q's.

  • 2. Re: Rethinking the FAQ
    Dan Allen Master

    Aslak Knutsen wrote:

     

    Q/A: Small snippets of concrete knowlegde.

    How can I:

      - add Libraries to be my Deployment?

      - setup multiple containers with Maven?

      - test a secure EJB?

      - test HTTPS with Selenium in Drone?

      - clean up a database per test class?

      - test async EJBs?

     

    Even things like:

     

    - configure Chrome in Drone? -> see ref doc xxxx

     

    I agree. In many case it will be another view, sort of an ad-hoc index for the guides. How do I do JPA testing -> see the testing java persistence guide.

     

     

    Idealy, we should be able to 'tag/convert' a Forum post/Answer to a Q/A, but they probably need to be reformatted/rewritten anyway. I don't think using the Q/A solution as a forum is such a great idea, as it will most likely flood the content and thin out it's value. Basically a Q/A solution should have a Q with a A and not just a bunch of Q's.

     

    Giving it more thought, I agree that Q & A is distinct from a forum. In some cases it's the result of a forum discussion, in other cases it's a sign post to help people find the appropriate resource and finally it's about those snippets of knowledge that are too small for a guide, or get buried in a guide.

     

    I don't think we should be afraid of more information. If we've learned anything from running Arquillian so far, it's that more information is always welcome. The rating system helps the good information stand out (meritocracy of information).

  • 3. Re: Rethinking the FAQ
    Dan Allen Master

    The next step on this may be getting on of these solutions setup on OpenShift so we can at least play with around with it. We have plenty of slots now Not sure when, but that seems to be the next step.

  • 4. Re: Rethinking the FAQ
    Rajmahendra Hegde Newbie

    Stackoverflow is haveing a option of Area51

     

    Area 51 is the Stack Exchange Network staging zone, where users come together to build new Q&A sites. New site ideas are proposed, discussed, and the best go on to beta. See the faq for more information

     

    the use in StackOverflow is many have like the badging and ranks : There aer other groups like Science, Ubuntu etc... so its nice to host there.. true its outside of the scope of jboss but its good tohave a popular solution

  • 5. Re: Rethinking the FAQ
    Christopher Deschenes Newbie

    Hey guys,

     

     

    We have been working on something similar with some of the Spring-Source folks. They wanted an automated generation of FAQ from StackOverflow with a couple of extra features tacked on (like being able to categorize questions more finely).

     

    It seems that this is pretty much what you guys want. *We could add support so that you can easily add your current items to that FAQ.*

     

    Would you guys be interested in joining the initiative?


     

    I believe you saw an early release of our site CodeMaps.org .  Our first beta release was a code browsing site, but we have been busy polishing the site and exposing more features from our backend.  We most recently released support for tagging code for sharing with other team-members. The site does include branding support for project admins.

     

    What do you guys think?