Technical Documentation Page Feedback - wavyhix

Hi :slight_smile:,

Could I please get some feedback on my technical documentation page?

I’ve run it through the W3C validator and the only issue is the warning ’ Section lacks heading. Consider using h2- h6 elements to [add identifying headings to all sections.’
I’ve decided to ignore this as the example provided to us ignores this warning.

Thank you!

1 Like

The example is wrong. You should definitely mark up those things that look like headings at the beginning of each section with a heading tag (an <h2> in this case). You also need an <h1> heading near the top of the page, which would be “Minecraft Dirt Mechanics” in this case. It’s in the <nav> which is not ideal, but if that’s what you need to do in order to pass the tests then so be it. Headings are huge accessibility requirement. Anyone using a screen reader relies on them heavily to navigate the page, so you never want to leave them them out. I know you are required to have a <header> tag at the beginning of each <section> but in the real world you would most likely not have these and they would just be <h2>s instead. But since you need them, put the <h2>s inside the <header>s.

A few other accessibility issues:

  • The white on bright green does not quite have enough color contrast. There are a ton of color contrast checkers out there. An easy one to use is the WebAIM Contrast Checker which will help you find an accessible color combination based on what you are starting with.

  • You are relying on the brower’s default focus indicator, which does technically meet accessibility requirements (for now) but in practice is not a great idea as I can’t really see it when I Tab through the nav menu. In general you should customize the CSS outline property for links, buttons, and other interactive elements so that the focus indicator clearly stands out to help keyboard users navigate through your page.

  • I would recommend you wrap the <code> tags with <pre> and then put each line of code on its own line like you would if you were coding in an editor. The <pre> tag will preserve the formatting. This will also make the line length shorter so that if the browser is narrowed everything still looks good. And it will allow you to get rid of the <br>s. Also, set CSS overflow-x: auto on the code tags so that if the browser gets too narrow and the code lines start to overflow then a horizontal scroll bar will appear (which is a legitimate use of horizontal scroll).

  • If I shorten the browser enough that some of the nav menu items go below the bottom of the browser window I do not get a vertical scroll bar for the nav menu and the vertical scroll bar on the main window does not help, thus those bottom nav items are inaccessible. Based on my advice for handling overflow with the code samples I’m guessing you can figure out how to handle vertical overflow for the nav menu.

1 Like

Thank you so much! That is one of the most comprehensive answers I have ever been given. I will put your advice to good use :).