How we Collaborate on our Composable Docs App
You may have noticed that we've been relatively quiet over the past several months. That's because we've been diligently working on a new version of Bit that has a gazillion new features and improvements. An official announcement is coming soon!
As we progressed with the development of the next major Bit update, we needed to create new documentation to accompany it.
In this blog post, we want to share our experience collaborating on our documentation in a composable way using Bit Components and MDX.
At Bit, each team is responsible for creating, delivering and maintaining both the code components and the documentation components that relate to its role in the organization. These components are hosted and collaborated on in a Bit Scope that corresponds to the team's role. For example, the Angular team manages the Angular Scope, which also includes MDX components that cover the Angular docs.
In this case, deploying the Angular docs involved three autonomous teams: the Angular team, the Docs team, and the Community team.
These three teams collaborate in the following way:
The Angular team delivers its MDX component, the Docs team approves and integrates these components into the docs section of the app, which is a component itself.
Then the Community team, which is responsible for the bit.dev app, approves and integrates the docs section into the app, which is, you guessed it, also a component.
As a side note, MDX is a fantastic technology for creating and managing documentation. It combines the power of Markdown and JSX to create rich, interactive content that can be easily maintained over time.
This makes it an excellent choice for component-based documentation, where clarity, organization and autonomy are paramount.
Coupled with Bit, MDX becomes even more powerful, as it allows you to create and maintain documentation components that can be easily maintained, independently versioned, and reused across multiple projects.
With each Bit component being truly independent, they can effortlessly be combined with any other Bit component to create something new. Let's demonstrate this by rendering an independent MDX component inside this MDX component.
Here's is another MDX component. Since we can render JSX in MDX components, we can use another independent React component:
MDX component per Scope
The amount of MDX component each scopes has
- ●teambit.react
- ●teambit.angular
- ●teambit.vue
Our Journey to Collaborative Content Creation
The first Bit component we created is the MDX-Env. Every Bit component uses an env (component development environment) for its development workflow. The env determines how a component is compiled, tested, formatted, built, and more.
As soon as the MDX-Env was set up, it was time to create some content! Each team indepedently authored and delivered their content using a standardized MDX component template, which is provided by the MDX env.
A team who wants to suggest new content for the docs will start by creating a new Bit workspace, using the bit-dev starter. This starter contains the bit-dev app component, as well as the docs section component.
For example, a developer from the Angular team will run the following command, to create a new workspace named new-angular-docs, and configure its components to be stored in the Angular scope):
This starter contains the bit-dev app component, as well as the docs section component. It’s maintained by the community team (scope):
Once the workspace is created, the team will create a new MDX component using templates available in the MDX env. For example:
To add their content to the doc’s sidebar navigation, the team will update the docs section component.
To wrap everything together into a single change request the team will use the lanes feature, which allows to collaborate on changes across multiple components without interfering with the main development course.
The Angular team will then snap the changes made to the components. These include:
- The new MDX components (for Angular's documentation)
- The modified docs section component, which now includes the routing to the new Angular documentation (the MDX component)
- The modified app component, which now uses a new version of the docs section component
Changes to the docs section will propagate automatically to the bit-dev app component.
Finally, the lane grouping the modified components is exported for review:
Once approved by the community team, the changes to all three components will be merged into the main lane.
That means, that each new snap (version) will become the latest version of its corresponding component, and not detached from it, as it was when it was part of the add-angular-dev-tools-docs lane.
Once the changes are merged, components will be tagged with a release version:
The Benefits of Collaborating with MDX Components using Bit
Since each component is independent, it doesn't require a complex and large codebase, making it simpler and quicker to create and deliver new content and components. In fact, all you have to do to start working on an existing component is to import it to your workspace.
Previewing content in the workspace is also streamlined with Bit, as each component can be previewed in isolation, making it easy to identify and resolve issues quickly.
As illustrated in the preview card above (clickable to visit the component page), each content component exists within its own distinct scope. Team members who specialize in specific areas, such as Angular scope, dependencies scope, or defender scope (covering testing and linting), maintain these scopes. They are also responsible for the documentation of their respective products, as they are best suited to write about their creations. This method promotes independent work and guarantees that each team takes full ownership of its designated scope.
Lastly, as mentioned before, non-developers can also contribute to the content creation process. Yona, one of Bit's Co-Founders and leader of the People scope really enjoyes writing content, and has been contributing to our internal Wiki for a while now.
Reviewing Composable Content (Or: 'How This Paragraph Was Added Later')
Speaking of non-developers, a composable process for content creation and composition also allows for a review process.
The version of the article you're reading now is NOT the first version of this article - you can click here to compare this version with the previous one.
You can see there how this paragraph was added in the review process, along with various notes added and editing done by my colleague Omer, who's definitely not a developer but still managed to write this paragraph with VSCode and export it back for integration.
The process was simple: After the first version was exported to the blog-content scope, he just imported the component, created a lane, made changes, snapped and exported it back for review.
Maintaining and Managing Content with MDX Components using Bit
In addition to creating a single source of truth, combining Bit and MDX provides the ability to compose content from independent components. Since each component is independent and can be reused in multiple projects, you can combine it with other pieces.
For example, for our blog posts, we created short snippets that are essentially a way to ensure that every time we had to explain something, we did so consistently and accurately - it's the exact same explanation, without copy-pasting it. If tomorrow we change that explanation, it will be automatically updated in every place it is featured, across any of our apps.
With Bit, teams are able to work together seamlessly to create and manage content by versioning, sharing, and collaborating on MDX components. MDX components can be reused and easily composed together, making it easy to update and modify content as needed, without having to start from scratch every time.
Conclusion
In conclusion, our experience collaborating on composable content using MDX components and Bit has been extremely beneficial. To recap what we've learned:
- MDX and Bit components enable teams to create and manage content efficiently and effectively, thanks to their modular nature and the ability to reuse and compose content.
- Combining MDX and Bit allows for greater collaboration, as each component is independent and can be reused with other components. This enhances team coordination on content creation by effectively managing versions and dependencies.
- Our experience showed that content creation and delivery are simpler and quicker with this approach, as it doesn't require a complex and large codebase.
- Non-developers can also contribute to content creation, making the process more inclusive and harnessing a broader range of skills and perspectives.
- Bit and MDX make it easy to maintain and manage content, improving consistency, accuracy, and collaboration. Bit components are flexible and reusable, allowing for seamless updates and modifications to content.
Ultimately, our approach to collaborating on composable content using MDX components and Bit has streamlined our processes and improved our workflows, resulting in a more efficient, consistent, and flexible content management system.
