11th week of 2021
Safari problems, Clojure exercises, cool feature in Firefox DevTools, 4 types of documentation.
Table of contents
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
object-src 'self'; to the CSP.
Interesting that other browsers don't require that setting.
Investigated another issue
concerning only Safari (desktop + mobile):
an SVG file,
loaded via an
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
instead of loading it via an
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).
Last week I began doing TypeScript 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.
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:
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.
Also check out Elijah Manor's video explaning the feature.
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:
- 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:
- Deep dives
I can't wait to get some time at work to update our documentation to have a clearer distinction between the four types. 😋