DEV Community: Michael Mangialardi

Treating AI Chats Like Git Branches

Michael Mangialardi — Fri, 07 Feb 2025 16:32:39 +0000

As a developer, I'm used to solving problems by composing many functions to handle one step in the solution. Solving problems via an AI chat introduces a new experience: dialoguing through a problem and its solution.

This open-ended experience of interacting with an AI chat requires the imposition of verbal "tools" to mimic structured functions, libraries, etc.

In this article, I'd like to show how I've imposed prompts to harness and organize my knowledge management mediated through AI chats, especially Claude.

Before I imposed any prompt structure, my AI chats would go like this:

Introduce a subject/problem/question
Make connections with other subjects/problems/questions
Get into the weeds of the connection between the original topic and the new one and miss the big picture (the structure and interconnection of the conversation)
Leave the chat session feeling stimulated with new ideas/thoughts/impressions but not being able to return and retrieve the knowledge quickly

Here's what I did. In short, I used prompts to treat every AI chat session like a git branch.

Every chat session has some subject/problem/question/theme. In other words, every session can be given a name corresponding to the holistic intent of the session. In git terms, every session is a "branch" that can be given a specific name to provide a baseline.

As with every git branch, a chat session delves into specific steps/dimensions of the initial problem.

The power of good commits is that they leave breadcrumbs demonstrating the logical unfolding--in short, the history—of a solution to the problem. More generically, we can say that commits trace the developer's mind as a theme is explored. Good commits are helpful not only for reviewing a branch in retrospect, but the discipline of creating them helps build awareness of the developer's approach/design.

Likewise, AI chat sessions could benefit from retrospectively examining the conversation's logical evolution. Moreover, creating session "commits" facilitates the discipline of awareness and organization of thoughts in a discussion.

When a git branch is completed, the code may be reviewed. Comments may be added to provide another layer of context/insight. Similarly, additional context/insight can be extracted within an AI chat session regarding a) the "commits" and b) the overall "branch."

While there isn't an industry-standard tool/interface like there is with git, a user can impose prompts to structure the workflow of an AI chat session to mimic that of a git branch.

There are many ways to do this, but let me showcase the prompt system I imposed on Claude.

Every time I enter an AI chat session, I name the chat, mimicking a branch's name and capturing the session's high-level goal/theme.

Then, I note the intent to work on a "commit" within the branch before diving into a new connection using this prompt:

Create a branch point marker. We're moving from [original topic] to [new domain].

Key context to preserve: [please generate]”

Example Output:
=== BRANCH POINT: [New Domain] ===
- [ ] - Original topic: 
- [ ] - Connection point:
- [ ] - New exploration:

This is a "commit message" that transitions from one commit to another—in other words, from one logical exploration of thought to another. I use the term "branch marker" instead of "commit" to better fit my mental model (since I have more control of this than git's interface/terminology).

That way, I can create a logical history of my progression through a chat.

Note: This begs the question of when to distinguish between a connection or tangential point within a logical group of thought (a "commit"/branch marker) and a new logical group. This depends on your preferences, intuition, and the nature of the theme/session. The significant point is to leave some organized trace of the different "chunks" of thought in an AI chat session.

Just as you would with git, you can check the "commit"/branch marker history in your AI session:

Can you (in text) list all our branch markers, including the next one?

Which may produce:

// output
Chat: Philosophical Realism
Branch 1: Plato's Realism
Branch 2: Aristotle's Moderate Realism

Moreover, just as you can use git hooks to do extraordinary things after a commit, I use each branch marker/"commit" to do things like aggregate notes from that chunk of thought:

One more thing before we move on to the next branch, can you create some summaries on those connection points that would make for formal notecards in my Zettlekasten system?

Once I've wrapped up a session, I do something equivalent to a git push hook to do end-of-session cool things:

"Please aggregate all zettelkasten cards from this chat in two formats:

A readable summary organized by branches, showing:

Branch name/theme
Each note's ID, title, and content

And notes in this format. Example Output:


const notes = [
    // Branch 1: Clarifying Aquinas
    {
      id: '202501261',
      title: 'AQ-ConscienceScope',
      content: `Natural law encompasses both moral principles discoverable by reason (synderesis) and broader principles of human flourishing. Aquinas distinguishes this from moral law, which specifically concerns divine commands and moral obligations. Natural law is thus broader, including practical and civic virtues alongside moral virtues.`,
      tags: 'aquinas,natural-law,moral-law,virtue,conscience'
    },
]"

And:

"Please create a complete branch index from all branch points and suggest an appropriate chat name."

Therefore, at the end of each session, I have:

An outline/index of each "commit"/branch marker
Summaries on main notes/thoughts in each branch marker
A final chat name (if I need to change it)

My final step is to update the branch/session name to be prefixed with (Complete) so that if I return to that chat session, I can expect to find an index and summary notes at the bottom to get right back into the swing of things.

To simplify this process, I use Mac keyboard shortcuts so that my standardized prompts can feel like entering commands into a terminal, as with git.

You can create your aliases/interface to invoke the prompts using keyboard shortcuts, giving you the potential to either copy the git interface verbatim or improve upon it.

In conclusion, version control and git concepts have applications beyond code. AI chat sessions are a perfect example where imposing these concepts can streamline a process for better extracting knowledge from interactions with AI.

If you have a similar workflow, let me know in the comments.

Does this engineering culture suck? (How to find out before you take the job)

Michael Mangialardi — Fri, 15 Jul 2022 18:41:12 +0000

Interview the Company

If I were to go on LinkedIn and search "UI developer," I would find a plethora of jobs with almost identical job descriptions.

However, each job could have a very, very different engineering maturity in its culture that could make or break your experience there.

So, how do you avoid entering into a bad engineering culture?

You have to ask questions to draw this out upfront.

Don't let the 5+ rounds of interviews with technical challenges fool you. You are interviewing the company as much as they are interviewing you.

Before you take a job, make sure to ask good questions that give you a sense of the engineering culture. It can be a bit illusive to know what to ask, so I'll give you some pointers:

Questions to Ask

What is the acceptance criteria for a branch to get merged into main?
🚩Red flag: No mention of making sure the code reaches a quality threshold based on determined standards/practices.
What is technical debt and how does this team address it?
🚩Red flag: Very abstract conversation, nothing actual process to point to.
Can you tell me the difference between tactical and strategical development? Where does this team lie on the spectrum?
🚩Red flag: Unable to understand the question.
Why are professional goals important to work towards in addition to releasing features? How does the manager take this responsibility upon themself?
🚩Red flag: Very abstract conversation, nothing actual process to point to.
What are the roles and responsibilities of engineering leads and engineering managers? How do the two roles differ?
🚩Red flag: The roles don't differ, and one person is doing both.
Can you show me an outline of an example 1-on-1?
🚩Red flag: Very abstract, nothing concrete to point at.
How do you distinguish between the different levels of engineering maturity between teammates when assigning work?
🚩Red flag: There is no distinction between levels of maturity.
How does this team aim at maintaining good talent amidst their developers?
🚩Red flag: They haven't really thought about it.
Can I explore some of the codebase?
🚩Red flag: They won't let you.
Who determines the product roadmap and what pushback do the developers have to negotiate time for technical improvements/vision?
🚩Red flag: An abstract answer.
If I want to be the best possible engineer I can, why would I join this company?
🚩Red flag: They won't let you.

Many more questions could be thought of, but hopefully this gets you thinking on the right track.

If you want to get your brain juices flowing even more, I highly recommend reading this book on software philosophy.

Looking Out For Tactical Tornadoes (Why Product People Should Also Care About Quality)

Michael Mangialardi — Thu, 14 Jul 2022 18:55:30 +0000

A mature engineering organization possesses a software philosophy where saying no is commendable.

If there is a deadline or some sort of higher-up-pressure to deliver software within a tight scope, a mature engineering culture encourages to say no to such pressure if it compromises code quality.

If I were to go on LinkedIn and apply for a variety of jobs that came up when I searched "React developer," I would guess that most of the job descriptions would appear almost identical. However, each role could significantly vary based upon the engineering culture.

Truth be told, some engineering cultures are heaving "tactical." The main virtue is being able to deliver features as quickly as possible.

Developers that deliver very fast are enshrined by management as heroes, but the other developers think otherwise.

In a word, a tactically-minded engineering culture says yes to too much, takes shortcuts, and fails to think of long-term implications in a pursuit for short-term efficiency.

The code is becoming complex and needs refactoring, and a tactical approach says: "We can do a patch and get this delivered. We can always refactor later." Patch after patch the code spirals out of control, adding a level of complexity that slows down efficiency for the long-haul and produces a codebase that mature engineers (the one's you actually want on your team) don't want to contribute to.

This, in a nutshell, is a "tactical tornado."

What does this mean?

Engineers must think about the long-term consequences of their code on the developer experience.

There's a common camping maxim of "leave no trace."

Is it a big deal to leave a banana peel on the campsite? It's just a banana peel!

Well, yes--it is a big deal. The reason being that if one person sees that it's ok to leave a banana peel, then everyone thinks it's ok to leave behind a few scraps. Before you know it, everyone is leaving scraps and the campsite is a mess.

This maxim equally applies to software development

As with life, engineers should consider their legacy. Do they want to leave behind a messy, complex codebase for the gain of delivering faster for the short-term?

No. Developers should think beyond just writing code that works and instead writing code that follows good designs.

Good designs are not complex. They do not create unneeded dependencies and obscurity.

The code is easy to follow and easy to contribute to.

Good designs improve efficiency because they the code is easier to contribute to, and it prevents more mature engineers from jumping ship.

However, in the short term, good designs require deliberation--extra work, extra time.

This means that a quick patch is a big deal and should be said "no" to.

On the side of product management, mature yet efficient (thinking both in terms of short and long-term) developers should be encouraged and celebrated--not those who get work done the quickest.

Product people should understand the implications of bad software designs and how those do affect the bottom line in the long haul. To not understand this, and to not take an interest in code quality, is to manage poorly. If you ignore this aspect of management, then you'll have tornadoes on your hands.

Keeping the "Up-Factor" (And, Keeping Your Senior Engineers as a Result)

Michael Mangialardi — Wed, 13 Jul 2022 20:48:55 +0000

The Roman statesman Cicero once said:

As a general truth, as it seems to me, it is weariness of all pursuits that creates weariness of life.

Here, we find an ancient observation of burnout.

To put it another way, when there is a sense of "nothing up from here," people become weary.

In the realm of software engineering, this phenomena is not uncommon.

It is well known that impostor syndrome can cause weariness due to a lack of assurance of being able to fulfill the responsibilities of a role. However, this sort of weariness protects from another sort of weariness--the "nothing up from here" weariness.

Impostor syndrome implies that there is an up-from-here. Namely, there is an active pursuit in becoming more confident in one's skills and fulfilling the responsibilities of a role.

Burnout can happen when impostor syndrome is accomplished and engineers mature.

They may have mastered their ability to be a sound contributor--they can do their job flawlessly. Then, there comes the creeping thought of "now what."

This creeping thought may be prevented when the following circumstances are sturdy:

The business is doing well and morale is good.
The product team one is working on has a strong mission-mindset and great chemistry.
Compensation is good.
There are open-ended challenges that require rigorous technical collaboration.
There are ways to master one's craft in step with product development.
One is in a very specialized role that affords a lot of freedom and creativity (e.g. a design system developer).
There is focus.
There is clear visibility into what is being worked on and why--and who made the decision and what for.

Usually, when teams breakdown and weariness ensues, it is due to more senior engineers burning out. They burnout when those pleasant circumstances previously described begin to evaporate. It has a cascading effect that can seriously harm the bottom line--whether higher-ups admit it or not.

You see, all the circumstances described above are"up-factors."

The business is doing well --> I'm contributing to something that's successful.
The product team has great chemistry --> The product team is presenting a strong vision of what we are working on, and the engineers are collaborating well to implement that vision. We're on a mission.
Compensation is good --> I have a bonus to look forward to.
There are open-ended challenges that require rigorous technical collaboration --> I'm learning a lot about the product and big-picture technical decision-making. I'm excited for the next product.
There are ways to master one's craft --> I'm able to try new technologies and design patterns in the codebase. I'm excited to share the next one I'm working on.
One is in a very specialized role that affords a lot of freedom and creativity --> I get to build out a design system. This is a really fun project. I can't wait for it to be implemented across our various products.
There is focus --> I know what I'm working on and can easily find a way to resolve the situation if I don't. I can come into work ready to get things done.
There is clear visibility into what is being worked on and why --> my team is on a mission, and I see how this ties in with the broader company's mission. I can't wait to see what we accomplish.

Many more examples may be given, but all of these provide up-factors. They fuse together personal accomplishment and a team mission.

From the vantage point of a junior engineer, these "up-factors" (or, the lack thereof) are important but not as impactful when compared to senior engineers. The reason being is that junior developers don't have as much to compare to, and they are motivated by being able to do what they're asked--they are less cognizant of the why things are being done and how to do them very well.

Case in point, junior engineers usually need direction to move beyond meeting the bare requirements of a story/ticket. They need to not just get their code to work, but for it to meet a good level of quality. This requires refactoring code and a large amount of intentionality. In addition to code quality, there is a such thing as an organization quality. Senior engineers becomes more cognizant of organization quality and its importance than junior engineers.

Organizational quality goes down when the up-factors evaporate.

From the position of a senior engineer, it can be quite illusive to sense when things are evaporating. It is not as if all circumstances are pulled out from underneath. Rather, there is a sort of death by a thousand paper-cuts--death by the slow removal of "up-factors."

The business is doing well --> We had a bad quarter. We have to hit all our marks in the next one.
The product team has great chemistry --> The product manager now owns multiple teams and their appearance is more infrequent (and hence, the collaboration and visibility that developers previously has implicitly been removed).
Compensation is good --> No bonus this year.
There are open-ended challenges that require rigorous technical collaboration --> The product team starts to make decisions without developer input, providing tightly-defined sets of work for them--the team starts to work like contractors.
There are ways to master one's craft --> There is not enough "bandwidth."
There is focus --> The developers become cross-functional across multiple projects because some far away higher-ups said so.
There is clear visibility into what is being worked on and why --> The team is split in too many directions. It's hard to keep track.

The removal of these up-factors will certainly weary senior engineers.

So, what does this mean? It is imperative for software engineering management to factor in the intangibles, to present up-factors and maintain them as if it does impact the bottom line (which it does)--to not hyper-analyze efficiency (by which only short-term efficiency is assumed).

Where do you see a need for up-factors?

By the way, I wrote a book on trying to rethink Agile and present up-factors if you're interested.

Roles and Responsibilities Within a Software Engineering Team

Michael Mangialardi — Wed, 13 Jul 2022 14:39:30 +0000

The way to organize of developer efforts and clarify the what, who, how, and why can be achieved by first clarifying roles and responsibilities with the developer process.

Generally, software teams have the following leadership roles: product manager, technical product manager, design lead, engineering manager, and engineering lead. We are not forced into this model, but it provides a helpful barometer.

How do these typical roles fit in your team's organization?

Product Manager

To understand how each typical role fits in our organization, we first need to clarify the responsibilities of each role.

Roles can best be understood as to how they are conduits. In other words, we must understand how a role is a channel between a "higher" initiative and goal--since no one on the level of software development team is a part of the "higher-ups."

A product manager serves as the channel between company initiatives and a team's roadmap of projects.

The product manager is responsible for explaining what the company initiatives are, how they relate to the formation of projects in a roadmap, and how the completion of said projects will contribute the mission of the business.

Also, the product manager serves as the channel between customer needs and a the roadmap of projects.

The product manager is responsible for explainging what the customer needs are, how they relate the formation of projects, how the completion of said projects solves their needs, and how a customer needs and business needs are both fused into a common solution via a project.

In a word, the product manager is the one to define what is worked on, explaining the why from the vantage point of the business and customers.

Technical Product Manager

Technical product managers are the channel between the product manager and the developers.

The technical product manager is responsible for translating projects determined by the product manager into requirements and size-able projects that can be delivered to developers.

Once a project is delivered, the technical product manager is responsible for ensuring that the developers are staying on track to complete a project.

In this sense, the technical product manager is the channel between the product manager and the engineering manager, as both have an interest in meeting the deadlines.

The technical product manager is also responsible for reenforcing what is being worked on and why it is being worked on from the vantage point of the customers and business. This reenforcement is important since the technical product manager is usually in more of a fixed orbit with the developers than the product managers who tend to have more communications with higher-ups.

Design Lead

The design lead is the channel to translate a conceptual project of the product manager into a viable prototype.

The design lead is responsible for showing how a project will look and feel for the users, postulating why the prototype is the best expression of the product manager's vision--and hence, the the best expression of a solution for a business and customer need.

Design leads, like product managers, are a step ahead the developers as they formulate a project for project roadmap while the developers are busy implementing a previously formalized project.

While design leads are a step ahead of the developers, they still should orbit around the current work of the developers, frequently explaining the prototype/requirements--amending them as needed.

It is also important to note that prototypes evolve as a product is constantly undergoing additions (and sometimes subtractions). Therefore, the design lead is responsible for making clear which prototype maps to which phase of a product's evolution. Since developers are a step behind, the prototypes for the current developers' project should not be modified without announcement and a conscious acceptance of the ramifications of a project's scope.

Moreover, the design lead is the channel between a broader design initiative (i.e. a design system) and the developers, ensuring that the prototypes are in sync with the design patterns and principles of the other products--which then ensures a uniform experience for all customers no matter the product in the product suite.

Finally, the design lead is usually the point of contact for receiving feedback from developers and translating those ideas into a prototype.

Engineering Manager

The engineering manager is responsible for allocating developer resources to accomplish projects distributed by the technical product manager.

Therefore, the engineering manager is a channel between the developers and the technical product manager.

The engineering manager advocates for project deadlines. It would be unwise for the product manager to set a deadline on the engineers that is incongruent with the deadline of the engineering manager. While the engineering manager is responsible for understanding the product initiatives, and must communicate with the product manager and technical product manager to do this, the engineering manager's deadline should able to trump the deadline of product managers if it is deemed too ambitious--since engineering managers understand both what needs to be accomplished and how it may be accomplished. Product managers do not have as much visibility into the how part.

The engineering manager is then also a channel between the engineering lead--who is primarily responsible for determine how a project will be accomplished in code (more on this below)--and the product managers.

The engineering manager should help keep the team on track to accomplish projects to meet a given deadline and ensure the team is properly implementing the project in light of product requirements.

This constitutes the responsibilities of the engineering manager so far as the product side is concerned. However, the engineer also is a channel between the developers and engineering higher-ups. Therefore, there are additional responsibilities to satisfy higher technical initiatives.

The engineering manager is a channel between developers and technical initiatives. Meaning, broader technical ideals for code standards, architecture, deployment, career growth, etc. should be implemented by the communication and counsel of the manager.

While this type of channel is shared with the engineering lead, the engineering manager serves this capacity in more of a "eyes on, hands off" manner.

When it comes to career development, a peculiar broader technical initiative. The engineering manager is responsible for helping developers build their craft amidst pursuits for tangible career goals.

More broadly, engineering managers help to motivate developers by allocating work that is peculiar to their skills and interests, developing their short-term and long-term growth, helping to connect work with the big picture, and navigating through difficult seasons in a company.

Finally, the engineering manager is responsible to coordinate technical work that is contingent upon other teams and communicate as needed down to the developers.

With all of this in mind, it can be seen how the role is a unique blend of technical and relational skills. It is the latter which clearly distinguished from engineering leads.

Due to the scope of responsibilities, it can also be understood why engineering managers often do not contribute to any writing of code.

Engineering Lead

The engineering lead is a distinct role from an engineering manager. A manager is more focused on keeping the team on track for delivering on product initiatives and cultivating a strong engineering culture marked by personal development. A lead, on the other hand, is primarily focused on keeping the team on track by planning technical decisions that coincide with product initiatives and developer experience.

An engineering manager may lean upon the engineering lead to help with keeping a team on track by delegating project breakdowns, etc. The manager may also have helpful feedback for big-picture technical conversations. Yet, the roles and responsibilities and distinct.

In a word, the engineering lead is responsible for how projects are accomplished (architecture, technical constraints, etc.) while managers are responsible for ensuring that the projects are accomplished and mapping out how the developers will be cultivated.

Engineering leads are distinct from other developers not only in their leadership qualities but in that they focus on more specialized work. They may work on the day-to-day stories around releasing features to customers, but they are responsible for technical work that enabled efficient releasing of features (tactical work)--such as: establishing code standards and principles, and patterns; maintaining shared libraries; informing architectural decisions; working with other leads to solve large technical projects; etc.

All of this in mind, the lead is a channel between engineering manager and developers.

They are also a channel between other engineering leads and the developers/manager.

Finally, they are a sort of channel between technical product managers and developers, being the primary liaison for questions about the code/projects.

Defining a Team

It is important to call out that it is impossible to enumerate roles without also thinking about how those roles serve a common purpose within the contexts of teams.

Speaking very generally, there are two types of teams in mature software engineering organization: stream and enabling teams.

Stream teams are focused on a "stream" of work. A stream is usually a product, but it could also be a set of experiences within a product, or a set of services that enable those experiences when applications grow larger.

Stream teams require all necessary components in order to legitimately constitute a team. Those necessary components are: Application (UI + mocks, or UI and presentational API) developers, API (presentational APIs and/or microservices) developers, and (sometimes) DB developers.

Usually, a product manager and technical product manager own a particular stream. If streams are smaller and scoped to a single product, then perhaps product resources could manage multiple streams. However, owning multiple streams across multiple products can be quite difficult, so it is not recommended.

Apply Agile to the Family

Michael Mangialardi — Thu, 30 Jun 2022 03:52:10 +0000

Although I have recently criticized some aspects of Agile, it does some things very well.

It creates a sense of mission across a variety of roles within a team.
It provides frequent opportunities to evaluate work in progress and pivot as needed.
It emphasizes small wins that can add up to a larger purpose.

To put it another way, we can break the Agile methodology into several components:

There is a team with multiple roles.
The team works together towards a mission within their distinct, yet sometimes overlapping goals.
The team has tasks on its mission.
The team tracks its tasks and evaluates periodically as tasks are being done.

The principles of Agile may be applied across any organization that also has a team with a mission comprised of a multitude of tasks and roles within that mission.

The family is such an organization.

We don't always think of it in this way, but the family is a mini government, a mini organization, a mini team.

Families do well to have a concrete mission. They should have aims as to what they should produce and how they may contribute to larger society for good--and how they can accomplish such things in a way that builds every member up.

Members of a family have distinct skills, experience, strengths, interests, callings, roles, and responsibilities. Yet, they are contributing to a shared mission.

Putting it all together, a family is a team with many roles found within it. A family may have a mission and small wins (tasks) to accomplish that mission, delegating work across the variety of members.

Therefore, why can't an Agile methodology be applied to a family?

Here's what it could look like:

Write out your family mission
Aggregate current tasks and projects that are a part of that mission
Make these tasks and projects deliverables that are small but important wins
Distribute the work across the team
Take time to check in on progress, see how things are going, discuss any difficulties, pivot as needed, and reflect to commend each other for what has gone well, yet still working on areas of improvement

For my family, which right now is only comprised of my wife and our not-even-one-year-old, we have formed a long term mission.

While the long term mission is something we always think about and prepare for in the background, we pursue it until it changes.

Each year, we set aside goals for what we would like to accomplish, to be intentional about.

Every month, we set aside some projects that can help us towards some of our goals.

Every week, we jot down some projects we can work on as well as the everyday life type of work.

At the start of each week, we review how the past week went, discuss our plans for the new week, and record an action items, making those action items tasks for the week.

Rinse and repeat.

Have you tried applying Agile to your family?

Clean Code is About Reducing Complexity (Not Improving Readability)

Michael Mangialardi — Tue, 28 Jun 2022 17:50:31 +0000

When it comes to clean code, there is often an assumption that clean code means readable code.

In other words, the aim of clean code is usually assumed to be making the code as readable as possible.

More readable code is almost always cleaner code. However, it is not at the heart of clean code.

The aim of clean code is to produce simpler code. Code should be reduced to the lowest level of complexity possible while still providing an adequate solution.

So, how can we reduce complexity in software?

The short answer is removing as much cognitive load as possible.

To put it another way, the less thinking that has to be done to make a change the better.

Creating a "Candidates" Pattern in Your Codebase

Michael Mangialardi — Mon, 27 Jun 2022 19:54:46 +0000

It is good practice to extract sharable code into libraries.

We all get this on some level. For example, UI teams often consume a central design system to reuse UI components that encapsulate a design system's style and behavior specifications.

However, there are three ways we often miss out on extracting sharable code:

By narrowing our sense of sharable code to a very specific thing (e.g. a design system)
By failing to separate generic code from application-specific code (e.g. creating a single GroceriesDropdown component instead of separating a generic Dropdown component from a GroceriesDropdown that merely wraps a generic component and plugs in any business logic--like sourcing a list of groceries)
By failing to stage library "candidates" (e.g. staging a design system candidate in a consuming application)

In this article, I'll talk about the third way of missing out.

Whenever a library of shareable code exists, there is always the potential of creating too large a chasm between the shared library and the consuming applications.

For example, a central design system codebase may be closed off from contribution by the developers working on one of the applications that consumes it.

Regardless of whether the centralized, shared library allows direct contribution from the consuming applications (e.g. creating a PR on the GitHub repo), I'd argue that all consumers of the shared library should contribute.

So, what does contribution look like if the consuming applications do not contribute directly?

Maybe it's jumping on a video call with the maintainers of the shared library and saying, "Hey! I made this function/component that could fit really nicely into the shared library. Here's how we're using it: [insert GitHub link to consuming application's codebase]."

In other words, the consuming application can stage "candidates" for the shared library. The consuming application can call out useful functions/components/patterns that could be extracted into a shared library, making these candidates easily discoverable and shareable.

For example, let's say there is a central design system at a company, and there is an application that consumes it.

The design system doesn't have a Action component, a clickable icon that animates into a background color when hovered. However, the consuming application is implementing this pattern over and over.

Without a candidate pattern, this Action component could get nested within the consuming application and located in a manner that does not make it discoverable:

/* pages/groceries/index.js */

function Action() { ... }

There exists in the consuming application a generic component that could be shared by any application, and hence, could be extracted into the central design system.

However, if no one on the team has an awareness that they can contribute to the design system (even if indirectly), then the shareable component will never get discovered--there won't be a pattern instilling an intentionality to contribute to the design system.

However, with a candidates pattern, we can instill an intentionality to contribute to the design system by having a pattern for stashing code that could be extracted into a central library.

So, how can one implement a candidates pattern? It's quite simple. Segregate a folder in the consuming application that is detected to stashing shared code that could be extracted.

For example, you could stash the design system candidates into a components/design/lab folder in the consuming application(s).

Then, when an opportunity arises, you can easily share the component within that folder with the maintainers of the design system.

Finally, as a cherry on top, you can do two more things:

Alias the dedicated "candidate" folder to match the external package with /lab appended:

components/design/lab --> @mycompany/design/lab

By creating an alias, you can treat the candidate folder as a shared package, making it easy to change the import if it does get extracted.

Write documentation to explain the candidate pattern and enforce it in code reviews.

16 Unsurprising & Surprising Tips on Developer Self-Care

Michael Mangialardi — Fri, 17 Jun 2022 13:48:56 +0000

Learn how to pace yourself to deliver high output without wearing your mind thin.
Take advantage of unlimited PTO if you have it. Studies have shown that when individuals who take periodic breaks from weightlifting performed the same as those who took no break. I don't think our minds are too different from our muscles.
Are you doing the developer work that you are gifted for? Coding teams require tactical work (e.g. building features for a product) and strategic work (e.g. designing architecture). Usually, you'll receive a mental boost when you align your work closer to your gifts.
Do you have a friend who does something similar to you but is not a coworker? Give them a call, or even better, get coffee with them. It is refreshing to talk about your work with someone who gets it but also is out of your work orbit.
Are you following developer trends, newsletters, blogs, etc.? It may seem counterintuitive but building your craft for the sake of your craft (not a product) can be restful.
Are you vocalizing any concerns or question with your teammates and managers? You can be directive without being a jerk.
Are you stretching your technical skillsets beyond your day-to-day? Maybe you should read a book on clean code, software philosophy, or staff engineering. It can be refreshing to think of problems that aren't in your peripherals.
Code something that is fun for the sake of being fun, not making a profit. This one is especially hard for the visionary in me, but again, seeing out a little bit outside of your peripherals through learning or action is helpful.
Read something tangentially related to the engineer side of your brain that fuels a separate interest. For me, this would be something like a book on baseball analytics.
How are you stewarding your income? Yes, that includes making wise financial decisions--but, it also means spending your money in light of a greater vision. Write out a vision for how you may use the fruit of your labor.
Do you have a vision for your career as a developer? If not, the grind of work takes on an excessive load. It is only natural and right to have something to which we are progressing towards, and coding is no exception. If you are unsure, talk with a manager or a mentor. If you have neither, seek your advice online.
Work with your hands. It is a maxim that those who work with their hands rest best with their minds, and those who work with their minds rest best with their hands. The point isn't to pick one over the other but to healthfully incorporate both into your life. Perhaps this could look like backyard beekeeping, square foot gardening, or rice farming.
Intentionally avoid some automation. I could automate cutting my grass. I could get one of those new robot mowers, or I could pay a teenager in my neighborhood to automate the mowing process. But, the truth is that mowing is very relaxing to me, and so, I don't automate it. It's hard for engineers sometimes to think this way, but calculated acceptance of manual processes has its merit.
Study the past. As developers, we can be caught in the hustle and bustle of the latest technologies, trends, and happenings. It is only fitting that a pause from this will be restful. Pick up a book that takes you to the past. Last year, I took a break by reading Up From Slavery by Booker T. Washington.
Shake up your routine. I recently listened to a book called Adventuring Together: How to Create Connections and Make Lasting Memories with Your Kids. I found it interesting how the other makes a case for spontaneity, and yet, also talks of the importance of family traditions. So, which is it? Routine is the foundation, and spontaneity with intention can be energizing. It is good to have a consistent work routine, but you can also be helpful to intentionally have aspects of your week where you shake things up. Working from home, I have some days where I mow or water the garden for a work break, work from a hammock, and/or work from a coffee shop to sprinkle some change to the week.
It is a maxim that thankfulness lightens the heart. Well, are you recording your thanks for the aspects of your work?

How to Start a Design System Without a Company-Led Initiative (A Use Case for Non-Enterprise Businesses)

Michael Mangialardi — Wed, 26 Jan 2022 16:22:27 +0000

It's harder to start when there's not a company-led initiative

While it does not take much to see the benefits of a design system, and there's plenty of material out there on the best way to build a design system, it is a bit harder to know how to start when there's not a company-led initiative.

Non-enterprise companies may be more likely to not be familiar with designs systems and their importance, and many times, the need for them is unintentionally discovered in the thick of business needs.

Practical Use Case

Example: A company has found their niche in the _____ industry. As the company has grown, they acquire other startups that are a good fit, extend their product offering, and in turn, take the company to the next level.

Suddenly, there are variety of applications for products living under one company. These applications have originated independently from one another.

As a result, all the applications have very different experiences that they present to the user, even if the due diligence has been done to update the logo and some of the colors.

With time, the business realizes that organizing the applications to reflect one brand and communicate a common feel/experience to users will do much to drive the business forward.

Finally, an initiative for a design system comes. However, all the various teams implemented some small version of a design system (whether in an external codebase or in their existing one).

The company is basically asking for a design system (whether they realize it or not) and someone needs to step up.

If this practical use case sounds familiar (or plausible), then what do you do?

Well, first we need to consider how things would have shaken out in an ideal scenario.

The ideal start

We've discussed a less-than-ideal example. But, how would a design system be started in an ideal scenario?

Ideally, a design system would be initiated proactively and not reactively. Meaning, a design system would be created upfront because of it's ability to set a foundation to craft common experiences, even if the company should grow. This is in contrast to starting a design system when its discovered that the customers are (basically) asking for one.

In an ideal start, the company would dedicate full-time resources (whether internally or externally acquired) to build out a design system.

And hopefully, those resources would include at least one designer and one developer, both recognizing that design systems have to be prototyped by designers and distributed by developers with a huge amount of conversation overlapping the handoffs.

When a design system is created proactively, there are still some dangers:

The design system team fails to showcase their work and invite visibility/input from other stakeholders (the designers and developers that will be consuming the design system).

Example: On the developer side, the design system assets do not meet the technical needs of all the applications and/or the assets force a technical transition that others don't want to make.

The design system team releases documentation before it releases assets that can be consumed in code, leading to micro-design systems being created independently of one another.

Putting it all together, here's what we would ideally have when starting a design system:

Support from the company as they recognize the business value of the design system (and not just geeking out of designers and developers).
Dedicated resources working on the design system, including designers, developers, and a healthy amount of collaboration between them.
Communication about the design system to stakeholders, making the work visible through online documentation, well-documented source code, and announce and feedback sessions.
A streamlined process for releasing versions of the design system, including both documentation and consumable assets for both designers and developers (i.e. a Figma library, CSS file, shared components, etc.).

Making the best of the less-than-ideal situation

Ok, so that's the ideal situation, but what about when you are in the less-than-ideal situation?

Meaning, you are in the situation where you see the need for a design system, but there is no company-led initiative.

Usually in such a case, bandwidth and deadlines are tight but the need for a design system is wide.

What do you do?

Well, you have three options:

You put together a strong case, including the business impacts of a design system. Then, you pitch it to whoever can make it happen (whether directly or by promoting your case).
You create an initiative within the designers and developers, creating a proof of the concept and then doing the first option collectively.

For this option, you would start by putting together a strong case for a design system, but you focus more on the impact on the designers and developers. You pitch the idea to a group of designers and developers, and then see what happens.

You wait it out.

Truth be told, you need a bit of each of these options.

Everyone needs to familiarize themselves with the practical and technical implication from the perspectives of the business, the designers, and the developers. Everyone needs to know why a design system is valuable. Plus, you'll need to be patient throughout the process.

While each option has an element of truth to it, you'll need to discern what approach is best in your specific scenario.

Regardless, here are a few things you could do to get started:

If you're a designer, start organizing a design system in your design tools and drive product-specific prototypes from the unofficial design system.
If you're a developer, create a POC of a design tokens pipeline. If there's no designer with an unofficial design system, then reverse engineer one and organize it in code using design tokens. Surely, there are some commonly used colors, typography, etc. that you could organize. There is always a design system, it's just a matter of whether or not it is formalized/organized.
After a POC has been created, begin to share your progress with designers and developers you work with.
Prepare your pitch. Write out how you could communicate the value of a design system, and how you could speak to the specific points of interest depending upon whether you're speaking with a designer, developer, and business person.
Lay out some ideas of how a design team could be formalized. What resources would be needed? How would those resources work together? How would the team invite visibility?
Create a roadmap of what needs to be done to get to a stable state with a design system and its consumable assets.
Be patient and wait for an opportunity. Discern who to speak to and when.

Conclusion

When working for a company that is not aware of the value of a design system (a not uncommon case for non-enterprise companies), take initiative to lay a foundation and gain momentum.

Although the business may be reactionary, you do not have to be. That is no knock on non-technical workers, but with your creative, technical mind, understand that you may see things before others do. And when that's the case, taking initiative is better than wallowing in disappoint.

Don't become discouraged. Although in some ways the less-than-ideal scenario is (...well...) less-than-ideal, it can eventually bear sweeter rewards. There is always pros-and-cons, and do your best to see the pros.

What can you do to help start a design system?

Wrapping React Query's useMutation (A Use Case for Wrapping External Libraries)

Michael Mangialardi — Fri, 21 Jan 2022 15:05:26 +0000

React Query is a library for fetching and mutating server state via React hooks. In addition to the perk of caching, it also neatly returns metadata representing the various lifecycles of a network request for both querying (read operations) and mutating (create, update, delete operations):

 const {
   data,
   error,
   isError,
   isFetched,
   isLoading,
   ...etc,
 } = useQuery('todos', getTodos);

 const {
   data,
   error,
   isError,
   isIdle,
   isSuccess,
   mutate,
   ...etc,
 } = useMutation(deleteTodo);

This cuts down on the boilerplate when using React local state to track this metadata manually.

As shown in the example above, the useQuery and useMutation hooks both have an argument for a function that will presumably make the network request (getTodos and deleteTodo respectively in our example).

I have previously written about alternatives to the signature of this hook that you can achieve by wrapping it.

In this post, I'd like to ponder on potential ways to improve the signature of the useMutation hook.

First, there is currently no way of enforcing that all mutation functions go through the same API client.

Imagine you wanted to set a pattern in the codebase to make all API requests through a wrapper around the native fetch API. That way, some common logic can be encapsulated (like stringifying the request body).

Let's say this wrapper is called fetcher.

We would want to avoid one mutation function using the native fetch API and the other using fetcher.

Of course, this could be enforced via code reviews, but what if there was a way to "document" the expected behavior through a design pattern?

A slight improvement to inlining the functions in the file where useMutation is called would be to colocate all the operations for an API endpoint in a single file, exporting each function individually.

Then, each "operations" file (the file with all the operations for an API endpoint, including queries and mutations) would have a pattern of importing the fetcher module and consuming:

/* /api/todos.js */

import fetcher from './fetcher';

export async function getTodos() {
  await fetcher('/api/v1/todos');
}

export async function deleteTodo(id) {
  await fetcher(`/api/v1/todos/${id}`, {
    method: 'DELETE',
  });
}

/* some-component.js */
import { useQuery, useMutation } from 'react-query';

import { getTodos, deleteTodo } from '../api/todos';

function SomeComponent() {
  const todos = useQuery('todos', getTodos);

  const removeTodo = useMutation(deleteTodo);

  // not necessary, but wanted to showcase the `.mutate` in action
  function handleRemoveTodo(id) {
    removeTodo.mutate(id);
  }

  if (todos.isLoading) {
    return '...';
  }

  return '...';
}

Looks fine, but there's something else to consider.

It is very common to "refresh" (or "requery") after doing a mutation.

In this example, you would want to refresh the todos after deleting one (you could do optimistic updates, but I'm ignoring that for the sake of simplicity).

To do this, you have to obtain access to queryClient via the useQueryClient hook, and then "invalidate" the todos query using queryClient.invalidateQueries function:

const queryClient = useQueryClient();
queryClient.invalidateQueries('todos');

The name of invalidateQueries captures the technical sense of what's going on.

To "refresh" your todos, you mark the todos as "stale" (effectively saying, "Hey! I may need to update the cached query results via an API request.").

Here's what that would look like in our previous example:

/* some-component.js */
import { useQuery, useMutation, useQueryClient } from 'react-query';

import { getTodos, deleteTodo } from '../api/todos';

function SomeComponent() {
  const todos = useQuery('todos', getTodos);

  const removeTodo = useMutation(deleteTodo);

  const queryClient = useQueryClient();

  async function handleRemoveTodo(id) {
    await removeTodo.mutateAsync(id);
    queryClient.invalidateQueries('todos');
  }

  if (todos.isLoading) {
    return '...';
  }

  return '...';
}

We can potentially improve this by encapsulating useQueryClient and the query invalidation into a custom hook (and it provides an opportunity to come up with a preferred name to describe this logic):

/* /api/index.js */
export function useRefresh() {
  const queryClient = useQueryClient();
  return (query) => queryClient.invalidateQueries(query);
}

/* some-component.js */
import { useQuery, useMutation } from 'react-query';

import { useRefresh, getTodos, deleteTodo } from '../api';

function SomeComponent() {
  const todos = useQuery('todos', getTodos);

  const removeTodo = useMutation(deleteTodo);

  const refresh = useRefresh();

  async function handleRemoveTodo(id) {
    await removeTodo.mutateAsync(id);
    refresh('todos');
  }

  if (todos.isLoading) {
    return '...';
  }

  return '...';
}

Lastly, if we wanted to inline the mutation function (deleteTodo) while ensuring the same fetch client is used every time, we could expose a hook from the same file as useRefresh that returns the fetch client for mutations:

/* /api/index.js */
import fetcher from './fetcher';

export function useRequest() {
  // Add any mutation-specific request logic here
  return fetcher;
}

/* some-component.js */
import { useQuery, useMutation } from 'react-query';

import { useRefresh, getTodos, deleteTodo } from '../api';

function SomeComponent() {
  const todos = useQuery('todos', getTodos);

  const request = useRequest();
  const refresh = useRefresh();
  const removeTodo = useMutation(async (id) => {
    await request(`/api/v1/todos/${id}`, {
      method: 'DELETE',
    });

    refresh('todos');
  });

  function handleRemoveTodo(id) {
    removeTodo.mutate(id);
  }

  if (todos.isLoading) {
    return '...';
  }

  return '...';
}

Conclusion

Maybe you like these changes, maybe you don't. Either way, I hope this gets the brain juices flowing to consider ways to wrap React Query's useMutation to fit the needs of your codebase.

Creating a Gradient Component in React From Design Tokens

Michael Mangialardi — Thu, 20 Jan 2022 16:08:45 +0000

If you're not familiar with design tokens, they are simply representations of design specifications in code.

By "representations," it is meant that they are key-value pairs that represent design specifications.

Generally speaking, there are two types of design tokens:

"Simple" tokens - Representations of valid values of the design system. These tokens usually cover the colors, typography, spacing, etc. of the design system (i.e. color-red-500, font-bold, etc.).
"Component" tokens - Representations of the design specs for a component/element (i.e. component-button-background-color).

With a design tokens pipeline, you can write out design tokens in JSON format, and then translate those "raw"/JSON design tokens into formatted tokens (JavaScript modules, CSS variables, SASS variables, etc.).

With that background in mind, imagine that a design system had "simple" design tokens defining valid colors.

Here's the JSON representation:



{
  "color": {
    "red-50": "#FFC3C2",
    "red-100": "#FFAFAD",
    // ...etc
  }
}

Now, imagine that a design tokens pipeline formats the JSON into the following JavaScript modules:



export colorRed50 = "#FFC3C2";
export colorRed100 = "#FFAFAD";
// ...etc

And, let's say these tokens can be consumed in an application via an npm package:



// SomeComponent.jsx

import * as tokens from "@some/design-system/tokens";

function SomeComponent() {
  const style = { color: tokens.colorRed50 };
  return <div style={style}>Some Component</div>
}

Now, given such a setup, how can we programmatically create gradients when given two color tokens?

Here's one way:



// SomeComponent.jsx

import * as tokens from "@some/design-system/tokens";

function SomeComponent() {
  const style = {
    background: `
      linear-gradient(
        45deg,
        ${tokens.colorRed50},
        ${tokens.colorRed100}
      )
    `,
  };
  return <div style={style}>Some Component</div>
}

Ok, but is there a way that we can refactor this?

Well, we could create a helper function that returns the gradient when providing the from and to values:



// get-gradient.js

export default function getGradient(from, to) {
  return `linear-gradient(45deg, ${from}, ${to})`;
}

// SomeComponent.jsx

import * as tokens from "@some/design-system/tokens";

import getGradient from './get-gradient.js';

function SomeComponent() {
  const style = {
    background: getGradient(
      tokens.colorRed50,
      tokens.colorRed100,
    ),
  };
  return <div style={style}>Some Component</div>
}

This refactor doesn't save in lines of code, but it does guarantee that gradients will be created the same so long as they are created through the getGradient helper function.

What if we refactored one step further and allowed the gradient to be applied to any child component via a wrapper component?



// Gradient.jsx

import { Children, cloneElement } from 'react';

function getGradient(from, to) {
  return `linear-gradient(45deg, ${from}, ${to})`;
}

export default function Gradient({ children, from, to }) {
  return Children.map(children, (child) => {
    return cloneElement(child, {
      style: {
        ...child.props.style,
        background: getGradient(from, to),
      },
    });
  });
}

// SomeComponent.jsx

import * as tokens from "@some/design-system/tokens";

import AnotherComponent from './AnotherCompoent.jsx';
import Gradient from './Gradient.jsx';

function SomeComponent() {
  return (
    <Gradient from={tokens.colorRed50} to={tokens.colorRed100}>
      <AnotherComponent />
    </Gradient>
  );
}

By using Children and cloneElement, the Gradient component clones the child element and applies the gradient.

🎊 Awesome! Now, we have a pattern for applying a gradient via a wrapper component in React!