#161

📝 A Note on Note-Taking

(Robin) When a codebase is still new and unfamiliar (and scary!) one of the best ways to learn about it is by taking copious notes. At Gusto, we take extensive notes of what features we’d like to ship next, what problems we might come across, and how we should tackle refactoring a component.

Note taking for our team is important because up until pretty recently the difficulties of our front-end codebase was very much siloed. Only one or two people knew how and why our form components worked the way they did, or how our styles loaded in the peculiar way that they do.

But I’ve noticed now that the Design Systems team is a fully-fledged team that all these public notes are starting to make an impact. Now everyone on the team has a pretty good understanding of what we should focus on next because we can see the challenges that everyone bumps into on a daily basis.

Our team makes alls these notes in Notion which I’ve fallen completely in love with:

Chris also made some notes a while back about how he’s been using Notion which is super interesting. Sarah detailed how she uses Notion in a post called “Prioritizing“:

I like to use the weekly planner in Notion. I’ll take all the things I think I can get done in a week and break them down day-by-day, based on when it makes the most sense to do each task. When I finish a task, it’s dragged to the top. Anything that’s unchecked at the bottom by the end of the day moves over to the next. I also have general to-do lists, and task-based lists, but the weekly planner is my holy grail. Again, you don’t have to do it exactly like I do, find what works for you.

So Notion is definitely a great tool to organize both what you’re doing and what you’re thinking about. Going back to front-end specifically for a moment though — all this reminds me of a post by Chen Hui Jing on how she tackles new refactoring projects:

Before diving into the code proper, I did a basic click-around, to get an idea of the look and feel of the site, and what it did. To me, this was a pretty important step, because you can only encounter a site for the first time, once in your life. And I took notes. Notes on things that took me a while to figure out, places where I had to ask “hmmm, now what does this even mean?”, functionality that required extra cognitive effort to comprehend.

This is a wonderful idea! I can’t count the number of times I’ve started a new project and joined a team only to have fallen into the codebase head first and immediately become lost and upset in a sea of weird and confusing nonsense.

The reason I love this post by Chen is that we can use that confusion to our advantage! By jotting down all those HUH? and WAH!?? moments we can help ourselves out in the future. Because if we’re confused by this one tiny thing in the codebase then it’s probably causing issues elsewhere for other folks, too.

If we use that initial confusing state of mind to our advantage then we can help other people and get a good sense of all the issues and troubles without letting it get to us.

Yay for note-taking!

🔗 Links from around the web

Google has launched an interesting feature called Paint Holding and it’s available to test in the latest version of Chrome Canary. Addy Osmani has the scoop:

For a while now, Chrome has eagerly cleared the screen when transitioning to a new page to give users the reassurance that the page is loading. This “flash of white” is this brief moment during which the browser shows a white paint while loading a page. This can be distracting in-between navigations, especially when the page is reasonably fast in reaching a more interesting state.

It sounds pretty neat! I wonder if there could be a bit of an accessibility issue with this though — for similar-looking pages it might not be entirely obvious right away that the user has navigated to a different page.


I really enjoyed this interview with Jeremy Keith on the state of the web, how things have been changing for developers lately and what effect that has on everyone that uses the web.

At one point Jeremy talks about how many people think that websites are annoying and frustrating. This reminded me that I cannot count the number of times when someone has said to me, “Ah, I can’t view this website on my phone.”

I looked at a very prolific news website the other day and was thoroughly annoyed by the bad typesetting, the slow performance, the janky scrolling, the newsletter modals, cookie toasters and a variety of other popups that jumped out at me. I caught myself thinking about why native apps don’t have this problem; why are we okay with adding so much unnecessary trash to a website?

However, my quick thought on this is that we shouldn’t become sour and pessimistic though. We should roll up our sleeves and get to work because clearly there’s much left to do.

📕 From the Blog

Multiplayer Tic Tac Toe with GraphQL

Rishichandra Wawhal walks through what GraphQL is (and all the developer experience improvements that comes with it) and then shows us how to build our very own Tic Tac Toe game.

If you’ve never worked with GraphQL and you’re interested in learning more, then this is a pretty wonderful tutorial to start with.


Advice for Technical Writing

“Write the article you wish you found when you googled something.” That’s Chris’s first piece of advice for getting started with technical writing but I really love this bit, too:

The moment you learn something is the best time to write. It’s fresh in your mind and you can remember what it was like before you understood it. You also understand what it takes to go from not knowing to knowing it. That’s the journey you need to take people on.

If you don’t have time, at least try to capture the vibe wherever you save your ideas. Don’t just write down “dataset.” Write down some quick notes like, “I didn’t realize DOM elements had a .dataset property for getting and setting data attributes. I wonder if it’s better to use that than getAttribute.” That way, you’ll be able to reload that realization in your brain when you revisit the idea.

This is another good reason why we should all take furious notes of things! Also this type of writing is by far the best way to learn something I’ve found.

My quick two cents would be this: don’t write for an audience! Write for yourself in six months time when you’ve completed forgotten about whatever this problem happens to be. That way, you won’t be too worried or nervous about the best way to describe things.


Can you view print stylesheets applied directly in the browser?

I had no idea you could do this and it’s right there in DevTools. Chris shows how to check them directly in all major browsers:

This is bound to be pretty useful for an upcoming project!


Draggin’ and Droppin’ in React

Maks Akymenko has made some notes about how we might go about adding drag and drop functionality to a React project and walks us through how to do that with react-sortable-hoc. Oh and this is the demo he shows us how to build:

In the docs for react-sortable-hoc the team describes the issue like this:

…most […] libraries rely on the HTML5 Drag & Drop API, which has some severe limitations. For instance, things rapidly become tricky if you need to support touch devices, if you need to lock dragging to an axis, or want to animate the nodes as they’re being sorted. React Sortable HOC aims to provide a simple set of higher-order components to fill those gaps. If you’re looking for a dead-simple, mobile-friendly way to add sortable functionality to your lists, then you’re in the right place.

Learn more →