11th week of 2021

Published on

Safari problems, Clojure exercises, cool feature in Firefox DevTools, 4 types of documentation.

Table of contents

👨‍💼 Work

Safari: "Blocked plug-in" when opening PDF files

Investigated an issue concerning only desktop Safari: when opening a PDF link so that the PDF file is opened in a new tab, Safari didn't display the file. It instead just showed the text "Blocked plug-in." The user could download the file to view it, but that would be cumbersome.

I did some quick googling but didn't find any good results.

Then I noticed that Safari's console showed an error message related to Content Security Policy (CSP).

In the end, the fix was to add object-src 'self'; to the CSP.

Interesting that other browsers don't require that setting.

Safari: broken CSS-animated SVG files

Investigated another issue concerning only Safari (desktop + mobile): an SVG file, loaded via an <img> tag and animated using CSS, was rendered in a very buggy way in Safari. Some parts were missing and some parts were distorted.

I did some quick googling but didn't find a clear cause. I did find some speak of something along the lines of "Safari is bad at rendering SVGs."

In the end, the fix was to inline the SVG file, i.e. render it directly via an <svg> tag instead of loading it via an <img> tag.

The downside is that now the file can't be cached by the browser. Luckily there's only one such file (at least for now).

👨‍🚀 Personal

Clojure exercises on Exercism

Last week I began doing TypeScript exercises on Exercism.

This week I switched to doing Clojure exercises on Exercism.

I have received mentoring from Amir Barylko, which has been very helpful since I'm just starting out with Clojure. Otherwise it would be too easy to learn poor practices.

And yes, I know that my motivation to do the TypeScript exercises lasted for a very short time. 😄 I have at some point realized that my motivation comes and goes in waves. Instead of fighting that, I embrace it.

👨‍🎓 Learnings

CSS: Firefox DevTools can explain why some styles have no effect

It's frustrating when a CSS declaration is technically valid (not crossed out in the browser's DevTools) but has no effect for some reason. Turns out that Firefox DevTools can often tell you why and also how to potentially fix those issues!

Starting from Firefox 70 (released in October 2019), its DevTools contain "inactive CSS rules indicators" that explain why some styles have no effect:

Firefox DevTools' inactive CSS rules indicator. Here it's saying that "width has no effect on this element since it has a display of inline. Try adding display:inline-block or display:block."

I use Firefox as my daily browser, but usually switch to Chrome when doing web development because Firefox DevTools often feel buggy. Good to know that Firefox DevTools can be very helpful in these frustrating situations.

I learned this trick from Josh W Comeau's CSS for JavaScript Developers course (Module 0).

Also check out Elijah Manor's video explaning the feature.

🕵️‍♂️ Cool stuff

4 types of documentation

Daniele Procida's documentation system splits documentation into four types.

  • Tutorials are learning-oriented; they teach how to get started.
  • How-to guides are problem-oriented; they guide how to achieve a certain goal.
  • Explanations are understanding-oriented; they clarify a certain topic.
  • References are information-oriented; they describe the system and how to use it. (E.g. what methods are available, what parameters they take and what they return.)

The four types are quite similar to each other. But if you don't realize that there are these different types of documentation, the types get mixed very easily, and the documentation gets messy.

From the related discussion on Hacker News, I learned that there are other types of documentation as well. For example:

  • Introduction
  • Announcements
  • Case studies
  • Code samples
  • Release notes.

These types might fit into one of the four categories, or they may not.

Another good point from the HN discussion is that the different types may have different names. For example, explanations can also be called:

  • Backgrounds
  • Deep dives
  • Discussions
  • Overviews
  • Rationales.

I can't wait to get some time at work to update our documentation to have a clearer distinction between the four types. 😋

💁‍♂️ More Weekly log entries

Next week: 12th week of 2021

Previous week: 10th week of 2021