Front-End-Dokumentation, Styleguides und der Aufstieg von MDX

Sie können das beste Open-Source-Projekt der Welt haben, aber wenn es keine gute Dokumentation hat, wird es wahrscheinlich nie erfolgreich sein. Im Büro kann gute Dokumentation Sie davor bewahren, wiederholt dieselben Fragen beantworten zu müssen. Dokumentation stellt sicher, dass die Leute herausfinden können, wie Dinge funktionieren, wenn Schlüsselmitarbeiter das Unternehmen verlassen oder ihre Rollen wechseln. Gut dokumentierte Codierungsrichtlinien helfen, Konsistenz in einer Codebasis zu gewährleisten.

Wenn Sie lange Texte schreiben, ist Markdown eindeutig eine großartige Alternative zur Erstellung von HTML. Manchmal reicht die Markdown-Syntax jedoch nicht aus. Es war schon immer möglich, direkt HTML in Markdown-Dokumente zu schreiben. Dazu gehören benutzerdefinierte Elemente, sodass Sie sie, wenn Sie ein Designsystem mit nativen Webkomponenten erstellen, einfach in Ihre textbasierten Dokumentationen einbinden können. Wenn Sie mit React (oder einem anderen Framework, das JSX spricht, wie Preact oder Vue) arbeiten, können Sie dasselbe tun, indem Sie MDX verwenden.

Dieser Artikel gibt einen breiten Überblick über die verfügbaren Werkzeuge zum Schreiben von Dokumentationen und zum Erstellen von Styleguides. Nicht alle hier aufgeführten Werkzeuge verwenden MDX, aber es wird zunehmend in die Dokumentationswerkzeuge integriert.

Was ist MDX?

Eine Datei .mdx hat exakt die gleiche Syntax wie eine normale Markdown-Datei, ermöglicht aber den Import von interaktiven JSX-Komponenten und deren Einbettung in Ihre Inhalte. Die Unterstützung für Vue-Komponenten befindet sich im Alpha-Stadium. Es ist einfach, MDX mit Create React App einzurichten. Es gibt MDX-Plugins für Next.js und Gatsby. Die kommende Version zwei von Docusaurus wird ebenfalls integrierte Unterstützung bieten.

Dokumentation mit Docusaurus schreiben

Docusaurus wird von Facebook entwickelt und von jedem Facebook-Open-Source-Projekt außer React verwendet. Es wird auch von vielen wichtigen Open-Source-Projekten außerhalb von Facebook verwendet, darunter Redux, Prettier, Gulp und Babel.

A screenshot of logos of all the various frameworks that support Docusaurus, including React, Gulp, Jest, Babel, Redux and Prettier. — Projekte, die Docusaurus nutzen.

Sie können Docusaurus verwenden, um *alles* zu dokumentieren – es ist nicht auf Front-End beschränkt. Docusaurus verwendet React im Hintergrund, aber Sie müssen dieses Framework nicht kennen, um es zu nutzen. Es nimmt Ihre Markdown-Dateien und verwandelt sie in eine gut strukturierte, gut formatierte und lesbare Dokumentationsseite mit einem schönen Design direkt aus der Box.

A screenshot of the Redux documentation homepage with the headline Getting Started with Redux. — Die Redux-Seite zeigt das typische Docusaurus-Layout

Mit Docusaurus erstellte Seiten können auch einen Markdown-basierten Blog enthalten. Prism.js ist standardmäßig für die Syntaxhervorhebung ohne Setup enthalten. Obwohl relativ neu, hat sich Docusaurus als beliebt erwiesen und wurde auf StackShare zum beliebtesten neuen Werkzeug von 2018 gewählt.

Andere Optionen für geschriebene Inhalte

Docusaurus ist speziell für die Erstellung von Dokumentationen konzipiert. Natürlich gibt es eine Million und eine Möglichkeit, eine Website zu erstellen – Sie könnten also Ihre eigene Lösung mit jeder Backend-Sprache, jedem CMS oder jedem statischen Website-Generator entwickeln.

Die Dokumentationsseiten für React, IBMs Designsystem, Apollo und Ghost CMS nutzen Gatsby, zum Beispiel – ein generischer statischer Website-Generator, der oft für Blogs verwendet wird. Wenn Sie mit dem Vue-Framework arbeiten, ist VuePress eine beliebte Option. MkDocs ist ein Open-Source-Generator für statische Websites zur Erstellung von Dokumentationen, geschrieben in Python und konfiguriert mit einer einzigen YAML-Datei. GitBook ist ein beliebtes kostenpflichtiges Produkt, das für Open-Source- und gemeinnützige Teams kostenlos ist. Wenn Sie interne Dokumentationen erstellen und etwas Einfaches möchten, ist die Leseerfahrung auf GitHub selbst nicht schlecht, sodass Sie einfach einige Markdown-Dateien committen und es dabei belassen könnten.

Dokumentation von Komponenten: Docz, Storybook und Styleguidist

Styleguides, Designsysteme, Pattern Libraries – wie auch immer Sie sie nennen wollen – sind in den letzten zehn Jahren zu einem unglaublich beliebten Themenbereich geworden. Was sie wirklich von reinen Eitelkeitsprojekten zu nützlichen Werkzeugen gemacht hat, ist nicht das Pathos von *Vordenkern*, sondern das Aufkommen komponentengesteuerter Frameworks wie React und der hier genannten Werkzeuge.

Storybook, Docz und Styleguidist machen im Grunde dasselbe: Sie zeigen interaktive UI-Komponenten und dokumentieren ihre API. Ein Projekt kann Dutzende oder sogar Hunderte von Komponenten haben, die im Auge behalten werden müssen – alle mit einer Vielzahl von Zuständen und Stilen. Wenn Komponenten wiederverwendet werden sollen, müssen die Leute wissen, dass sie existieren. Wir fördern die Auffindbarkeit, wenn wir Komponenten katalogisieren. Ein Styleguide bietet einen leicht durchsuchbaren und überschaubaren Überblick über alle Ihre UI-Komponenten. Dies hilft, die visuelle Konsistenz zu wahren und doppelte Arbeit zu vermeiden.

Diese Werkzeuge bieten eine bequeme Möglichkeit, verschiedene Zustände zu überprüfen. Es kann schwierig sein, jeden Zustand einer Komponente im Kontext einer echten Anwendung zu reproduzieren. Anstatt durch eine tatsächliche App klicken zu müssen, kann die Entwicklung einer Komponente isoliert hilfreich sein. Schwer erreichbare Zustände (wie z.B. ein Ladezustand) können simuliert werden.

Dan Green schrieb eine nette Zusammenfassung der Vorteile der Verwendung von Storybook, aber sie gilt gleichermaßen für Docz und Styleguidist.

„Storybook hat es Designern, die programmieren, wirklich leicht gemacht, mit Entwicklern zusammenzuarbeiten. Indem sie in Storybook arbeiten, müssen sie keine ganze Umgebung mehr laufen lassen (Docker-Container usw.). Für Wave haben wir viele wichtige Komponenten, die nur während eines Prozesses sichtbar sind, der kurzlebig und zeitaufwendig zu reproduzieren ist (d. h. ein Ladebildschirm, der nur angezeigt wird, während die Zahlungskonto eines Benutzers eingerichtet wird). Vor Storybook hatten wir keine gute Möglichkeit, an diesen Komponenten zu arbeiten, und waren gezwungen, temporäre Hacks zu verwenden, um sie sichtbar zu machen. Jetzt, mit Storybook, haben wir einen isolierten Ort, an dem wir einfach daran arbeiten können, was den zusätzlichen Vorteil hat, dass es für Designer und PMs leicht zugänglich ist. Es macht es uns auch sehr leicht, diese Zustände in Sprint-Demos zu präsentieren.“

– Dan Green, Wave Financial

Neben der Visualisierung verschiedener Zustände nebeneinander und der Auflistung von Props ist es oft hilfreich, schriftliche Inhalte über eine Komponente zu haben – sei es die Erklärung der Design-Begründung, Anwendungsfälle oder die Beschreibung der Ergebnisse von Benutzertests. Markdown ist für *jeden* leicht zu erlernen – idealerweise sollte ein Styleguide eine gemeinsame Ressource für Designer und Entwickler sein, zu der beide Disziplinen beitragen. Docz, Styleguidist und Storybook bieten alle eine Möglichkeit, Markdown nahtlos mit den Komponenten selbst zu vermischen.

Docz

Derzeit ist Docz ein reines React-Projekt, arbeitet aber an der Unterstützung für Preact, Vue und Webkomponenten. Docz ist das neueste der drei Werkzeuge, hat aber bereits über 14.000 Sterne auf GitHub gesammelt. Es ist meiner Meinung nach die einfachste Lösung zum Arbeiten. Docz bietet zwei Komponenten: und . Diese werden importiert und direkt in .mdx-Dateien verwendet.

import { Playground, Props } from "docz";
import Button from "../src/Button";

## You can _write_ **markdown**
### You can import and use components

<button>click</button>

Sie können Ihre eigenen React-Komponenten mit umwickeln, um das Äquivalent eines eingebetteten CodePen oder CodeSandbox zu erstellen – eine Ansicht Ihrer Komponente neben editierbarem Code.

  <button>click</button>

zeigt alle verfügbaren Props für eine gegebene React-Komponente, Standardwerte und ob der Prop erforderlich ist.

Ich persönlich finde diesen MDX-basierten Ansatz am einfachsten zu verstehen und am einfachsten zu bearbeiten.

A screenshot of a Code Sandbox project making use of the tool to document the code for a Button component.

Wenn Sie ein Fan des React-basierten statischen Site-Generators Gatsby sind, bietet Docz großartige Integration.

Styleguidist

Genau wie bei Docz werden Beispiele mit Markdown-Syntax geschrieben. Styleguidist verwendet Markdown Codeblöcke (dreifache Backticks) in normalen .md-Dateien anstelle von MDX.

```js
<button> console.log('clicked')&gt;Push Me</button>
```

Codeblöcke in Markdown *zeigen normalerweise nur den Code*. Mit Styleguidist wird jeder Codeblock mit einem Sprach-Tag von js, jsx oder javascript als React-Komponente zusammen mit dem Code gerendert. Genau wie bei Docz ist der Code editierbar – Sie können Props ändern und sofort das Ergebnis sehen.

A screenshot of the output of the documentation for a pink button made with Styleguidist.

Styleguidist erstellt automatisch eine Tabelle der Props aus PropTypes-, Flow- oder TypeScript-Deklarationen.

A screenshot of a table of values that Styleguidiist generated for the pink button documentation, including values it accepts.

Styleguidist unterstützt derzeit React und Vue.

Storybook

Storybook vermarktet sich selbst als „ein *Entwicklungsumfeld* für UI-Komponenten.“ Anstatt Beispiele von Komponenten in Markdown- oder MDX-Dateien zu schreiben, schreiben Sie *Stories* in JavaScript-Dateien. Eine *Story* dokumentiert einen bestimmten Zustand einer Komponente. Eine Komponente kann zum Beispiel Stories für einen Ladezustand und einen deaktivierten Zustand haben.

storiesOf('Button', module)
  .add('disabled', () =&gt; (
    <button disabled="disabled">lorem ipsum</button>
  ))

Storybook ist weniger geradlinig zu bedienen als Styleguidist und Docz. Mit über 36.000 GitHub-Sternen ist es jedoch die beliebteste Option. Es ist ein Open-Source-Projekt mit 657 Mitwirkenden und einem *Vollzeit*-Maintainer. Es wird unter anderem von Airbnb, Algolia, Atlassian, Lyft und Salesforce verwendet. Storybook unterstützt mehr Frameworks als jede andere Lösung – React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte und reines HTML werden alle unterstützt.

Das Schreiben von Dokumentationen über Komponenten erfordert derzeit Add-ons. In einer zukünftigen Version lässt sich Storybook von Docz inspirieren und übernimmt MDX.

# Button

Some _notes_ about your button written with **markdown syntax**.


  <button disabled="disabled">lorem ipsum</button>

Die neue Docs-Funktion von Storybook wird in den nächsten Monaten schrittweise eingeführt und scheint ein großer Schritt nach vorn zu sein.

Verwenden Sie @storybookjs für Komponentendokumentationen oder Designsysteme? Sie werden DocBlocks lieben
📦 Nahtlos in MDX integrierbar
🏗 Modular und komponierbar
🤝 Kompatibel mit @gatsbyjs, #nextjs, etc.

🔜 https://#/AmE4l9B3FU von @mshilman pic.twitter.com/Q48PQCmiEt

— Dominic Nguyen (@domyen) 28. April 2019

Zusammenfassung

Die Vorteile von Pattern Libraries wurden in unzähligen Medium-Artikeln bis zum Erbrechen gepriesen. Wenn sie gut gemacht sind, fördern sie die visuelle Konsistenz und erleichtern die Schaffung kohärenter Produkte. Natürlich kann keines dieser Werkzeuge ein Designsystem herzaubern. Das erfordert sorgfältige Überlegungen sowohl zum Design als auch zu CSS. Aber wenn es darum geht, dieses System dem Rest einer Organisation zu vermitteln, sind Docz, Storybook und Styleguidist alle großartige Optionen.