Tech doc challenge & HTML semantics: <article> vs <section>

HTML-CSS
1

Tell us what’s happening:

Hi - I have some questions about this project’s requirements, mostly for, I guess… academic purposes.

I’ve been reading a lot about HTML semantics and like many others I was confused with when to use <article> and when to use <section> . MDN web docs and WHATWG specification wasted little breath explaining this in much detail, but I managed to find elsewhere some good articles on this topic, and here’s one which, in my opinion, explains it very well: http://html5doctor.com/the-article-element/#div-comment-31959.

Now, the Technical Documentation Page challenge requires that each main section be enclosed in <section> tags. If I’m not understanding the <article> vs <section> topic wrong, wouldn’t <article> be more appropriate, since each main section is, or meant to be, a “complete, or self-contained, composition in a document, page, application, or site and that is, in principle, independently distributable or reusable”?

What’s more perplexing is how the two tags are used in the example solution - main sections are enclosed in <section> tags and paragraphs inside each main section, excluding the section title, are enclosed in <article> tags (except for the Variables section, which I guess is likely an accidental omission). Is the usage of <article> there correct? Is it redundant?

Would appreciate some clarification.




Your code so far
N/A




Your browser information:

User Agent is: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/88.0.4324.182 Safari/537.36 Edg/88.0.705.81.




Challenge: Build a Technical Documentation Page

Link to the challenge:

2

Back when committees were arguing over the new tags and their usage, the only explanation that made sense to me was when using a system like WordPress, for example, was the “recent posts” page. The posts were to be marked up as articles and can contain their own H1 (back the the practice was for the post heading to be an H2, which makes sense on the "recent posts"page but not on the page containing only the post). In the context of a “recent post” page each post is “complete or self-contained” which is what they say about the article element.

If you think of a physical newspaper each page has many columns containing separate articles. We just don’t make webpage with that style.

Some people held the opinion that section was duplicating div and unnecessary. Section can be used in many contexts so I wouldn’t stress about needing one or not.

Hope this helps.

3

Thanks. Would you say sections of a technical documentation are somewhat similar to a blog post in the sense that technical documentations are reference materials and individual sections are meant to be read/referred to individually?

4

Personally, I think the FCC sample is not the greatest when it comes to semantics. I do think each of the “sections” of the doc should be in a <section> tag (as they are in the sample) but then instead of a <header> tag they should be <h2>s. Sections should almost always have a heading.

And I would not use an <article> to wrap the content in the section either. The content is not a “self-contained composition”, it is part of an entire document. And like <section>s, and <article> should almost always have a heading near the top, which in this case is clearly not needed.

Regardless of what I think, the distinction between <section> and <article> is often not perfectly clear and sometimes it just comes down to preference. You could use either for the technical docs, I just don’t think you need both of them.

2 Likes
5

I think that a typical documentation page with a sidebar full of topics can be navigation to separate pages or on-page navigation to a new topic with its own heading. That’s all the semantic division I need and it doesn’t impact ARIA either way.

6

Thanks. I’m starting to come around to your point. A section of a reference documentation may not make sense anymore if taken out of context, and what establishes the context is likely outside the section e.g. main title of the documentation. Therefore, the section isn’t a self-contained composition.

7

This topic was automatically closed 182 days after the last reply. New replies are no longer allowed.