Sie können das beste Open-Source-Projekt haben, aber ohne gute Dokumentation wird es wahrscheinlich nie richtig durchstarten. Gute Dokumentation im Büro hilft Ihnen, nicht ständig die gleichen Fragen beantworten zu müssen. Sie stellt auch sicher, dass Mitarbeiter, die das Unternehmen verlassen oder die Rolle ändern, sich im Projekt zurechtfinden können. Lebensnahe Richtlinien helfen, die Integrität der Daten zu gewährleisten.
Wenn Sie längere Texte schreiben müssen, ist Markdown eine hervorragende Alternative zu HTML. Manchmal reicht die Syntax von Markdown nicht aus. In diesem Fall können wir HTML innerhalb von Markdown verwenden, z. B. für benutzerdefinierte Elemente. Wenn Sie also ein Design-System mit nativen Webkomponenten erstellen, lassen sich diese einfach in die Textdokumentation integrieren. Wenn Sie React (oder ein anderes JSX-Framework wie Preact oder Vue) verwenden, können Sie dasselbe auch mit MDX tun.
Dieser Artikel ist ein umfassender Überblick über Werkzeuge zur Erstellung von Dokumentationen und zur Erstellung von Richtlinien. Nicht alle hier aufgeführten Werkzeuge verwenden MDX, doch es wird zunehmend in Dokumentationswerkzeuge integriert.
Was ist MDX?
Die Datei .mdx hat die gleiche Syntax wie Markdown, ermöglicht jedoch das Importieren von interaktiven JSX-Komponenten und deren Einbettung in Ihren Inhalt. Die Unterstützung für Vue-Komponenten befindet sich in der Alpha-Phase. Um mit MDX zu beginnen, genügt es, "Create React App" zu installieren. Es gibt Plugins für Next.js und Gatsby. Die nächste Version von Docusaurus (Version 2) wird ebenfalls über integrierte Unterstützung verfügen.
Dokumentation mit Docusaurus erstellen
Docusaurus wurde von Facebook entwickelt. Sie nutzen es in jedem ihrer Open-Source-Projekte, außer React. Außerhalb des Unternehmens wird es auch von Redux, Prettier, Gulp und Babel verwendet.
Projekte, die Docusaurus verwenden.
Docusaurus kann verwendet werden, um jede Dokumentation zu schreiben, nicht nur zur Beschreibung von Frontend. Es basiert auf React, aber um es zu nutzen, müssen Sie nicht mit React vertraut sein. Es nimmt Ihre Markdown-Dateien, fügt eine Prise Magie hinzu, und schon ist die gut strukturierte, formatierte und lesbare Dokumentation mit ansprechendem Design fertig.
Auf der Website von Redux kann man sich die Standardvorlage von Docusaurus anschauen.
Mit Docusaurus erstellte Websites können auch einen Markdown-basierten Blog enthalten. Die Syntaxhervorhebung erfolgt sofort durch Prism.js. Obwohl Docusaurus erst vor relativ kurzer Zeit auf den Markt kam, wurde er 2018 von StackShare als das beste Tool ausgezeichnet.
Weitere Optionen zur Erstellung von Inhalten
Docusaurus wurde speziell zur Erstellung von Dokumentationen entwickelt. Natürlich gibt es unzählige Möglichkeiten, eine Website zu erstellen — Sie können Ihre eigene Lösung in jeder Sprache oder CMS bereitstellen oder einen statischen Website-Generator verwenden.
Zum Beispiel nutzen die Dokumentation für React, das Designsystem von IBM, Apollo und Ghost CMS Gatsby — einen statischen Website-Generator, der häufig für Blogs verwendet wird. Wenn Sie mit Vue arbeiten, ist VuePress eine gute Option für Sie. Eine weitere Möglichkeit ist die Verwendung eines mit Python geschriebenen Generators — MkDocs. Dieser ist Open Source und wird über eine YAML-Datei konfiguriert. GitBook ist ebenfalls eine gute Wahl, aber kostenlos nur für öffentliche und nicht-kommerzielle Teams. Außerdem können Sie einfach Markdown-Dateien hochladen, indem Sie Git verwenden und mit ihnen in GitHub arbeiten.
Dokumentation von Komponenten: Docz, Storybook und Styleguidist
Richtlinien, Designsysteme, Komponentenbibliotheken – ganz gleich, wie Sie es nennen, dieses Konzept hat in letzter Zeit stark an Popularität gewonnen. Das Aufkommen von Komponentenframeworks wie React und der hier erwähnten Tools hat sie von bloßen Eitelkeitsprojekten in nützliche Werkzeuge verwandelt.
Storybook, Docz und Styleguidist erfüllen alle denselben Zweck: Sie stellen interaktive Elemente dar und dokumentieren deren APIs. Ein Projekt kann Dutzende oder sogar Hunderte von Komponenten umfassen – jede mit unterschiedlichen Zuständen und Stilen. Damit Komponenten wiederverwendet werden, müssen die Anwender wissen, dass sie existieren. Dazu reicht es aus, die Komponenten zu katalogisieren. Richtlinien bieten eine durchsuchbare Übersicht über all Ihre Komponenten. Das hilft, visuelle Konsistenz zu gewährleisten und Doppelarbeit zu vermeiden.
Diese Werkzeuge bieten eine einfache Möglichkeit, verschiedene Zustände anzuzeigen. Es kann schwierig sein, jeden Zustand einer Komponente im Kontext einer realen Anwendung zu reproduzieren. Anstatt in der realen Anwendung herumzuklicken, ist es sinnvoll, eine separate Komponente zu entwickeln. Seltene Zustände (wie z.B. den Ladezustand) können modelliert werden.
Neben der visuellen Darstellung verschiedener Zustände und einer Liste von Eigenschaften ist es oft notwendig, eine allgemeine Beschreibung des Inhalts zu schreiben – Designbegründungen, Anwendungsfälle oder Beschreibungen der Ergebnisse von Benutzertests. Markdown ist sehr einfach zu erlernen – idealerweise sollten die Richtlinien eine gemeinsame Ressource für Designer und Entwickler sein. Docz, Styleguidist und Storybook bieten eine Möglichkeit, Markdown nahtlos mit Komponenten zu kombinieren.
Docz
Momentan funktioniert Docz nur mit React, jedoch wird aktiv an der Unterstützung von Preact, Vue und Web-Komponenten gearbeitet. Docz ist das neueste der drei Werkzeuge, hat jedoch auf Github bereits über 14.000 Sterne gesammelt. Docz präsentiert zwei Komponenten – <Playground> und < Props >. Sie werden in den Dateien importiert und verwendet. .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## Sie können _Markdown_ **schreiben**
### Sie können Komponenten importieren und verwenden
Sie können Ihre eigenen React-Komponenten mithilfe von <Playground>, um ein ähnliches Erlebnis wie bei CodePen oder CodeSandbox zu schaffen — das bedeutet, Sie sehen Ihre Komponente und können sie bearbeiten.
<Props> zeigt alle verfügbaren Eigenschaften für diese React-Komponente, deren Standardwerte und ob eine Eigenschaft erforderlich ist.
>Persönlich halte ich diesen MDX-basierten Ansatz für den einfachsten zum Verstehen und einfachsten in der Handhabung.
Wenn Sie ein Fan des Gatsby-Statischen-Seiten-Generators sind, bietet Docz eine großartige Integration.
Styleguidist
Wie bei Docz werden Beispiele im Markdown-Syntax geschrieben. Styleguidist verwendet Markdown-Codeblöcke (dreifache Anführungszeichen) in regulären Dateien .md Dateien, nicht in MDX.
```js
Codeblöcke in Markdown zeigen normalerweise einfach nur den Code. Wenn Sie Styleguidist verwenden, wird jeder Codeblock mit der Sprache js, jsx oder javascript als React-Komponente angezeigt. Wie bei Docz ist der Code editierbar — Sie können Eigenschaften ändern und sofort das Ergebnis sehen.
Styleguidist erstellt automatisch eine Eigenschaftstabelle aus PropTypes, Flow oder TypeScript-Deklarationen.
Styleguidist unterstützt jetzt React und Vue.
Storybook
Storybook positioniert sich als „Entwicklungsumgebung für UI-Komponenten“. Anstatt Beispiele für Komponenten innerhalb von Markdown- oder MDX-Dateien zu schreiben, schreiben Sie Geschichten in JavaScript-Dateien. Geschichte die spezifische Zustand eines Komponenten dokumentieren. Zum Beispiel kann ein Komponenten Geschichten für den Ladezustand und den deaktivierten Zustand haben (deaktiviert).
storiesOf('Button', module)
.add('deaktiviert', () => (
))Storybook ist viel komplexer als Styleguidist und Docz. Dennoch ist es die beliebteste Option; das Projekt hat auf Github über 36.000 Sterne. Es handelt sich um ein Open-Source-Projekt, an dem 657 Mitwirkende und unterstützende Mitarbeiter beteiligt sind. Es wird von Unternehmen wie Airbnb, Algolia, Atlassian, Lyft und Salesforce verwendet. Storybook unterstützt mehr Frameworks als die Wettbewerber – React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte und reguläres HTML.
In zukünftigen Releases werden Funktionen aus Docz integriert und MDX eingeführt.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Die neuen Funktionen von Storybook werden schrittweise in den nächsten Monaten eingeführt, und es scheint, dass dies ein großer Fortschritt sein wird.
Ergebnisse
Die Vorteile von Pattern Libraries werden in Millionen von Artikeln auf Medium gepriesen. Wenn alles gut gemacht ist, erleichtern sie die Erstellung verwandter Produkte und die Aufrechterhaltung der Identität. Natürlich wird kein Tool magisch eine Design-System erschaffen. Das erfordert sorgfältige Gestaltung und CSS. Aber wenn es darum geht, ein Design-System für das ganze Unternehmen zugänglich zu machen, sind Docz, Storybook und Styleguidist hervorragende Optionen.
Vom Übersetzer. Dies ist meine erste Erfahrung auf Habré. Wenn Sie Ungenauigkeiten finden oder Verbesserungsvorschläge zur Artikel haben, schreiben Sie mir bitte eine persönliche Nachricht.
Quelle: habr.com
