Full article available on Aviyel for free (leave a like here before you check it out on Aviyel)
Hello, developers! I bet you know React and love it, but let’s time travel to the time when you didn’t know about it. You didn’t know where to start, so you probably watched a video of a guy telling you about React and found yourself stuck in tutorial hell. But look at you now. You are well versed with React and can easily create documentation for React components in one go.
Why Do Developers Require Documentation?
When software solves a problem and makes the lives of others (including developers) easy, it’s good software. But what truly drives a large fanbase is the developers behind it. Imagine if React didn’t exist and you created it over a weekend or two. Not many people would try it out and your tech will be forgotten (the worst-case scenario), someone else would create similar tech better than yours unless you document your tech, driving more users and developers.
Documentation is simply a report (without strict format) on how to use a tech usually created by its creators so others can get friendly with that tech and figure out its usages easily. Imagine if your beautiful documentation for a tech you created (the tech doesn’t necessarily need to be big like the entire React library or Angular framework) got noticed by popular software engineers like Clément Mihailescu, or Akshay Saini and they try your tech and love it. The next thing you know is that your code becomes popular and you either get employed at your favorite company or turn that tech into a startup and become successful and wealthy. Your documentation, if open sourced might widen new avenues of community growth, collaboration and might connect you with big shots of the industry as well.
Is It Difficult To Create Good Docs?
Is it difficult to super cool and professional docs like the following ones? If you want to do it manually by implementing all the fancy UI components, yes, of course. Have you checked out Expo’s (a toolchain built on top of React Native) documentation? They don’t just write a bunch of texts describing how to use their components, rather they’ve got editable codes for components, which means the users are able to edit the displayed code snippet (e.g. “color = black” to “color = yellow”) right on the site and the changes will be immediately visible on screen. With this, users are able to grasp the behavior of a component in an interactive way, which is the ideal way to learn for a developer. You can also check out Flutter and Material UI for inspiration on creating better documentation.
What is the Best Way to Document Your React Components?
You can have all the money in the world and hire the best web developers to manually create a beautiful site for your documentation but to be honest, that’s just so time-consuming and a burden to make all parts of docs consistent and by the time you try to make it consistent, the entire team is exhausted just to make a doc? Thankfully, the open source community has put in tons of work to create a tool that will help you to create high-quality, professional, powerful, and sleek software documentations. And, before you think that I’m about to make you pay to use that software, well no, the tool I’m about to share with you is absolutely free!
Image source: Medium
It’s Docz. Docz is a popular state-of-the-art open-source tool that allows anyone to create clean and highly customizable custom software documentation sites with fairly minimal effort. Think of it as using Canva to create cool posters. It has got 21.7k stars on GitHub which is a huge thing in software development. Here are some of the features and cool things about Docz:
- Built with Gatsby, a hot open-source framework that is used to create blazing fast static sites that are Progressive Web Apps. And no, you don’t need to know Gatsby to use this tool.
- Based on MDX. MDX is Markdown + JSX. Now you don’t need to understand confusing symbols to create markdowns, but just a bunch of easy-to-use JSX-like syntax.
- Supports TypeScript. It provides native TypeScript support. Everyone likes TypeScript. If you don’t, you probably haven’t spent enough time using it, or you haven’t looked at a large codebase because almost all large JavaScript projects are built using TypeScript.
Quick Start Guide
Before I show you how to use Docz, if you’ve plenty of time, do read the official docs to get a good overview of this tool. If not, keep reading.
- Add Docz as a dependency in your project. Pick one of the commands below depending on your package manager (npm/yarn). Please take note that react and react-dom versions in your app must be greater than 16.8.0. Otherwise, this will not work so upgrade them. Make sure react and react-dom are installed to run the commands;
yarn add docz
npm install docz
- Add a .mdx file anywhere in your project, you are not required to adhere to any file architecture or conventions. You can just copy and paste this code.
---
name: Button
route: /
---
import { Playground, Props } from 'docz'
import Button from './Button'
# Button
<Props of={Button} />
## Basic usage
<Playground>
<Button type="submit">Click me</Button>
<Button>No, click me</Button>
</Playground>
Only a few easy steps are left. Check out the complete article for free on Aviyel. I assure you that this free tool will help you in ways you didn't expect in your software development journey.
Top comments (11)
Informative Piece of Content
Thank you, Hamza. Share it if you don't mind. Feel free to ignore if you're busy.
For anyone using storybook as part of your development MDX is also supported by storybook and some docs on that can be found here: storybook.js.org/docs/react/api/mdx
also nice guide ! :)
Great stuff!!!
Thank you. 😁
Well written !
Thank you, Vanshika. Share it if you don't mind. Feel free to ignore if you're busy.
Wonderful Article.
Thank you, Petrina. Share it if you don't mind. Feel free to ignore if you're busy.
Super cool!
Thank you, share it if you're free.