Read the docs. Every last word.
What I learned from reading the documentation for styled-components
Table of contentsWhy did I decide to read all the docs?Developing a docs-reading habitWhat I learnedThings I didn't know about SCattrsTransient PropsTest utilitiesSSG @import in `createGlobalStyle`Other things I learned by reading the docsInformation ArchitectureIdiomatic usageExtra readingConfidence
Before last week, I had never read all of the documentation for a technology from start to finish. I'm currently working through Josh Comeau's excellent CSS for JS devs course in which he chooses to use styled-components.And gives an excellent breakdown of the pros and cons of various styling choices which I won't reproduce here. I chose to use SC (styled-components) for this blog because I wanted to learn it—it's popular and I was seeking to understand the debates around CSS-in-JS by trying it out myself. But after installing it and learning how to add styling, I didn't dig much deeper. It turns out, I was missing out on a whole mental model.
Why did I decide to read all the docs?
I already knew everything I needed to about SC to use it. I knew how to style components
dynamically based on their props. I knew about the
createGlobalStyle function for, yep
you guessed it, creating global stylesThat temptation to roll your eyes
is how you know it was well named.. But occasionally I found myself doing
things I didn't like. I would create extra wrappers - unnecessarily polluting the DOM with
more divs - or sometimes style nested elements from a parent component. And although I
couldn't identify why I disliked it, I trusted my instincts and decided to find out what I
was doing wrong.
Also, in one of my interviews for a company I'll be joining soon, it sounded like they were considering adopting SC, making this the opportune moment to become an expert on it. And if you want to know everything about a technology, then you better have read the documentation, right?This isn't actually rhetorical. Mastering a technology takes more than just reading the docs. And reading all of the documentation is only as useful as the documentation is good.
Developing a docs-reading habit
I wanted to practice reading documentation. And the SC docs are relatively short, so this was a good place to start. They took me a little over an hour to read at a careful pace, so much less than an hour if you want to skim them. They are also organised. I didn't suffer from sidebar overwhelm.
Why get good at reading docs? Sometimes, reading the docs is your best, or only, option. In closed-source tech, you have to rely on documentation. And for OSS, reading the source may take a lot of time. That might be worthwhile if you're looking to contribute, but not if you just want to assess the api.
Also, I've never done it before. I've definitely claimed that I learn new tech by reading documentation, but realised when I heard Wes Bos say that he skims all the docs to get an idea of a technology's surface area, that I had never done that. So, instead of changing my narrative, I did the work to make it come true.
What I learned
I learned things about SC. I have a better mental model for how it works. I have a better feel for idiomatic usage—how to use the library as it was designed to be used. I know the surface area of the api, so if I come up against an issue, my memory will likely remind me that there's a method for solving it. And I now know about some gotchas with SSR, which I use on this blog, so I could apply that benefit immediately.
But I learned about other things by doing this too. Primarily, I developed my ideas about good documentation and information architecture; this is important if you're a dev and you need to write docs yourself.
Things I didn't know about SC
This is more for my reference, or for those who know SC and are curious.
.attrs() is a useful method I didn't know about. It provides a way for adding props to a
styled component. Use it when you want every instant of that styled component to have
the same prop(s).
How to use it is well documented in the basics section of the documentation. The api is
clarified in the API reference. What wasn't clear to me was when to use it—and when not
to. I had to find that out in the FAQs section. So that's another win for reading all the
documentation, but it also shows that I wasn't the only one unsure of the use case for
.attrs(). It is better to include these things in the main docs. Sections like Tooling
and FAQs are extras that most people won't be reaching.
Forwarding props is a useful pattern in React. In using it, however, we risk passing non-standard attributes to HTML elements. This will probably show an annoying warning in the console and nothing more. But accidentally forwarding the wrong prop to another React component could change its expected behaviour.
As of v5.1, SC allows you to prefix a prop with a dollar sign, marking it as for SC's use only.
Incidentally, look at how they highlighted which version this is available from. Definitely something to emulate.
It had never occurred to me that using SC could affect your tests. It's useful to know before using it in a serious application that the library itself provides some methods.
So reading the docs is clearly a good way to assess whether you want to adopt a technology at work because this prompts further research. Does it play nicely with our test suite? Is it easier to use with Jest than with Mocha?
SSG @import in
The docs recommend - again in the FAQs instead of somewhere more prominent - that we don't
@import in the
createGlobalStyle function "due to some issues with how browsers
process @import via the CSSOM APIs."
I can easily imagine doing exactly that - why would I not? - and spending hours, if not days, trying to work out what had gone wrong. Now, I am forewarned.
Other things I learned by reading the docs
We compartmentalise information into need-to-know and nice-to-know. How you structure your docs will tell readers what to learn and what they needn't bother with.
Some information that I would consider very useful is relegated to the Tooling and FAQs sections, both of which feel optional. I would bet that Frequently Asked Questions is not a frequently visited section. Following JC's example on his excellent blog - and course platform - it's better to disclose additional information about something immediately, rather than in a link to an external section. You can progressively disclose with an accordion if necessary.
The Babel plugin is a good example. While not essential for usage, it is essential for debugging. I don't recommend foregoing it unless if you have the choice.
All software is designedIdeally. In theory. At least a bit. Even if thoughtlessly. Oh, just go with it.. If you're using something in a way that is never documented by its authors, you may be slipping into some unidiomatic usage. Have you come up with a clever way of adapting something for your use case, or have you just invented a foot-gun?
The docs won't be exhaustive. They're quite unlikely to tell you everything about how the tech works, for instance. For that, you may have to go to the source. Fortunately, in this case, I have JC to help again! SC also includes a list of further reading articles on the website, which is a really great practice that's much appreciated.
Reading the docs will answer most of your questions, but it might raise new ones. Follow your curiosity 🌈
The more you understand about a technology - how to use it, all the things it can do, and how it actually works - the more confident you will be in using it. A big part of development is stitching pieces together. If you don't know exactly where the boundaries of those constituent parts lie, then debugging issues can be very tricky. "Is it a React, Next, SSR, styled-components, TypeScript, Babel or Webpack issue?"
You can also contribute better to discussions at work about what tech to use and why. And if you're already using it, you'll be better at teaching others on your team. Win win win!