Recently I had to start using a new library. Every time this happens I feel like I tend to just do random things until it works. This time, however, I decided to monitor my process and see if there could be some order to my madness.
This isn’t a work of genius, it’s quite simple:
Get a functional example in your working environment
Play around with the knobs just to get a feel
Step back, evaluate and plan ahead
Iterate through the different tasks you have, slowly diving deeper into the documentation (the “spiral”)
Repeat steps 3 and 4 until the feature is complete
As part of our most recent feature, I was tasked to build a new component:
The feature is our smart event grouping (or “Magic Event Builder”). Basically we help our customers group similar events into more cohesive conversions, and in such a manner we provide better insights into their marketing efforts. From a developer’s point of view, this was a challenge due to custom styling, dynamic tooltips, varying labels (and images) according to event type, as well as a required smooth and “bouncy” feel for the bubbles themselves.
At Oribi we already use Highcharts quite extensively, so that’s why it was my choice (and why I won’t cover how to choose the right library). I had some experience building chart components, but this was my first time using Highcharts, so what did I do?
1 - Copy a working example
Goal: Integrate the library into your working environment
My first step is always to Google a few working examples. That’s how I get a feel for the library’s capabilities and how I try to find a good starting point. Eventually I found this example and I tried to copy the code.
This step usually helps me get over all of the hurdles of compiling/importing/making the library work in my environment. I usually find this step the most annoying but I try to treat it as a “band-aid.” As I said, we already use Highcharts so this was relatively easy.
2 - Start playing around
Goal: Have a crude working example and estimate what is going to be difficult
Once I have a working example, it’s time to play. I explore the exposed API, I change the values and I see what happens.
With frontend libraries I find that there are usually three pitfalls:
Styling the components
Getting the required functionality
Integrating into the app’s lifecycle
I have two main goals while playing around:
Get to know the different knobs the library exposes,
Gauge how difficult it should be to achieve the desired outcome.
I stop once I can roughly answer these two questions. So after a bit of playing around I reached this point:
As you can see, it's far from perfect, but that wasn’t the intent—I was able to answer my questions. After my short experimentation, I already had a good understanding of the knobs and I could tell (for example) that we would quickly be able to achieve the required feel for the circles’ movement.
Regarding how difficult it was going to be, I could already estimate what would be problematic. Two examples were the styling of each circle, particularly the hover effect, and building the custom tooltips.
3 - Take a step back and review
Goal: Create a list of small tasks to tackle one by one
Not much to explain here, but I do think this deserves a point of its own.
I think it’s important from time to time to pause, take a step back and look at the bigger picture.
Based on the insights from playing around, I made a general plan of how I was going to tackle the feature. I compared the desired end result with what I had and I broke the process down into subtasks.
Related to the issues we previously discussed, here were my subtasks:
Get the required feel for the circles’ movement (mapped as “easy,” but still a task)
Create a custom tooltip
Style the circles
Get the hover effect to work properly
4 - “The Spiral”
Goal: Get closer to the end result
At this point I put on my earphones, chose a good playlist and dove in.
I see the process as a spiral: an iterative process that slowly gets closer and closer to its target. So what are we iterating through? I have somewhat of a “nested-loop”: I iterate through the various tasks, while slowly diving deeper and deeper into the documentation.
I start with any task I feel like doing and once I make decent progress, I move on to the next task. Sometimes I completely finish the task, other times I move forward even if I don't reach 100%. The idea is to keep moving, achieve small wins and keep going. I try not to kill myself over stuff I can’t manage to get right after one iteration. Sometimes, while trying to solve the next issue I’ll find a new option I missed and it will help me solve the previous issue. In other cases simply putting it aside for a bit gives me fresh eyes when I come back to it.
Going back to the task list for the project, I tried to get the animation to a point I was happy with, and I managed to get a decent result without opening the docs. Then I moved on to the tooltip and finalized the design without connecting it to real data, and then I moved to styling the circles. Here I got a bit stuck and I opened the docs. This led to a few new ideas that I hadn’t thought of previously but nothing close to an end result. Before I got too bummed out I kept on going. The animation took another iteration or two, the styling took much longer, but there were other features that I managed to complete in one go.
5 - Rinse and repeat
Goal: Well… rinse and repeat I guess
I like to step back once in a while and evaluate my status. This usually happens at the end of the day, or before a check-in with my manager. I look at my progress, review the solutions I chose, and try to look at the full picture. Then, you guessed it, I dive back in.
As I mentioned at the beginning of this post, this isn’t necessarily a genius technique, I simply tried to analyze how I do things and share it. Looking at it written down I already have a few ideas for how to improve the process.
My main takeaway would be to find a good trigger to break out of the spiral and read the docs thoroughly. There were a few instances where I did just that and it really helped me move forward quickly. I think this is especially important when the library is rather complex or introduces a new way of thinking: examples that come to mind are D3 and Downshift.
Another takeaway would be to fully tackle a single task until it’s complete. As always, it’s a tradeoff, but I’m known to suffer from the “last mile” issue. For some reason I always have trouble bringing something to 100%, so maybe for me it would be smarter to try and focus on just one subject and bring it to completion. On the other hand, so far this has worked for me and I haven’t received too many complaints. :)
So how do you start using a new library? What have I missed? What do you find the hardest?