Feedback for Technical Documentation Project

Code Feedback
1

Hi everyone!

I recently completed my technical documentation project and ended up changing it up a bit in CodePen. It took me a really long time to get it where it’s at but I feel like the code is pretty messy and I really struggled with formatting it to be readable and easy to navigate on both larger and smaller devices.

If anyone has feedback on it in general or with 1-cleaning up the code 2-formatting for multiple devices I would be grateful!

Link to project

Thank you!

2

Look good. Everything seems spaced out evenly, no big gaps or anything as far as I could see. There is this though

IMG_1324
IMG_13241095×1833 319 KB

You have multiple dots for the li. I would get rid of those to make it look better. There is some css you can use to get rid of those dots and keeps the li in the html. I will leave that for you to find if you choose to do it :grin:

Also. This may just be me, and has nothing todo with the actual design, functionality of the page. I see you have multiple BOTTOM LINE. Personally I think it would be better if you had just one bottom line at the end that summarizes everything.

Again, thats just my thought

1 Like
3

Thanks so much! I got rid of the dots that were just hanging out there and incorporated section summaries instead of a bottom line in each section since that can definitely be confusing if there are multiple bottom lines and they aren’t really at the bottom :slight_smile:. I really appreciate your feedback!

4

You’ve done a fantastic job! There are two sketchy UI things if I were to nitpick

  1. The sidebar links jump to the right on hover
  2. When hovered, the links within the article get a background of blue, but the padding places the text on the edge of the background

Just some things that could improve the experience overall, but not necessary. Good work!

5

Awesome, I went ahead and fixed those so that on hover, the color of the text changes since the padding was pushing everything to the right which can make the text more tricky to actually use as links. I appreciate the feedback and thanks so much! :slight_smile:

1 Like
6

So a few notes here re. the structure (this is a really nicely put together page btw).

The important one is that you’ve put the headers in <header> elements. <header> is a sectioning element, it is used to contain other elements, not text directly. Navigation between parts of a page using accessibility tech normally relies on headers within the document, ie <h1>, <h2> &c. <header> is used to contain elements such as that, plus (for example) some subheaders or explanatory text or images or whatever. It’s useful to have those <header>s, but you don’t need them, you can replace them with <h1>s.

Technically you can use <h1> throughout, beacuase the semantics are that each section of the document can have its own <h1>, so in your case you have a document, with two base sections (<nav> and <main>). They can each have an h1. Then each section in main can have an h1, and so on.

However this can produce weird results in some accessibility software (and some SEO stuff). So generally you’d want one <h1> (the title for the whole document), then can use <h2> for all the rest of the titles.

So example structure:

<body>
  <!-- This will implicitly be treated as the document's overall header -->
  <header>
    <h1>Document title</h1>
    <h2>Subheader</h2>
    <p>Maybe some extra info</p>
  </header>
  <!-- This will implicitly be treated as the document's overall navigation -->
  <nav>
    <h2>Document navigation</h2>
    <ul>
      <li><a href="#a">Link to a</a></li>
      <li><a href="#b">Link to b</a></li>
      <li><a href="#c">Link to c</a></li>
    </ul>
  </nav>
  <main>
    <section id="a">
      <h2>Section a title</h2>
      <!-- stuff here -->
    </section>
    <section id="b">
      <h2>Section b title</h2>
      <!-- stuff here -->
    </section>
    <section id="c">
      <h2>Section c title</h2>
      <!-- stuff here -->
    </section>
</body>

So you don’t need <header> elements at all here in your code, an <h1> in the nav + <h2>s in the sections will be fine. It’s useful though.

Next thing is this:

<p class="quote">
  "We believe this is a transformational moment for technology and social justice. The need is obvious. Let's do something about it." -Erin Baudo Felter
</p>

A <blockquote> element is used to denote quoted text taken from another source.

<blockquote cite="https://where-this-quote-came.from">
 <p>We believe this is a transformational moment for technology and social justice. The need is obvious. Let's do something about it.</p>
</blockquote>
<p>

So, rules are:

  • It’s a containing element, so you can wrap text in the <blockquote> in something like a <p>.
  • The attribution must be outside the <blockquote> element.
  • The <blockquote> may have a citation, passed as the cite attribute. That citation must be a url pointing at the source. Leave it off if you don’t have one.

Styling becomes fiddly, and you need a way to link the attribution to the quote.

A <figure> element is designed for usecases like this:

<figure>
  <blockquote cite="https://where-this-quote-came.from">
   <p>"The power of the Web is in its universality. Access by everyone regardless of disability is an essential aspect."</p>
  </blockquote>
  <figcaption> Tim Berners Lee</figcaption>
</figure>

<figure> also works really well for your examples (you can provide descriptions and access software will be able to easily understand the link between the images/text and the description of them).

(I’ll leave it at that for the minute, there are some other minor issues but these are most immediately fixable & should bump the rating up to top level)

1 Like
7

Awesome, this is all really, really helpful! I changed all of the headers to h2 and added a h1 to make it more cohesive and readable. I also changed all of my “p quote” elements to blockquotes, cited, inside of figure elements. This is all really great to know since I want my page about accessibility to be as accessible as possible! Thank you, I appreciate the detailed response!

1 Like