Thanks to everyone who's provided valuable feedback since I put the first version of the SPARQL FAQ online last week. I just wanted to take a brief opportunity to address some of the comments/questions I've received since then.
Can I receive updates when the SPARQL FAQ changes?
As I've said before, I'm still working on new questions and updated answers for the FAQ, and I intend to continue updating it regularly as SPARQL matures and is used more widely. Elias asked if there was a feed that he could use to keep up with the latest. Well there wasn't, but now there is. Feed readers/aggregators should be able to autodiscover the feed from the SPARQL FAQ page itself, but in case that fails, here's an Atom 1.0 feed of new questions/answers to the FAQ. As many aggregators won't currently re-show items with an updated atom:updated timestamp, I'll still post here on my blog when significant updates have been made to existing answers.
How can I print the SPARQL FAQ? How can I view all the answers at once?
The FAQ includes Expand All and Collapse All links that can be used to accomplish this. Depending on the CSS support of your browser, these links should either be in the top-right corner of the web page or else in the top-left corner. They're small, so they're somewhat easy to miss. So to print the FAQ, just click the Expand All link and then use your browser's print command to print the web page as normal.
How was the FAQ constructed? Can I reuse the infrastructure?
A side goal of creating this SPARQL FAQ (aside from answering common questions about SPARQL) was to try to create a more usable FAQ. After several discussions with coworkers (especially Sean and Elias), I came up with a few properties that I wanted to have in the FAQ:
- The FAQ should have an easy-to-navigate table-of-contents view, but I didn't want to have to maintain that table-of-contents independently of the questions and answers themselves.
- The FAQ should be on a single page and should be viewable all at once, to facilitate printing. (See above.)
- Both the FAQ itself and each individual question/answer within the FAQ should be linkable/bookmarkable.
- The FAQ should be completely accessible to browsers without JavaScript, though it's OK if the user experience is not as comprehensive without JavaScript.
To accomodate these properties, I chose the following technical approach:
- The FAQs are maintained in a simple XHTML format. On its own, the XHTML simply contains the category headers, questions, and answers, without the permalinks, table of contents, or expanding/collapsing behavior.
- CSS (currently inline, but there's no good reason for that) is used to style the FAQ appropriately. (Or inappropriately if you will, I'm not much of a designer.)
- JavaScript acts in response to the page's onload event to enhannce the user experience. This JavaScript does the following:
- Iterates through the categories and questions, adding numbers to them and collapsing (hiding) the answers
- Adds the permalinks in based on the ids of the questions, making it easy to copy a link for emailing, linking, bookmarking, etc.
- Adds the Expand All and Collapse All links.
- Adds event handlers to handle clicks to show and hide questions.
- An XSLT acts on the XHTML to generate the Atom feed of the FAQ (see above). Currently I run this XSLT manually to generate the Atom document whenever the SPARQL FAQ changes.
The JavaScript to enable this was designed to be reusable and can be downloaded here. (It has very basic instructions for how to use it inside. If there's much demand, I'll be glad to write up a brief tutorial to creating a FAQ using this library.) If you're interested in the XSLT which generates the Atom feed, just drop me a note.
