Technical Documentation Page - feedback, please :)

Hello everyone!

I’ve finished my Technical Documentation Page challenge. I chose Accessibility as the topic :slight_smile: I’d love to hear some feedback on it! What do you think? What can I do to improve?

(Even though I tried hard, I’m not sure my page is very accessible, especially the dropdown menus. I tried making it accessible without javascript but probably there’s something I’ve missed there…)

Thanks so much already! :blush:

Great work @ines-violin. Your doc looks pretty awesome and well structured.

  • To get the ‘smooth scroll’ effect you desire, I’d advise using scroll-behavior and then setting this to smooth would be a better syntax.

  • Great work using the article the only thing is articles in HTML semantics require you to have h2-h6 elements in them. You can run your code through the The W3C Markup Validation Service to check for warnings or errors in HTML for markup validity.

  • On the mobile layout, I can’t seem to find the navigation and that is quite important for a web page I believe. If I was trying to access your docs from a mobile phone, I would need to scroll to the bottom manually which doesn’t really give the best user experience.

In all honesty, you did an amazing job of completing this project. Keep pushing and Happy coding :+1:!

1 Like

Overall, I would say that your page is very accessible. Great job! Yes, the accessibility of the drop down menus could be improved, but as you guessed, this would require JS. Without using JS, my official recommendation for these would be to always display the submenus and not use the drop down effect at all, but unless you are planning on using this down the road to show to a potential employer then I wouldn’t worry about it.

As @teamie already noted, you have hidden the nav menu for narrow widths, which is sort of cheating :slight_smile: but I also understand why you did this, because implementing a proper accessible “hamburger” menu does require JS. You could just move the nav menu on the top and make the best of it, but you probably wouldn’t do that in the “real world” so I’m willing to give you a pass on this.

A few minor suggestions concerning accessibility if you are interested.

  • You are relying on the browser’s default focus indicator when people use the keyboard to navigate your page. Under the current accessibility guidelines (WCAG 2.1) this is not an accessibility failure, but under the new impending guidelines (WCAG 2.2) this would be considered a failure because not all browsers implement the focus ring to meet the minimum requirements coming in 2.2. I would highly suggest you always customize the focus indicator to make sure it is easily seen. CSS-Tricks has a good article to give you some ideas on how to do this.

  • As @teamie pointed out, usually an <article> would contain a heading at the very beginning. If you were intent on using an <article>, then I would just replace the <section>s with <article>s as I don’t think you need both. But sometimes the distinction between section and article isn’t that clear and to be honest, as far as accessibility goes, it doesn’t really matter that much. (There is a specific use for <section> that can turn it into a landmark). An article is supposed to be a self-contained composition, which would include the heading, the content, and any additional information needed to understand the content. In other words, an article should stand on its own. Some of these sections definitely fit that definition, but I’m not sure the Reference section does, or even the Overview section. Personally, I would probably leave all of these as <section>s and drop the <article>s completely.

  • You might consider putting a max-width on your content so that the lines of text don’t get too long, which can be hard for some people to read. I’d recommend using em units for the max-width, but there are other relative units you can use as well. Just don’t use px as that won’t allow the width to adjust if the user manually makes the font size bigger.

1 Like

Hi @teamie! Thanks so much for your reply and for checking my page! :blush:
I’ll work on making the changes you mentioned! Regarding the navbar not showing up on the mobile layout that was actually intentional, but as bbsmooth said below, kind of cheating :see_no_evil: I just couldn’t figure a way of making it effective and accessible solely through CSS…

Thank you again for your comments and encouragement! :grinning:

1 Like

I’m sure you’ll figure it out eventually. Don’t forget this is a supportive community and a safe space for Devs. DO NOT HESITATE to ask for help whenever you get stuck even if it’s “supposed” to be easy. Cheers :clinking_glasses: and Happy coding!

1 Like

I’ll certainly do that in the future! I’m definitely guilty of thinking I should ask for help but then changing my mind because maybe it’s something too obvious to ask :see_no_evil: I’ll to that instead next time! Cheers! :grin:

Hi @bbsmooth! Thank you very much for taking the time to look through my page and I’ll implement your suggestions right now! Regarding the nav menu, in that case I might leave it like it is for now but I look forward to learning how to do it right with Javascript! :grinning: Thank you again for your help! :smiling_face: