In the agile world, with dynamic requirements, large projects might need a revamp for numerous reasons. The need for a revamp might arise to improve performance and thereby user experience, to upgrade some libraries that have security vulnerabilities, or to remove certain libraries which are no longer supported and port to new/better libraries. Rebranding might require revamping as well. As products scale, cost optimization might need revamping. Revamps are also frequently driven by a need to merge multiple applications into a single app, usually internal-facing apps. With multiple such reasons overlapping, my team and I had to revamp some projects in the last few years. Here are some of our learnings with the challenges we faced.
Moving to a design system
Business temptations for shipping optics and associated operational hazards
Content architecture vs design changes vs simultaneous content and design changes
Dependencies that broke us
Developer experience
Moving to a design system
One of our projects involved an admin panel for a product suite of 5 products. The product suite is a SaaS offering. The admin panel for end users had StyledComponents. Moving to a design system - standardising all components meant great time savings for the long term. However, that implied porting an existing code base of 25+ man-years.
We found a sweet spot where we migrated component by component to the design system. Very small PRs where every PR involved changes from only 1 page for only 1 type of component made code review, testing and UX review easy. The new design system had a theme that styled the new components similar to the old implementation. The idea is to switch the theme after all components are migrated. That way, the new design release is a large change visually, but a small code diff on the day theme is flipped.
If such small code is not shipped often, the branches become stale, and in a large team that ships new features often, rebasing becomes a large task in itself. Hence the need to ship as often as possible.
Business temptations for shipping optics and associated operational hazards
Business teams demand large releases that are good optics for marketing. However, those come at a risk. The users using the app face challenges when there are large changes. Large shipping could cause an increase in support tickets if there’s any confusion during app usage, specially from the internal stakeholders. When there are content architecture changes, during release, a different set of fields is required for the old vs new versions. The new fields could be derived from the old ones, hence the need to maintain the old fields for a while. Such old fields become a tech debt and have to be removed later.
This brings to another aspect - whether the changes are graphic design changes or content architecture changes or both.
For CMS-driven large static websites we developed, for changes involving such old redundant fields, and a large number of new fields, having Storybook updated enabled the content managers to check the old and new components on Storybook. We’ve been using Chromatic for the past few years, and it has helped us enable content managers to quickly experiment with components.
Content architecture vs design changes vs simultaneous content and design changes
Often, designers creatively add more fields to the UI while redesigning. This mixes two tasks up - graphic design change and content architecture.
Separating graphic design changes and content architecture changes helps. Content architecture changes need to be shipped extremely small. Whereas large graphic design changes could be made in large releases.
Dependencies that broke us
NextJS shipped a stable app directory/app routing. We used a CSS-in-JS library ChakraUI. This library does not support app directory and only works with client-side rendering if used in app directory. If we would have used TailwindCSS, this would not have happened. However, using TailwindCSS, and building components with some other library which would facilitate accessibility would have taken more time (Radix is one way to use primitives and use TailwindCSS). The trade-off of using ChakraUI paid off in the first few years of the project, but now is a blocker for upgrading NextJS and using new features NextJS offers. Another roadblock is that the ChakraUI plugin for Storybook does not support newer Storybook versions. Essentially, we’ll need a complete re-write to exit ChakraUI at some point.
In one of our projects, we used a navigation library - navi. This library stopped supporting ReactJS v17 onwards. We had to fork the library and upgrade it since it is no longer supported. While the dev team might want to take some risks and use libraries, when such libraries aren’t supported in newer versions, replacing such core features require large refactoring.
Developer experience
When setting up a project, prettier and eslint need to be the priority. Missing these out, and enforcing rules later is expensive. Having these set during the project setup makes it easier to onboard new developers. Instead of maintaining documentation or addressing formatting rules during code reviews or memorising rules without documentation, setting up prettier and eslint enforce rules on the codebase, using IDE/IDE plugin features. This saves time and reduces developer fatigue as well as irritation.
While some teams consider writing types/interfaces in TypeScript an unnecessary overhead, when building large projects, knowing types really helps in knowing what might break during development instead of runtime. The learning curve associated with learning TypeScript isn’t much, and GitHub Copilot has made things easier as well.
Comentários