Menu Close
Docz – how to make frontend documentation
Development

Docz – how to make frontend documentation

Posted on 04/06/2019
4 min read

Writing frontend documentation is one of the most neglected tasks in software development even though it helps to fight technical debt.

Fortunately, there is an open-source tool that makes frontend documentation easy, pleasant and valuable for the entire team. The tool is called Docz.

What you’ll learn about frontend documentation and Docz in this article:

  • Why should we document frontend?
  • What is Docz?
  • How does Docz work?
  • Which features of Docz do I find the best?

What is frontend documentation for?

Usually, when we speak of documenting software, we mean backend documentation that allows developers to test server responses, check the endpoints to connect with or document how functions work.

Frontend documentation serves a different purpose. It shows how visual elements of the interface behave under different circumstances.

Project documentation is especially important when we’re:

  1. taking over a project from a different team;
  2. introducing new developers to our team;
  3. coming back to an old project after several months;
  4. creating similar components in another project with the same technologies.

In all the cases above, a proper documentation reduces the onboarding time by helping developers understand how the code works.

What is Docz?

Docz is a fresh tool for creating frontend documentation. Its beta version was released in early 2019 and then version 1.0 on the 21st of March 2019.  Though the tool is very young, the community around it is quite impressive and active. I observe at least one significant update a week on Docz’s Github.

Docz github

Docz works especially well for React and Typescript projects but can support other frameworks as well. For example, to support Vanilla JS, it’s enough if you install a package called prop-types. One can also add providers such as Redux to Docz.

What makes Docz different from other documenting tools is a super easy installation. The only dependency is the need to install the newest version of React.

How to install and use Docz?

The basic installation is as easy as writing two lines of code.

  1. You need to install Docz with a default theme. If you wish, you can modify the theme by adding the project logo or other information. You can also create your own theme.
    $ yarn add docz docz-theme-default --dev
  2. Then spin up your dev server by running
    $ yarn docz:dev

After going to localhost:3000 you’ll see a plain Docz environment.

Then, if you wish, you can configure the tool by installing plugins or styling it the way you want.

After the installation, the only thing you need to do is to create an .md or .mdx files with documentation in any place of our project. It means that you can e.g. create a catalogue with the documentation of the entire component or a section. No matter how distributed our files are, Docz will put them together.

docz documentation

Mdx files in Docz

Docz uses .mdx files which are an interactive hybrid between a markdown file and a jsx file. Mdx files enable using React components or js code such as interactive charts with inside of the documentation files with all standard properties of markdown files.

Here’s an example of how it looks.

---
name: Preloader Button
menu: Components
route: /components/preloader-button
---

import { Props, Playground, Link } from 'docz';
import { PreloaderButton } from './preloader-button';

# Preloader Button

## Properties
<Props of={PreloaderButton} />

## Best practices
- Use `isPending` from redux-store to define whether button is loading or not
- If you don't want to call any function after click/touch, pass `noop` function from /core/helpers as `onClick` prop

## Basic usage

### Like a standard button
<Playground>
  <PreloaderButton
      color="blue"
      onClick={() => console.log('clicked!')}
      isLoading={false}
  >
    I'm not loading
  </PreloaderButton>
</Playground>

### Loading button
<Playground>
  <PreloaderButton
      color="blue"
      onClick={() => console.log('clicked!')}
      isLoading={true}
  >
    I'm Loading
  </PreloaderButton>
</Playground>

### Disabled button
<Playground>
  <PreloaderButton
      color="blue"
      onClick={() => console.log('you cant click me')}
      isLoading={false}
      isDisabled={true}
  >
    I'm disabled
  </PreloaderButton>
</Playground>

## See also
- <Link to="/components/preloader">Preloader</Link>

When you add a file name and menu at the top of each file, Docz will find its way to create a navigation in the .mdx file.

Documenting components with Docz

One of the coolest things in Docz is that you can document components inside of .mdx files. Let’s take a look at the example of a text area that is a common generic component in many projects.

A component is documented in Docz through <Props> that fetches its properties and places them in a table inside of an .mdx file. Docz takes the components from the code and places all properties in a table without the need to rewrite the code. What’s more, the comments we place above the properties are also displayed.  

Creating a frontend component takes only a few seconds and if you pay attention to how you create interfaces and name types, the frontend code practically self documents.

The table with props contains in particular:

  • Component name
  • Component type
  • A flag whether the component is required or not
  • An optional description

All of these properties go straight to the documentation with a single line of code.

<Props of={TextArea} />

Using additional markdowns in the code may seem like overkill that requires discipline but it structures the code nicely and helps the entire team keep up to high coding standards. It may be annoying in the projects that already exist but should not make any trouble in the ones we write from scratch.

---
name: Textarea
menu: Components
route: /components/textarea
---

import { Props, Playground, Link } from 'docz';
import { TextArea } from './components/textarea';

# Textarea

## Properties
<Props of={TextArea} />

## Basic usage
<Playground>
  <TextArea resizeProp="vertical" placeholder="type something..." />
</Playground>

## Se also
- <Link to="/components/text">Text</Link>
- <Link to="/components/title">Title</Link>

docz documentation example

Docz playground component

Another killer feature of Docz is so-called Playground component. It’s a special area in the documentation where we can play with the component under different circumstances. Let’s take a look at how a preloader button component behaves with different display width or breakpoints.


A playground is a fantastic tool for anyone who enters a new project and needs to use components that already exist in the project. Thanks to Docz, the new developer doesn’t need to constantly compile and reload the application. It’s enough if they review the component’s behaviour in Docz.  

Application flow in Docz

The tool allows documenting the flow of the entire application in a full-screen mode. Thanks to that, we’re able to show each screen and describe which action triggers the next step.

Such flow documentation helps developers speed up their project onboarding and understand the user journey throughout the application. Our backend developers appreciate using Docz especially when they build APIs for new features as they don’t need to ask frontend colleagues about each tiny detail.

On the other hand, since Docz is a part of code repository, we’re able to show it to our client to prove that the application works exactly as expected and planned.

Alternatives for Docz

Of course, Docz is not the only way to document frontend but it’s the most interactive one I’ve ever come across.

The most popular alternative is called Jsdocs and requires to describe each input and field or generate a template from e.g. Visual Studio Code. It’s more time consuming and still less attractive. What’s more, Jsdocs miss the interactive .mdx files I find one of the strongest points of using Docz as frontend documentation tool.

Summary

I hope I made you consider using Docz for your next frontend project. The reasons why I like doing so are that

  • Docz is super easy to work with
  • It requires writing better-structured interfaces
  • I’m able to make a base of components I can use in further projects

There are new things coming up in Docz in the nearest future. Support for React Native will be enhanced. Currently, you’re able to import and describe React Native components separately. Docz will support more and more frameworks, with Vue coming up soon. With more supported frameworks, using Docz for frontend documentation makes even more sense.


About the author

Adam Kruczek
Adam Kruczek
Front-end Developer

Enjoys programming since 2017. Builds modern web applications in top Javascript frameworks applying agile development methods during everyday work. Fascinated with creating Cross-Platform mobile apps using React Native.

See other blog categories

Business

Tips, trends and business insights for startups and growing companies.

Culture

Team building, team development and values that build a conscious organisation.

Development

Top frameworks, technologies and development tips from our team.

Project management

Everything you need to know about project management to make your projects successful.

Let’s talk!

Get an estimate of your project’s time and cost.