Front-End-Dokumentation, Style Guides und der Aufstieg von MDX

0
37

Sie können die besten open-source-Projekt in der Welt, aber, wenn es keine gute Dokumentation, die Chancen sind es wird nie ausziehen. Im Büro, eine gute Dokumentation sparen könnte, dass Sie immer wieder dieselben Fragen beantworten. Die Dokumentation sorgt dafür, dass Menschen herausfinden können, wie die Dinge funktionieren, wenn der Schlüssel Mitarbeiter entscheiden, das Unternehmen zu verlassen oder ändern Sie Rollen. Gut dokumentiert coding-guidelines helfen, die Konsistenz zu einer Codebasis.

Wenn Sie schreiben long-form text, Markdown ist eindeutig eine gute alternative zum erstellen von HTML. Manchmal aber, Markdown-syntax ist nicht genug. Es ist immer möglich, schreiben direkt HTML innerhalb von Markdown-Dokumenten. Dazu gehören benutzerdefinierte Elemente, so, wenn Sie ein design-system mit nativen web-Komponenten, ist es leicht zu integrieren Sie in Ihren text-basierte Dokumentation. Wenn Sie arbeiten, Reagieren (oder einem anderen framework, das spricht JSX, wie Preact oder Vue), können Sie das gleiche tun, indem mithilfe von MDX.

Dieser Artikel wird einen groben überblick über die verfügbaren tools für das schreiben von Dokumentation und für den Aufbau Stil-Führer. Nicht alle tools, die hier aufgeführt nutzen MDX-aber es ist zunehmend eingebunden in die Dokumentation Werkzeuge.

Was ist MDX?

Ein .mdx-Datei hat genau die gleiche syntax wie eine regelmäßige Markdown-Datei, jedoch können Sie importieren interaktive JSX-Komponenten und integrieren Sie diese in Ihre Inhalte. Unterstützung für Vue-Komponenten ist in der alpha. Es ist leicht zu bekommen MDX einrichten, Erstellen Sie Reagieren, App. Es gibt MDX-plugins für Next.js und Gatsby. Die bevorstehende version zwei release von Docusaurus wird auch kommen mit eingebauter Unterstützung.

Die Dokumentation mit Docusaurus

Docusaurus von gemacht und von jedem open-source-Projekt, abgesehen von Reagieren. Es ist auch verwendet durch viele große open-source-Projekte außerhalb , einschließlich Redux, Schöner, Schlucken und Babel.

Projekte nutzen Docusaurus.

Sie können Docusaurus zu dokumentieren nichts — es ist nicht die front-end-spezifisch. Docusaurus verwendet Reagieren unter der Haube, aber Sie nicht haben, um zu wissen, dass framework Gebrauch zu machen. Es wird nehmen Sie Ihre Markdown-Dateien und verwandeln Sie diese in einen gut strukturierten, gut formatierte und lesbare Dokumentation Ort, mit einem schönen design, direkt aus der box.

Die Redux-Website zeigt das typische layout Docusaurus

Seiten erstellt mit Docusaurus kann auch ein Markdown-basierten blog. Prism.js standardmäßig enthalten ist, für null-setup-syntax-highlighting. Während relativ neu, Docusaurus hat sich als beliebt herausgestellt, abgestimmt wird der Nummer ein neues tool von 2018 auf StackShare.

Andere Optionen für geschriebene Inhalte

Docusaurus, die speziell richtet sich an Bau-Dokumentation. Natürlich, es gibt eine million und eine Möglichkeiten, um eine website zu machen — so könnte man Rollen Sie Ihre eigene Lösung, die mit beliebigen Backend-Sprache, CMS oder statische Website-generator.

Die Dokumentation Standorte für Reagieren, IBM-design-system, Apollo und das Ghost-CMS verwenden Gatsby, zum Beispiel — eine generische, statische Website-generator, der oft für blogs. Wenn Sie die Arbeit mit dem Vue-framework, VuePress ist immer eine beliebte option. MkDocs ist ein open-source-static-site-generator für das erstellen von Dokumentationen, in Python geschrieben und konfiguriert mit einem einzigen YAML-Datei. GitBook ist ein beliebtes Produkt bezahlt, das ist kostenlos für open-source und non-profit-teams. Wenn Sie erstellen die interne Dokumentation und wollen etwas einfach, das lese-Erlebnis auf GitHub selbst ist nicht halb so schlimm, so konnte man nur Begehen einige Markdown-Dateien und es dabei belassen.

Dokumentation Komponenten: Docz, Storybook und Styleguidist

Style guides, design, Systeme, Muster-Bibliotheken, was immer Sie wollen, Sie zu nennen — haben sich zu einem beliebten Thema in den letzten zehn Jahren. Was wirklich den Unterschied in der Drehung aus Eitelkeit Projekte in nützliche tools, die nicht die pontificating von Meinungsführern, sondern die Entstehung von component-driven frameworks, wie Reagieren, und die Instrumente, die hier erwähnt.

Bilderbuch, Docz und Styleguidist alle viel tun, die gleiche Sache: display-interaktive UI-Komponenten und der Dokumentation der API. Ein Projekt kann Dutzende oder sogar Hunderte von Komponenten zu verfolgen — alle mit einer Vielzahl an Staaten und Stile. Wenn Sie möchten, dass die Komponenten wiederverwendet werden, die Menschen müssen wissen, dass Sie existieren. Wir Hilfe Auffindbarkeit, wenn wir Katalog-Komponenten. Ein style-guide gibt eine leicht durchsuchbare und scannbarer übersicht aller UI-Komponenten. Diese zu erhalten hilft, eine optische Konsistenz und vermeiden Sie überschneidungen in der Arbeit.

Diese tools bieten eine bequeme Möglichkeit zum überprüfen verschiedener Staaten. Es kann schwierig sein, zu reproduzieren, die jedem Zustand einer Komponente im Kontext einer realen Anwendung. Anstatt zu müssen durch das klicken auf eine tatsächliche app, die Entwicklung einer Komponente in isolation hilfreich sein kann. Hart-zu-erreichen-Staaten (wie eine be-Staat, zum Beispiel) können werden verspottet.

Dan Green schrieb eine schöne Zusammenfassung der Vorteile der Verwendung von Bilderbuch, aber es gilt gleichermaßen für Docz und Styleguidist:

“Storybook hat es wirklich einfach für die Designer, die code zur Zusammenarbeit mit Ingenieuren. Durch die Arbeit in den Märchen, die Sie nicht brauchen, um eine ganze Umgebung ausgeführt (docker-container, etc). Für die Welle, wir haben viele wichtige Komponenten, die nur dann sichtbar sind, in der Mitte eines Prozesses, der nur von kurzer Dauer und zeitaufwendig zu reproduzieren (d.h. ein lade-Bildschirm, der nur zeigt, während ein Benutzer ist mit Ihren payment-Konto einrichten). Bevor Bilderbuch, die wir nicht haben, ein guter Weg, um arbeiten an diesen Komponenten und waren gezwungen, temporäre hacks, um sichtbar zu machen. Jetzt, mit Storybook wir haben einen einsamen Ort, um einfach an Ihnen arbeiten, die das bonus-feature wird leicht zugänglich für Designer und PMs. Es macht es auch wirklich einfach für uns zu zeigen, diese Staaten im sprint-demos.”

– Dan Green, Wave Financial

Sowie die Visualisierung unterschiedlicher Zustände side-by-side und Liste der Requisiten, Ihre oft hilfreich geschrieben zu haben, die Inhalte über ein Komponente — ob seine Erklärung der design-Grundlagen, Anwendungsfälle, oder die Beschreibung der Ergebnisse des user-Tests. Markdown ist einfach genug für *niemanden* zu lernen — idealerweise in einem style guide ist eine gemeinsame Ressource für Designer und Entwickler, dass beide Disziplinen beitragen. Docz, Styleguidist und Storybook alle bieten eine Möglichkeit, nahtlos zu vermischen Markdown mit den Komponenten selbst.

Docz

Derzeit Docz ist ein Reagieren-nur Projekt, sondern arbeitet an Unterstützung für Preact, Vue-und web-Komponenten. Docz ist das neueste der drei tools, hat aber schon Betrug über 14.000+ Sterne auf GitHub. Es ist, meiner Meinung nach, die einfachste Lösung zu arbeiten. Docz bietet zwei-Komponenten — <Spielwiese> und <Props>. Diese werden importiert und direkt verwendet .mdx-Dateien.

import { Spielplatz, Props } von “docz”;
Schaltfläche “importieren” von “../src/ – Taste”;

## Sie können _write_ **markdown**
### Sie können importieren und verwenden von Komponenten

<Button>klicken</Button>

Sie können wickeln Sie Ihre eigenen Komponenten Reagieren mit <Spielwiese> zu erstellen, das entspricht einer embedded CodePen oder CodeSandbox — eine Ansicht der Komponente, die neben der editierbaren code.

<Spielwiese>
<Button>klicken</Button>
</Spielplatz>

<Props> zeigt alle verfügbaren Requisiten für eine bestimmte Reagieren Komponente, default-Werte, und ob die Stütze ist erforderlich.

<Props={Button} />

Ich persönlich finde diese MDX-basierten Ansatz ist am einfachsten zu verstehen und am einfachsten zu arbeiten mit.

Wenn Sie ein fan des Reagieren-based static Website generator Gatsby, Docz bietet tolle integration.

Styleguidist

Genau wie mit Docz, Beispiele geschrieben werden mit Markdown-syntax. Styleguidist verwendet Markdown-code-Blöcke (triple backticks) in regelmäßigen .md-Dateien anstatt MDX:

“js
<Button onClick={() => console.log(‘angeklickt’)>Push Me</Button>

Code-Blöcke in Markdown in der Regel zeigen nur den code. Mit Styleguidist, jedem code-block mit einem language-tag, js, jsx oder javascript dargestellt wird, als ein Reagieren Komponente zusammen mit dem code. Genau wie mit Docz, der code ist editierbar — Sie können ändern, Requisiten und sehen Sie sofort das Ergebnis.

Styleguidist wird automatisch eine Tabelle erstellen, in der Requisiten aus entweder PropTypes -, Durchfluss-oder Typoskript-Deklarationen.

Styleguidist unterstützt derzeit Reagieren und Vue.

Storybook

Bilderbuch vermarktet sich selbst als “eine Entwicklungsumgebung für UI-Komponenten.” Anstatt das schreiben Beispiele von Komponenten im Markdown-oder MDX-Dateien, die Sie schreiben *Geschichten* in Javascript-Dateien. A *Geschichte* Dokumente, die einen bestimmten Zustand einer Komponente. Eine Komponente könnte Geschichten für ein lade-Zustand und einem deaktivierten Zustand, zum Beispiel.

storiesOf(‘Button’, Modul)
.add(‘disabled’, () => (
<Button disabled>lorem ipsum</Button>
))

Storybook ist weniger einfach zu benutzen als Styleguidist und Docz. Auf über 36.000 GitHub Sterne obwohl, es ist die beliebteste option. Es ist ein open-source-Projekt mit 657 Mitarbeiter und ein Vollzeit-Betreuer. Es wird verwendet, unter anderem Airbnb, Algolia, Atlassian, Lyft, und Salesforce. Storybook unterstützt mehr frameworks als jede andere Lösung—, Reagieren, Reagieren Nativen, Vue, Winkel -, Mithril, Ember, Aufruhr, Schlank und HTML werden unterstützt.

Die Dokumentation über die Komponenten derzeit nur über addons. In einer zukünftigen Version, Storybook ist inspiriert von Docz und die Annahme MDX.

# Taste

Einige _notes_ über Ihre Schaltfläche geschrieben mit **markdown-syntax**.

<Geschichte name=”disabled”>
<Button disabled>lorem ipsum</Button>
</Story>

Storybook-die neue Docs-Funktion wird ausgerollt wird schrittweise über die nächsten paar Monate und sieht ein großer Schritt nach vorne.

Verwenden Sie @storybookjs für die Komponente docs oder design-Systeme? Sie sind gonna love DocBlocks:
📦 Drop in MDX
🏗 Modular und zusammenstellbar
🤝 Kompatibel w/ @gatsbyjs, #nextjs, etc

🔜 https://t.co/AmE4l9B3FU @mshilman pic..com/Q48PQCmiEt

— Dominic Nguyen (@domyen) April 28, 2019

Zusammenfassung

Die Vorteile des Muster-Bibliotheken wurden gepriesen, bei ekelerregenden Länge in einer Millionen Mittel-Artikeln. Wenn gut gemacht, kann Sie helfen, die visuelle Konsistenz und erleichtern das erstellen von zusammenhängenden Produkten. Natürlich keines dieser tools können Magie bis ein design-system. Das braucht sorgfältige Gedanken über design und CSS. Aber wenn es darum geht, Zeit zu kommunizieren, dass das system um den rest einer Organisation, Docz, Storybook und Styleguidist sind alle große Möglichkeiten.