Addy works on the Chrome Developer Relations team at Google, building and advocating for tools to help improve developer productivity and satisfaction.
Components Should Be Focused, Independent, Reusable and Small (FIRS)
Whether it’s a client or server-side component, a Node module or a piece of visual UI, components that are large are inherently more complex to maintain than those that are small.
In fact, the secret to efficiently building ‘large’ things is generally to avoid building them in the first place. Instead, compose your large thing out of smaller, more focused pieces. This makes it easier to see how the small thing fits within the broader scope of your large thing. These concepts apply to existing ways of doing things, including Web Components.
Focus and modularity has worked to some degree of success in the Node community and is equally as valuable across other parts of our field for a few reasons:
Smaller APIs are easier to learn and teach to others. This is generally helped if you do one thing and do it well.
Code reuse can save you time. Reusability in itself is often a side-product of writing code that happens to be well structured and well defined. It does help when you can just drop in an existing component vs. writing one from scratch. You’re likely to discover flaws in the original design that you improve on over time, but the more your component is reused, the more you fix these flaws, improving reusability.
Improved composability. This means new components can be built by extending existing ones. This again allows for a great deal of code reuse, avoiding re-implementation of the same functionality across projects.
An increase in maintainability is possible thanks to a reduction in complexity. By splitting out a component into something smaller, it’s generally easier to test and document. Keeping your component source DRY can help.
Separation of concerns. If each component addresses a specific concern, this simplifies the update cycle as one component doesn’t always need to know the details of others. Note that separation of concerns does not always equate to separation of technologies. Keeping logical, related parts of a system together can make it more easy to understand and maintain.
Simplified debugging. This is more implementation specific, but granularity should make it more straight-forward to identify and fix problems by making it simpler to determine the true source of errors.
Easier understanding of your large system as you’ve broken it into smaller, more well grained pieces
On the whole, approaching components with modularity and a focus in mind increases reuse, eases maintenance and improves extensibility. Diligence does need to be taken with making something ‘focused’ however.
If you’re building components to be shared with the community or even just your team, ask yourself if features in your API will be used by 90% of users. If so, it’s likely pretty core functionality and should stay. If a feature it going to be used by the 10%, it should probably be a separate component or module. Avoid code bloat.
Some may read this and think, “Great!.. but practically speaking modularity from the get-go is not always possible”. This is fine. Some developers find it more feasible to build an integrated solution first and then extract out useful modules. This can save time on public interfaces that might turn out to be wrong, but ultimately leads to the same end-goal: having a collection of components that can be reused in future projects.
When you’re trying to build a component, whether it’s visual or non-visual try to keep in mind four things:
Keep it (F)ocused.
Keep it (I)ndependent.
Keep it (R)eusable.
Keep it (S)mall.
or in short FIRS.
With thanks to Pascal Hartig and Stephen Sawchuk for their reviews.
Writing is hard. Let's go shopping.
“The first draft of anything is shit.” — Ernest Hemingway
My earliest experiences writing technical articles for the web were pretty atrocious. Years before I wrote any books, I was an engineering student. I lacked writing experience, had impostor syndrome and my resume was a YouTube video of me doing the Macarena for 12 minutes. This could probably have been enough to get me into the White House, but made it difficult to know where to start in the world of authoring articles around programming.
One of the biggest mistakes I made early on was not seeking outside advice on what I was writing. Technical reviews, regardless of how critical, are an essential litmus test for content you intend on sharing with the world. That cannot be stressed enough. Imagine if Guns N’ Roses were writing Paradise City today and didn’t get a sanity check before releasing new songs? We’d end up with “Take me down to the hipster city where the grass is green and the girls don’t even”. No one wants that. At least, I hope not.
When I began writing, I drew inspiration from popular tech blogs at the time and so my titles would look like “I Learned How To Write Clickbait Titles. What I Learned May Amaze You”. Or equally as Pulitzer prize worthy, “50 Ways To Do This One Thing. You Don’t Need 48 Of Them But Sssh”. It’s been a few years since and I’ve attempted to correct my ways but titles and post structure remain a difficult beast to get right. Go overly academic and your audience may not read what you have to say; go too click-baity and you’ll feel dirty and likely lose the respect of those that would prefer you being more direct. It’s best to keep your titles short, sweet and to the point where possible.
Another challenge I ran into was grammar and attempting to reduce the complexity of what I was saying. If the average person can appreciate at a high-level the gist of your article, you’ve done something right. This is probably unfeasible for a lot of technical content that requires context, but keep in mind that lowering the barrier of understanding is generally useful. I mean, it’s not like the English language is evolving at great speed. Now that “twerking” and “selfie” are in the Oxford dictionary, we can probably return to beating our chests and hitting things to communicate.
Pictures. We should talk about pictures. Lacking sufficient context to write about some topics in detail, I would follow suit from other tech bloggers and try littering images and screenshots between my text to balance them out. Ooof. That was bad. The problem with this is that visuals should be used liberally and only when they add to the overall message you’re trying to convey. They shouldn’t be used “just because”. Pro-tip: Don’t post screenshots of your phone if your battery percentage is low. It’s hard for people to focus on the picture because your low battery stresses them out and basically makes you the worst person ever.
Next tip, be careful on escalators. I once tripped and fell down the stairs for two and a half hours. Perhaps that tip should have been, “keep it relevant”. You would be surprised just how easy it is to go off on a tangent when your goal is to get across a few succinct points.
I could fill pages with the mistakes I’ve made over the years trying to improve my technical writing skills. The last tip I’ll share today is to check your facts and always cite your sources for data. For example, interesting fact — 80% of people inside VIM have no idea how they got there or how to get out. We all assume that has to be true, but if this was a real piece of technical writing, the source of this data should be fact checked and cited.
So, in closing, go write something! Sit down at the keyboard and you put one word after another until its done. Don’t be afraid to share your thoughts and experience with the world. We need good technical content out there and although you’ll undoubtedly make mistakes, we all do.
Choose tools you'll use.
Learning about the front-end can seem like a daunting task these days — especially if you’re a beginner. It’s easy to feel like you have to master a thousand different tools and technologies just to get started. The good news is, this isn’t the case.
As your familiarity with these languages improve, you can then add tools and abstractions into the mix when you’ve confirmed they improve your productivity and help you manage complexity.
Signed — someone who burns most of their calories at the gym untangling headphones.
Deal with something once
If a task can be done in less than two minutes, do it right now.
I find myself consciously procrastinating more than I would like. I’ll read an email, a GitHub issue or pull request and think “I can come back to this later. I’d rather just code”. Over time the items on my mental to-do list start to build up until I have a decreasing hope of ever getting them complete.
You see, to-do lists are like a burrito. If you fill it with too many things it falls apart and then you cry and they kick you out of Chipotle.
This week I’ve started trying to change that. Rather than saying “later”, if I really mean to get back to something, I’ll deal with it right away. Even if it means the reply or review is shorter, at least the task gets pushed on a little and I’m not a bottleneck for progress. I want to start dealing with things immediately.
There’s this story I recently read about Susan O’Connell — a Zen Master who’s taught the “deal with it only once” principle.
One of her students was meeting with her and they talked about getting tea sometime soon. Rather than dealing with it later, she pulled out her notepad and set a date right then and there. Her idea was that you should deal with something only once. Do it now. Once done, it’s off your mind and you can fully focus on the next matter at hand.
There isn’t really any science behind this. A lot of us will say “I can decide on that or reply to that later” to many of the tasks we end up each day, but we put them aside for later. Avoid putting off those small decisions so they don’t weigh at the back of your mind.
If you read an email, write a quick reply to it right away. Don’t let it sit there. Add thoughts, even if brief, to ongoing pull requests. Schedule those meetings you really want to get into your calendar.
Related is another useful rule I’ve read about by David Allen — it’s called the two-minute rule. If a task can be done in less than two minutes, do it right now. You could stretch that to five minutes, but it just means one less thing to worry about.
Take actions, move onto the next thing, rinse and repeat.
I hope that some of this has been useful. If not, I apologize. I decided to deal with this post once and now must return to the rest of my to-do list:
[ ] Find out why “apps” isn’t short for “appetizers”. Why would I buy a phone if it can’t download nachos?
[ ] Say “your right” to the next person that argues with you. They’ll think you said “you’re right” but you didn’t. So, you win.
Front-end Choice Paralysis
A problem we regularly face in this industry is an abundance of choice. We have a plethora of tools, frameworks, languages, abstractions and platforms. Choice is ultimately good for competition and innovation, however when faced with too many choices, we can feel paralysis. Rather than making a choice we feel frozen and alone with the indecision of having too many options in front of us. This isn’t necessarily an industry problem — it’s a human problem.
Take the simple idea of streaming a movie on Netflix.
Over the weekend, I was determined to watch a movie on it. I’d set aside two hours, which I thought was sufficient to select and play something.
What I didn’t realize was that it had been a while since I had last performed this exercise. The Netflix catalog had introduced (what felt like) hundreds of movies since my last break and so I started browsing. And browsing. And browsing. Watch Twilight! Or 2. Or 3. It’s the timeless tale of a girl who has to choose between ripped abs or clingy dependency. Watch Avatar! It’s like the Blue Man Group go to Jurassic Park.
There were so many choices and I felt flustered. In short: choice paralysis set in. It took me an hour to find a title I felt comfortable watching and I barely got half-way through before my time was up. My subscription now feels like one of those abusive relationships people are afraid of leaving.
Psychologist Barry Schwartz covers this phenomenon topic well in his 2004 book The Paradox of Choice, where he argued that by eliminating too much choice, you can reduce the amount of anxiety felt by shoppers.
He summarized a very relevant jam experiment by Sheena Iyengar and Mark Lepper as follows:
“When researchers set up [in a gourmet food store] a display featuring a line of exotic, high-quality jams, customers who came by could taste samples, and they were given a coupon for a dollar off if they bought a jar. In one condition of the study, 6 varieties of the jam were available for tasting. In another, 24 varieties were available. In either case, the entire set of 24 varieties was available for purchase. The large array of jams attracted more people to the table than the small array, though in both cases people tasted about the same number of jams on average. When it came to buying, however, a huge difference became evident. Thirty percent of the people exposed to the small array of jams actually bought a jar; only 3 percent of those exposed to the large array of jams did so.”
The challenge is that when presented with an abundance of choice, you can feel increasingly unsure of whether yours is the right one. Instead of being happy with our decisions, we’re filled with anxiety. Did I pick the wrong one? Would I have been better off with something else? What would my friends have used? Should I ask them? I don’t want to seem stupid. We’re stuck in a rut pondering whether we’ve missed an opportunity for something better. How many times have you second-guessed your technology stack?
When you’re given too much choice you can also end up increasing your expectations. Maybe you feel that if you hold out, you’ll find the ‘best’ one. The unicorn in the herd. Clearly, with so many options to choose from, the correct choice must be amazing. Often, however, on discovery of what the ‘correct’ choice is like we can feel unfulfilled. Such high expectations are difficult to meet, leaving us in a state of unquenchable dissatisfaction.
We need to start getting realistic with our expectations. Competition can coexist happily, but perhaps the developer with a passing interest in a tool or framework benefits more from limited choice (something highly opinionated) whilst the person with a keen interest and more experience with some of the options available benefits from a broader selection.
If you’re an experienced developer speaking to someone stuck on a decision, try to help them simplify their options. It’s a freeing experience and may help narrow down their choices to something that doesn’t feel so daunting. Even taking a few off the potential list can give them an opportunity to get more clarity and choose something they can at least evaluate before making a final decision.