This article is originally posted on https://aviyel.com/post/894/how-to-manage-your-software-documentation-with-docz
A bunch of users finds documentation to be boring and time-consuming. It is one tedious task for most newbies and intermediate developers. However, documentation is a crucial part of our project, so we can't skip it. It enhances the traceability of your code and helps developers make informed and sound decisions, making it a crucial part of project success. Training costs can be reduced with proper documentation, serving as a single source project repository. Documentation also demonstrates professionalism and is an essential part of project management.
Challenges to managing documentation
Time-consuming process
Hard to manage in complex projects
Editing challenges
Conflict with different users while managing
Document version control challenges
Imagine having a software package to manage all your documentation needs along with your project. You can now give your project complete focus rather than panicking about documentation.
Here’s where Docz comes into the picture.
Documenting code is one of the most essential but time-consuming processes when developing a software. Several extra hours go in vain while building and maintaining custom documentation sites. Docz solves this problem by quickly creating SEO-friendly, live-reloading, production-ready documentation sites with MDX so that you can customise the look, feel, and behaviour when required by leveraging GatsbyJS and Gatsby theme shadowing.
How can Docz help manage documentation?
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 for each component to 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 complicated for you to understand each component and manage them. But with Docz, you can focus on committing codes rather than devoting time on understanding components. Docz is based on zero config so no more extra features to reminisce while curating codes. Let Docz take care of your needs.
Another exciting part about Docz is its open source nature. Anyone can use and contribute to it without spending a single penny. The top contributors and maintainers of this project are Pedro Nauck, Renato Benkerdorf, and Rakan Nimer. To know more about contributors and how to contribute, check it out here!.
Moreover, Docz’s built-in components and their ASTs help developers render and generate documentation with codes, create tables, content, and use custom getters for traversing files. The ‘Playground’ section helps develop and document code components.
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 you can use it and what are the prerequisites?
Prerequisites to Start with Docz
As mentioned above, it works on a component basis. Docz requires a basic understanding of React. I will recommend going through the React official documentation if you want to know more.
Getting Started with Docz
Step 1: Go to your terminal/cmd/git bash and use the command;
npx create-react-app your-project-name
Note: Don't use capital letters in your project name.
cd your-project-name
Step 2: Add Docz as a dependency
npm install docz
Step 3: 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>
Step 4: 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;
Step 5: 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.
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!