Why I document my React components
This article explains why I personally place so much importance on documenting the React components which I write as part of projects, and why try I do it in similar way as the third-party components which the projects rely on.
While this article describes my approach specific to React component, its ideas do not apply only to React projects. They can just as well be used in projects which use Vue, Angular and any other frontend/UI/web framework.
Introduction
In any non-trival project I’ll inevitably be using a component library, such as Theme UI, Chakra UI, Material-UI or some other.
These component libraries usually come with pretty good documentation. In that documentation I see how the components look and how they behave. The better libraries even provide source code which I can copy&paste straight out of the documentation into my own project. The documentation is an invaluable source for both developers and designers.
Over the years I noticed that when we create our own, custom components which build on top of this solid foundation, we often don’t give their documentation the same attention. Let me show you why it is worth your while to spend a bit more time documenting your project.
Tale of a <LoaderButton>
Let’s say the component library provides a <Button> component. Pretty basic, right? And in my project the design asks for a particular kind of button which shows an optional loading indicator over the label, and that special button is used in many places. So it only makes sense that I create my own component which builds on top of <Button>. Let’s call that new component <LoaderButton>.
I strongly believe that a developer working with me on that project should have the same experience whether they are using <Button> or <LoaderButton>. Just looking a bit of source code that’s using either, they should not be able to tell whether the component is coming from the third-party library or not. The components should be largely interchangeable (to the extent possible), and when the developer learns how to use one, they should instantly be able to effectively use the other.
Artificial Divide
The fact that one component was written by the component library developers and the other one by me doesn’t make them inherently any different. If we think of them as different, we’re building an artificial divide that serves no purpose.
Any divide between first- and third-party components increases friction. I can learn how to efficiently use Material-UI components, but that skill has little value of I can’t apply it consistently throughout the whole project. If I have to keep track in my head which kind each component I’m looking at, and how to use them, it decreases the amount of bandwidth I have for more important things.
When creating my own first-party component I try very hard to follow the same patterns as the third-party component library. For example, all Theme UI components support a sx prop to easily override the style. If I base my components on Theme UI, I’ll make sure that — if possible — the components that I write also support that prop.
Part of me is always thinking: how would I design this component if I wanted to submit it for inclusion in the upstream component library, or at the very least pull it out of the project into my own component library. This drives a lot of my decisions about how to design the APIs, make them simpler, easier to understand, and more consistent overall.
In the documentation for my components I try to provide examples that highlight the capabilities and also limitations of the implementation. This gives designers — some of who surprisingly often visit the documentation pages — more context about where, how, and why the components diverge from the design. And also which kind of changes might be easier to implement than others. Because let’s be honest, the design is never set in stone in any project, and will change. And if the designer has to decide between two (functionally equivalent) options, I want them to pick the one that is easier for me to implement.
Who’s paying for all this?
This consistency and documentation comes at a cost. It takes a bit longer to create each new component, to think of sensible examples, to describe how the components work etc. Don’t worry though, the more you practice the easier it gets. Still, it takes more effort than not doing all of that additional work.
In the end, it’s a personal decision that every developer has to make for themselves. How much do you value consistency? How important is a clean, well-documented code base to you? How much are you willing to invest in order to give your coworkers—not only developers but also designers—a good foundation for understanding the overall state of UI components in the project?
I know my answer. What’s yours?
