Technical Documentation Page finally done!

Very happy about it!
FCC Project: Technical Documentation Page (codepen.io)

Created some joke content. At some point I was wondering if I spent too much writing it but soon realised I was gaining some very good understanding on HTML semantics.

Took a mobile-first approach this time. Learned some very neat CSS tricks along the way.

I am however wondering whether I should use media queries right after each style block I want to change or should I write fewer and bigger blocks of media queries.

My overall feel has been that, unlike JavaScript (which I did on FCC first), to write something satisfactory in HTML and CSS, you really need to read about a lot of stuff first.

1 Like

Your page looks good @gaac510. Some things to revisit;

  • Run your HTML code through the W3C validator.
    • There are HTML coding/syntax errors you should be aware of and address.
    • Since copy/paste from codepen you can ignore the first warning and first two errors.
  • Do not use the <br> element to force line breaks or spacing. That’s what CSS is for.
    • Reference MDN Docs
    • There are two solutions to preserving whitespace and line breaks. One is an HTML solution, the other is a CSS solution. A search will help.

There are two schools of thought on this. Because of the shops I worked in it was always the bigger blocks but there is nothing wrong with adding right after each style block. I find the former easier to read and maintain but again, it’s what I’m used to.

1 Like

@Roma Thanks a lot for the feedback!

Would you mind being more specific about where/how <br> was used inappropriately?
I only used it in the coding blocks where the division of lines is significant.

Yes, I see where it’s used and yes it is significant. What I’m saying is you shouldn’t use the <br> element.
There is an HTML solution or a CSS solution that you can use to preserve the significant whitespace and line breaks. Search for it and show us what you’ve found/tried.

Are you talking about using <p>, line-height and margin etc.?

No

I’m talking about still using the code element but not using <br> element

<pre>
or
<span> + float + clear?

Good job. The first one is the HTML solution.

You can nest multi-line <code> snippets in <pre> </pre> tags in HTML to preserve whitespace and line breaks.
Or skip the pre element and do the following in CSS;

code {
  white-space: pre-line;
}
1 Like

@Roma Thanks!

I actually read about <pre> earlier on. I was going to use it initially but realised if I want to keep my HTML perfectly indented, unwanted white spaces were added to the beginning of each line of codes.

(I just realised I can probably wrap each line using <pre>, but is this an acceptable approach? Edit - just tried; works rather well except needed to type pre alot :joy:)

There’s a problem with white-space: pre-line. It wraps my codes when the viewport is too narrow, which I didn’t want . Of course I can set width or min-width of <code> blocks to max-content but this makes the code block stick out to the right when the viewport is too narrow, which I didn’t want either. The effects I was hoping to achieve were:

  1. Each line of code doesn’t get wrapped.
  2. The width of the code block be responsive to viewport width, and if any line of code becomes longer than the block’s width, a horizontal scroll bar appears at the bottom of the code block box to allow for scrolling of the code block individually.

Would you have a practical way to achieve these without using <br>?
I did quite a bit of research on this while working on the project but just couldn’t find anything very satisfactory.
(Edit 12/3/21 - Just tried wrapping the <code> with <div> and set overflow-x: auto and max-width: 100vw for the latter. Worked! :grin:)

@Roma Sorry. One more question. Why are we so terrified of <br> that we seem to need to avoid it at all cost?

I’ve done a bit of reading on this but nowhere offered very convincing reasons.

Some sources say it’s because of accessibility issues, but then a lot of HTML stuff have accessibility issues. Why are we only terrified of <br>?

Some sources say it’s because it’s not semantic, but:

  1. Occasionally a line break is genuinely the convention as in “everybody knows a line break is supposed to be there”, so much so it becomes part of what establish the context.
  2. If a line break is expected, wouldn’t not using a line break non-semantic?

Not at all saying we can use it anywhere we want, but surely there are times it is the most appropriate option?

We’re not terrified of the <br> element. Back in the 90’s when Tim Berners-Lee came up the HTML there was no CSS and that element was very important.
However, since the advent of CSS its use has generally been used for postal addresses and poems.

1 Like

@Roma Thanks again.

As I tried to understand it. The reason why <br> is OK for poems and postal addresses is that the tag helps with establishing the context, in that:

  • Line breaks in a poem == This is a poem.
    No line break in a poem == Is this a poem? Maaaaybe? But why no line break???

  • Line breaks in a postal address == This is an address meant to be on a letterhead/envelope.
    No line breaks in a postal address == This is an address meant to be used to fill a form.

But then similar logic may be applied to line breaks in code blocks:

  • Line breaks in a code block == This is a block of code likely written by a human and is meant to be human readable.
    No line breaks in a code block == This is a block of code likely compiled by a program and is meant to be fed directly to programs.

Am I wrong to assume this is also a valid logic for the usage of <br>?

Your pages look fantastic, great job! =)