Rethinking the FAQ
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.
