The Struggle is Real: My Journey with CSS Debugging
A CSS debugging story
CSS is the stylesheet of the web. It's the language responsible for giving every website its aesthetically pleasing look, and it's also responsible for many developer headaches. In this article, I'll be sharing my CSS debugging story, and a few lessons I learned.
The Problem
I was writing a CSS at-page rule - @page - over two months ago to submit proposal documentation to an agency, and as I was working on it, I discovered a peculiar bug on the at-rule that made me spend three whole days trying to fix. :) I honestly wish it was just a few hours for it to be solved so I could attend to other duties.
Intended function
The @page at-rule is a CSS at-rule used to edit the pages of a print-out. From background properties to page dimensions, and more.
On MDN at the time, it was stated that I could only change the orphans, margins, widows and page-breaks of the page print-out. But, after testing each property, I found out that only the margin property had a visual effect on the document.
Weird right? I thought something was up so I cross-checked MDN's documentation using the official spec and according to the spec, I can edit the page's margin at-rules properties and page-properties of the document.
Then, I still thought that MDN's doc was correct and the official spec was correct as well, and maybe the combination of the two documents is how CSS is documented. Well, that was dumb and I was wrong.
The properties from the spec are just specific CSS properties that are used to edit a page's display features. However, these properties didn't have any visual effect either, except the margin property! For example:
Here we have a simple HTML page with three unstyled paragraphs.
<p>This is an example text on a print-out</p>
<br/>
<p>This is an example text on a print-out</p>
<br/>
<p>This is an example text on a print-out</p>
<br/>
Below, we have the CSS editing the page when it's about to be printed.
@page {
text-align: center;
background-color: lightblue;
margin: 5rem 16rem;
}
The code above should output this result:
Reality
The reality of the situation caused many headaches and nightmares back then. Here's a screenshot of what happened:
Notice how both the CSS text-align and background-color properties were not applied to the printout. Only the margin property was. That was the visual bug I was facing, and I needed to fix this so I could submit it as proposal documentation.
Note: A visual bug is a type of bug that occurs when elements on a website or graphical interface do not display as intended.
Markus' article on Visual bugs provides more insight into what visual bugs are with clear examples. Be sure to give it a read!
Debugging Process
Whenever I encounter bugs like this, I go through a series of mental checks in my mind:
Is the stylesheet (<style></style>) linking the right file?
Did I write the correct syntax?
Was the HTML syntax wrong?
Maybe, my browser is the problem
...
The debugging process was simple. Make sure I got everything right both syntax-wise and logic-wise. However, after spending a few days performing the necessary checks, I got everything right. Everything was looking good on my side. Then, I realized something that has never happened before in my entire life as a developer.
My syntax was correct, but the language was at fault.
Since everything was surprisingly okay from my side (trust me, it was a shock) I took a second look at MDN's documentation, looking for how I could correct the error from their side so that other developers that encounter this issue won't waste hours trying to solve a non-existent bug.
That's when I opened a pull request on MDN docs.
Resolving the Bug
Spoilers: The bug wasn't fixed.
I still experience the same issue. However, the official spec hasn't reflected anything at the time of this writing to implement a solution for it, but I found out I could do something to correct the documentation from MDN's side, and that's what I did.
Since the bug wasn't from my side but from CSS itself, I wanted to let other developers know that it's a feature that should be corrected.
Although I only identified one error in the documentation and wanted to correct it, there were many other things wrong with the documentation that needed to be fixed. And with the big help of the awesome technical writers at MDN, that's what I did.
After 3 months of reviewing, rewriting, and painful testing. We rewrote the whole at-page rule to reflect the bug I identified with the inaccuracies we spotted, and the changes were merged into MDN's doc.
Lessons Learned
The whole process was exciting, and I'm pretty certain any front-end developer reading this would agree that with most CSS bugs, it is painful to debug. But, I learned a few lessons throughout this whole journey and I hope they would be of help to you too:
Follow the 15-minute Learning Rule
The 15-minute learning rule says that after 15 minutes of intensely focused problem-solving on a hard task, seek help. I struggled in the past asking for help, and it's really because I did not want to be a burden to someone else.
However, I've realized that that's why I have Senior developer and technical writer mentors. They are people that are well-experienced in the field and might have come across such bugs that I'm currently struggling with. It shouldn't be a burden for them to help contribute to my growth in tech.
Overall, this method saves a lot of time especially when it's work-related and there are deadlines to meet. A task that you might you spend three days on could've been done in less than an hour sometimes if you asked the right person.
Note: Martin Brennan's article on "Supercharge your learning with the 15-minute rule" excellently expands more on what the 15-minute rule is about and how it applies to everyday tasks and work life. Be sure to give it a read if you want to learn more about this!
Sometimes You're Not at Fault
If you're like me and the major causes of bugs have been incorrect syntax, incorrect placements of semi-colons, and the like. Then, it's safe to say that this lesson doesn't usually happen as often.
It might be hard for you to accept, but after you're sure you've gotten everything right and proceeded to ask for help and the same result occurs, then maybe the language is the problem and not your code. It's a possibility, and it can happen as we've seen above.
This is in no way to make the language less credible, it's maintained by incredibly skilled developers who put in a lot of time and energy ensuring everything works as intended.
But, this is to give allowance for faults and admit that at the end of the day, mistakes can be made. We're all human. Some features may not function as intended and it was accidentally added there, and some codes may not run the way they're supposed to and that's fine.
What's important is to learn from our mistakes, correcting them as we go on. In this case, if we're opportune to notice such bugs, we can use it as an opportunity to contribute to the developer ecosystem by identifying and correcting them.
Summary
This article talks about one of my many CSS debugging stories, highlighting key points in my experiences and the lessons I learned along the way. If you experienced a similar bug, let me know in the comments section down below. I'd love to hear your own debugging story.
I hope you enjoyed reading this as much as I enjoyed writing it. :) Thank you for your time, I hope you have a great day ahead, and I'll see you in the next article! 💛
Let's Connect!
The title was generated using Olubisi Idris Ayinde's article idea generator.