[html5] How to mark up FAQ

Mon Mar 17 15:02:33 PDT 2014

On Mon, 17 Mar 2014, Jukka K. Korpela wrote:
> 
> > There seem to be 3 main alternatives:
> > 
> > <h1>Question</h1>
> > <p>Answer</p>
> > <h1>Question</h1>
> > <p>Answer</p>
> 
> This is not satisfactory on several grounds. You would be using several 
> 1st level headings.

That's not necessarily a problem. For example, if the fragment above was 
all in a <section> element, it would semantically be equivalent to a 
series of sequential <section> elements.

> How would you mark the real 1st level heading then, the page heading?

If the entire page markup is the fragment above, then they would all be 
"page headings", effectively. That's ok too, though. See the outline 
algorithm for more details on how this gets mapped to an outline:

   http://whatwg.org/html/#outline

> If it's h1, too, then search engines would not know which h1 is the real 
> one.

Search engines would handle this fine, in practice. (Search engines have 
to deal with far less clear markup than this!)

> And the default (non-CSS) rendering would be bad, with huge font size.

Assuming the <h1>s are in a <section>, they would, per the spec, render 
like <h2>s without <section>s. (This is implemented in some browsers.)

> This would also restrict answers to single paragraphs.

It's trivially extensible to multiple paragraphs.

> Moreover, there would be no container for the FAQ as a whole, the list. 

Well, presumably it would be either a <section> or the <body>, at a 
minimum.

> This would make styling and scripting inconvenient. You could wrap it 
> all in a <div> element.

You could also do this, indeed.

> > <dl>
> >   <dt>Question</dt>
> >   <dd>Answer</dd>
> >   <dt>Question</dt>
> >   <dd>Answer</dd>
> > ...
> > </dl>
> 
> This makes the FAQ as a whole a single element and lets you to style it 
> conveniently. The default rendering would not be very good, but perhaps 
> acceptable.

The difficulty here, styling-wise, is that CSS doesn't yet support a way 
to style runs of elements withou a container (e.g. putting a box around 
every question-answer pair).

> Search engines probably don't give <dt> much relative weight, but 
> normally you would want the questions to be emphasized more than the 
> answers.

Search engines really are far less simplistic than this at this point. I 
wouldn't worry about the SEO value of <h1> vs <dl>.

> If you need to group consecutive questions and answers e.g. for styling, 
> you can't, in this model. A <dl> element does not allow such grouping.

Right. (Hopefully CSS will eventually support this.)

> To mention yet another approach, you could use a two-column table, with 
> questions in one column, answers in another. The data is structurally 
> tabular, but this is not a place for a table for practical reasons: in 
> almost all cases, tabular (grid) presentation is not suitable, and there 
> is not much tangible benefit from using <table> here.

Right, a two-column table is more or less equivalent to <dl>. (It gets 
harder to do the semantics right if you have multiple <dt>s and multiple 
<dd>s for a particular group, though.)

> In a typical case, the best approach might be something like this:
> 
> <div class=faq>
> <h2 id=abc>Question abc</h2>
> Answer to question abc. Use p markup if you have some use for it, typically
> when answers are longer than one paragraph.
> <h2 id=def>Question def</h2>
> ...
> </div>

This is basically equivalent to the <h1>/<p> solution suggested earlier, 
but yes, it's a good solution.

For consistency and ease of maintenance I would recommend using explicit 
<p>s for all paragraphs, but the spec does indeed allow them to be omitted 
in cases like the above (there are implicit paragraphs created in the 
semantics, but they don't appear in the DOM).

> The id attributes are there to allow direct linking to specific 
> questions from other pages. They are also useful if you set up a table 
> of content, of course.

IDs are a good idea on questions in a FAQ, indeed!

-- 
Ian Hickson               U+1047E                )\._.,--....,'``.    fL
http://ln.hixie.ch/       U+263A                /,   _.. \   _\  ;`._ ,.
Things that are impossible just take longer.   `._.-(,_..'--(,_..'`-.;.'