Raphael Thys
I like to think that documentation serves as a compass that not only guides future maintainers but also aligns current team members to a shared understanding of the codebase.
Of course, there is a big difference between writing documentation and writing “good” documentation; not everyone understands or even considers that difference.
How often have you landed on a documentation site only to find out the docs are auto-generated pages based on the project source code you’re looking to use?
In this article, I’m going to cover some of the best practices when it comes to writing proper documentation.
An example of a documented Bit component in a remote Bit scope.
The Role of Documentation in Software Development
Good documentation is like that friend who always remembers important details — comprehensive, reliable, and frankly, a lifesaver when you’re trying to make sense of lines and lines of code.
On the teamwork front, quality documentation is the same, when you have clear, up-to-date, and accessible instructions, it’s like handing every team member their very own Rosetta Stone for code comprehension.
Now, let’s not sugarcoat it; not everyone “gets” documentation. More often than not, there are key aspects missing due to the writer making assumptions about the user’s knowledge, or even just a lack of proper details, because documentation was treated as an afterthought once the library/system was already implemented.
Poor documentation practices are one of the main causes of setbacks in a project. You’ve got slow onboarding because new team members are basically solving riddles in the dark. There are endless bug hunts because, without guidance, finding a glitch is like finding a needle in a haystack made of needles. And oh, the wasted time as developers playing detective, piecing together how a system supposedly operates. It’s a surefire way to drain resources, morale, and, let’s in some situations: sanity.
But here’s the kicker: documentation doesn’t have to be a chore or an afterthought. Enter Bit, the solution to all your documentation problems. With Bit, you’re not just documenting; you’re creating interactive, living insights into your code’s purpose and prowess. Bit understands that documentation isn’t static; it’s a living narrative of your software’s journey, evolving hand-in-hand with every iteration and improvement.
The Pillars of Effective Code Documentation
As I’ve hinted at before, it’s important to understand that not all documentation is created equal — and in this article, we’re trying to define what makes the crème de la crème.
So, what makes for the golden standard in documentation? Let’s lay down the pillars — the non-negotiables that separate the best from the rest.
Clarity: The Unclouded Lens
Every word and every sentence must cut through confusion like a hot knife through butter. Clear documentation uses plain language, avoids jargon unless absolutely necessary, and answers the “what,” “why,” and “how” without sending readers on a wild goose chase.
The key is to help the reader find the answer they’re looking for as fast as possible.
Consistency: The Familiar Path
Walking through your documentation should feel like strolling down Main Street in your hometown — not a single surprise turn or unexpected pothole. Consistency ensures that once you’ve read one part of the documentation, the rest follows suit in style, format, and terminology.
This way you reduce the cognitive load required to traverse the documentation and find the answer to whatever question your readers are trying to answer.
Accessibility: The Open-Door Policy
Good documentation doesn’t play favorites. It’s there for everyone, regardless of their years of experience. Accessibility means your docs are easy to find, well-organized, and cater to different learning preferences, with visuals for the visual learners and examples for the hands-on crowd.
It’s paramount to understand that when you’re creating documentation that will be publicly available, not all readers who reach it will learn through the same means. Some of them will enjoy the long, detailed walls of text, but others will turn around screaming unless you give them some visual cues, even a video version of the documentation where you show exactly what they need to know. And others will, in fact, scroll through your words as fast as possible looking for a properly highlighted block of code, that’s the only way they incorporate new concepts.
And your documentation should, ideally, cater to all of them.
Up-to-Dateness: The Living Document
Static documentation is about as useful as last year’s calendar. The best documentation evolves in tandem with its code — it breathes, it grows, it adapts. Keeping your documents fresh and reflective of the latest changes means never having to say, “Oh wait, that’s how we used to do it.”
Remember, in a world where your code could be seen by millions or just a few, clarity, consistency, accessibility, and timeliness are your best allies in building a legacy of understanding.
Documenting your Bit Components
Bit streamlines documentation as it is essential for code reuse and a decentralized collaboration workflow between autonomous teams. Both objectives are at the core of Bit’s mission — both are promoted by good documentation of independent Bit components.
Here are two features you’re gaining out-of-the-box when authoring and maintaining Bit components:
- Live Code Renders: Bit’s live code renders provide a sneak peek at how your components behave in the real world without leaving the comfort of your docs. It’s dynamic, illustrative, and darn effective at getting everyone up to speed. Developers can tinker with the live code box and understand the effect of their changes before even importing the component into their systems.
- Example Embeds: Ever read a manual and thought, “Sure, that sounds great, but what does it look like in practice?” Bit’s example embeds (also known as “compositions”) put an end to the guessing game. These tangible snippets show your components rendered and in action, providing a hands-on experience.
- Auto-generated API reference: Head over to your componet’s ‘API reference’ tab (in the component page) to explore the API reference generated by Bit
Now, let’s get to the nitty-gritty of integrating Bit into your workflow:
- Start with Structure: Identify the components that are the building blocks of your project. With Bit, each becomes a first-class citizen, deserving of its own spotlight in the documentation realm.
- Embrace Interactivity: Use Bit to document not just the static aspects but also the behavior of your components. Leverage live code examples to illustrate how they interact with their environment.
- Keep it Fresh: Bit thrives on the living, breathing essence of documentation. Each update to a component can sync seamlessly with its documentation, keeping your team aligned with the latest and greatest.
- Share the Love: Bit makes your well-documented components shareable across projects and teams. Who knows? Your nifty date-picker might just become the belle of the ball in numerous codebases, all thanks to top-notch documentation.
By integrating Bit into your documentation workflow, you’re not just keeping records; you’re crafting an interactive documentation experience that empowers your team (and anyone else really).
The result? A smoother, faster development process where everyone’s in the know, and your software shines brighter than ever before.
A practical example: documenting your Bit component
Let’s now put everything we’ve seen so far into practice. I will show you how you can document your components by taking advantage of the tools you already have at your disposal inside your Bit project.
For this example, I’ll document a component I’ve already created a while ago. It’s called “User Display” and it just shows a simple user box with some details.
Here’s what the documentation looks like right now:
As you can see, there is no explanation whatsoever, there is only a single working example (a composition), and a table of properties that don’t really add any insights.
So let’s see how we can improve this.
After importing my component into a fresh new project (which I can do thanks to Bit’s import command), I see that my folder structure looks like this:
See any problems there?
The main issue I noticed is that I never created a documentation file for my component (either that or I removed the one created by default by Bit). So let’s quickly add a file called user-display.docs.mdx in there and let's add something like this:
---
Description: A simple component used to showcase the details of a user
---
import {UserDisplay} from './user-display'
This component takes a user id and gets the details of the user through the useUser hook.
It then displays the user's details (specifically the name, email and phone number).
If can also display any child element you add inside it.
While it's loading the details, it'll display a "loading" state instead of displaying the empty container.
```jsx live=1
<UserDisplay userId={1}>
<h1>You can edit any of this code!</h1>
</UserDisplay>
```With that, just run bit start to boot up the Bit server, so it can render our documentation and we're now seeing the following:
This is already a major improvement! Now, we’re seeing a subtitle (the one specified on the description property of the file's frontmatter), a properly rendered documentation (our MDX code), and a live sample code that you can tinker with while reading the documentation for this component.
Of course, this is not all, we can also create some “compositions” that show different ways of using our component.
In my case, I’ve edited the user-display.composition.tsx file to look like this:
import React from 'react';
import { UserDisplay } from './user-display';
export const DefaultUserIdUserDisplay = () => {
return (
<UserDisplay>hello world!</UserDisplay>
);
}
export const CustomUserIdUserDisplay = () => {
return (
<UserDisplay userId={2}>This is another user</UserDisplay>
);
}
export const NoChildrenUserDisplay = () => {
return (
<UserDisplay userId={0}/>
);
}I’m essentially using my component in three different ways, and through these examples, the documentation will render the following:
Notice some interesting details:
- The name of the composition is at the bottom of each one, they’re parsed versions of the names I used for my constants. So thanks to the fact I used a friendly name there, you get a human-friendly name here for free (awesome!).
- You can have as many compositions as you want here.
- Compositions don’t show code, they’re meant to show the behavior of the component under different configurations.
The final piece of documentation I’ve added was code comments on my code to describe what each prop of the component is supposed to represent.
My code looks like this:
export type UserDisplayProps = {
/**
* The ID of the user to display, by default it takes the value of 1
* */
userId?: number;
/**
* Any content to render inside the component
* */
children?: ReactNode;
};
export function UserDisplay({ userId=1, children }: UserDisplayProps) {
const [loading, error, user] = useUser({id: userId})
if (loading) {
return <Loader />;
}
if (error) {
return <p>Error: {error.message}</p>;
}
return (
<div>
<h2>{user.name}</h2>
<p>{user.email}</p>
<p>{user.phone}</p>
{children}
</div>
);
}Notice the code comments and the default value on the userId prop. Now, the table at the bottom of my documentation looks like this:
Thanks to the fact that Bit is also parsing the code comments and the actual code to generate some auto-documentation, I’m showing even more details here without having to even think about it.
Note: When composing apps and services with Bit components, the levels of abstraction or concreteness of each component are according to the component’s place in the dependency tree. The “higher” it is located in the tree (the closer it is to the app component), the more abstract it is. The documentation for each component should match its level of abstraction.
Conclusion
There is no other way to say it: proper code documentation is not just a nice-to-have, it’s the bedrock of a robust, maintainable, and collective understanding of whatever you build through code.
If you’re hoping to have others (or even you in the future) work with your code (be it a platform, a library, a framework or just a function you’re sharing), then having proper documentation for it is crucial to its adoption.
Now, there are many ways to tackle documentation, but if you want to go deep, make sure everything gets covered and at the same time, you don’t want to delay the project’s timetable due to this effort, Bit is probably one of your best options.
The way it integrates documentation into the development life cycle, and how it seamlessly supports the most common tools for this job, it’s really a shame not to use it to document your components/creations.
Remember that you can review the component I documented for this article here, and you can even fork it through bit and use it as your own template.
Happy documenting!