🌟 Docz

📝 your React components

Il était une fois …​

  • 1 projet

  • Plusieurs feature teams (React)

  • Une même UX

🤝 Des composants React communs maintenus par tout le monde

Tech Lead 👉 "Benoit Prioux"

binout / ❤️ Asciidoctor (🐜)

lectra

lectra versalis

📖 RTFM !

🤓 : Il faut mettre en place le process de documentation dès le 1er commit !
— Tech Lead
😤 : On en a réellement besoin ? La doc ne sera jamais à jour …​
— Dev

💪 Challenge Accepted

La documentation :

  • doit être simple (et fun) à écrire

  • doit être facilement accessible et utile

  • doit être toujours à jour

Progress Foo

progress foo 1 progress foo 2

README

60266022 72a82400 98e7 11e9 9958 f9004c2f97e1
Figure 1. https://github.com/kefranabg/readme-md-generator

Check up

  • ✅ simple à écrire

  • ✅ facilement accessible et utile

  • ❌ toujours à jour

Living documentation

51fjfN1lKLL. SX380 BO1,204,203,200

Asciidoc FTW !

logo asciidoctor 300

  • Mieux que Markdown (selon moi 😝)

  • Inclusion de code source dans la documentation

Exemple

readme

Code

// tag::props[]
interface ProgressFooProps {
  /** value of progress (min=0, max=100, default is 50) */
  now?: number
}
// end::props[]

const ProgressFoo = ({ now = 50 }: ProgressFooProps) => ....

README.adoc

asciidoc

Check up

  • ✴️ simple à écrire

  • ✅ facilement accessible et utile

  • ✅ toujours à jour

🤔 💡

idea

🚀 Docz 🚀

https://www.docz.site/

  • Basé sur l’écriture de fichiers MDX

  • Génère un site statique

MDX ?

MDX = Markdown + JSX 🤯

# Hello, *world*!

Below is an example of JSX embedded in Markdown.

<div style={{ padding: '20px', backgroundColor: 'tomato' }}>
  <h3>This is JSX</h3>
</div>

Documentation

68747470733a2f2f63646e2d7374642e64707263646e2e6e65742f66696c65732f6163635f3634393635312f533259434944

🤓 Getting Started

npm install docz

Required react et react-dom >= 16.8.0

😎 Typescript support

doczrc.js
export default {
    typescript: true
};

🚀 Build and serve

package.json
"scripts": {
    "docz:dev": "docz dev",
    "docz:build": "docz build",
    "docz:serve": "docz build && docz serve"
}

🛠 Under the hood

Génère un site statique basé sur https://www.gatsbyjs.com/

gatsby

🤩 Built-in components <Props>

Documentation for components props

  • Supports flow, prop-types and Typescript

import { Props } from 'docz'
import ProgressFoo from './ProgressFoo.tsx'

<Props of={ProgressFoo} />

🤩 Built-in components <Props>

interface ProgressFooProps {
  /** value of progress (min=0, max=100, default is 50) */
  now?: number,
  /** variant which defines color (default is info) */
  variant?: 'success' | 'info' | 'warning' | 'danger',
  /** set to true to display a label next to progress bar (default is false) */
  label?: boolean
}

const ProgressFoo = ({ now = 50, variant = 'info', label = false }: ProgressFooProps) => {
  ...
}

🤩 Built-in components <Props>

props

🤩 Built-in components <Playground>

Editable rendering

import { Playground } from 'docz'
import ProgressFoo from './ProgressFoo.tsx'

<Playground>
  <ProgressFoo now={66} variant="success" />
</Playground>

🤩 Built-in components <Playground>

playground

😎 Démo

14865

Check up

  • ✅ simple à écrire

  • ✅ facilement accessible et utile

  • ✅ toujours à jour

One More Thing 🤩

💡 Docz = environnement de développement et d’intégration

😅 Permet d’éviter npm link ou yalc

Feedback 👍

  • 🚀 Mise en place et prise en main

  • 🎭 Facile à customizer

  • 📚 Permet de construire un site de documentation

Feedback 👎

  • 🧐 Support Typescript à améliorer

  • 🐘 Un peu lourd

  • 😤 Des problèmes de cache (🗑 .docz)

Alternative - react-styleguidist

https://github.com/styleguidist/react-styleguidist

logo

Styleguidist

  • Même principe que Docz

# Usage

```jsx
<ProgressFoo now={66} variant="success" />
```

  • Documentation automatique des props

Styleguidist vs Docz

  • 👍 Plus léger

  • 🤓 Intégration avec third-party librairies

  • 😅 Moins customizable

Alternative - storybook

https://storybook.js.org/

011fc620 4cb2 11e9 a51a fdbb10b4cabb e1567090000539

Storybook

  • 😅 Ecriture de stories (code) pour générer un storybook

  • 👍 Supporte les autres frameworks (Vue, Angular, WebComponents)

  • 😎 Large écosystème de plug-in

  • 🥳 Support du MDX depuis 6.0 (août 2020)

Storybook vs Docz

  • 📚 Plus adapté pour une gallerie de composants

  • ✅ Aide au développement et à la testabilité

  • 👨‍🎨 Plus orienté doc UX que doc technique

Pour conclure

  • 🤗 Eco-système riche …​ mais en constante évolution

  • 😛 Fun d’écrire de la documentation

keep calm and document properly