Suchitra

Posted on Sep 24, 2021 • Edited on Mar 30, 2022 • Originally published at aviyel.com

How to manage your software documentation with docz!

#react #beginners #management #typescript

So, before starting the topic, I want to ask you one thing is...

How do you think about documentation of your project?

It's probably boring or time-consuming as well as very tedious task, right!!

But also the documentation is very important part of our project, we can't skip it. Because if project doesn't have the documentation then how much great and useful the project is. It would be useless if no one can understand and use the project.

So, what if you have something which can manage your documentation along with your project. And you can give your full focus on your project, rather of panicking about documentation.
Here, Docz comes into the picture.

So, let get started…

Introduction
What makes Docz a brilliant documentation tool?
Prerequisite
Getting Started with Docz
Conclusion

Introduction to Docz

Documenting code is one of the most important and time-heavy processes when developing software.

A lot of time is spent on building and maintaining custom documentation sites.

Docz was created to solve this problem.

Docz enables you to quickly create live-reloading, seo-friendly, production-ready documentation sites with MDX and customize the look, feel and behavior when required by leveraging GatsbyJS and Gatsby theme shadowing.

In simple, word Docz makes it easy to write and publish beautiful interactive documentation for your code. Create MDX files showcasing your code and Docz turns them into a live-reloading, production-ready site.
It enables you to manage your React components by creating documentation of each component and so that it can help you in your project documentation.
Suppose if you are working on a big and complex project where lots of components are present. In this case, it might be complex to you for understanding each component and managing the component parts. But it would be easy if you use Docz because it will manage everything on behalf of you by creating the docs.
Visit here to know more

Docz is an open source project:

The interesting part of Docz is… it is an open source project, anyone can use and contribute to it (without spending a single penny).
The top contributors and maintainer of this project are Pedro Nauck, Renato Benkerdorf and Rakan Nimer. For know more about contributors and want to contibute. Then go through this link.

Another interesting part of Docz is... Docz itself made up of Docz link.

What makes Docz a brilliant documentation tool?

Powered by Gatsby

Docz is built using GatsbyJS. It's optimised for a lightning-fast development experience and build times. It also allows you to leverage GatsbyJS's massive ecosystem of plugins and tools.

Zero config

It has zero configuration and is easy to learn. Avoid unnecessary build steps with confusing setups.

Easy to customize

Customization is effortless. You can customize the provided theme to make your documentation website stand out.

Based on MDX

MDX is Markdown + JSX. It brings the world of components to Markdown and the best standard for writing documentation.

Fully pluggable

Plugins provide a great way to add functionality to your application without changing your code. Docz supports GatsbyJS plugins and some of the indigenously made Docz plugins.

TypeScript support

Docz provides native TypeScript support for TSX components and can generate documentation from your prop types and comments in your code.

Now, you might be thinking about how can you use it?, what are the prerequisites?, and also might be interested to use it?...

Prerequisite

As, I mentioned the above that it works on component basis, so the prerequisite is... it would be great if you are familiar with React. But don't worry if you don't know It's totally fine, you can still follow along with me.
But I will recommend you to go through the React official documentation. If you want to know more.

Getting Started with Docz

Go to your terminal/cmd/git bash Use this command:

npx create-react-app your-project-name

Note : Don't use capital letters in your project name.
Then

cd your-project-name

Add docz as a dependency

npm install docz

Then, add .mdx files anywhere in your project:

---
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>

And a Button component, Button.jsx:

import React from 'react';
import t from 'prop-types';

const Button = ({ children, type }) => <button type={type}>{children}</button>

Button.propTypes = {
  /**
   * This is a description for this prop.
   * Button type.
   */
  type: t.oneOf(['button', 'submit', 'reset']),
}
Button.defaultProps = {
  type: 'button',
}
export default Button;

Finally, run:

npx docz dev

This will start a local development server and open your documentation site in the browser.

You can also follow an alternate method to start working with Docz by using create-docz-app.

Conclusion

Managing documentation is not an easy task. But a few communities of developers have made it with products like Docz. Docz’s open source nature makes it affordable, easy to use and create documentation within a heap of seconds.

So, are you excited to use Docz in your next project?
Do let me know in the comment section below. I hope you enjoyed reading.

Do check my article which is officially published here👉 Aviyel

If you want to support😀