Möglicherweise haben Sie ein besseres Open Source-Projekt, aber wenn es keine gute Dokumentation enthält, ist es wahrscheinlich, dass es niemals startet. Im Büro können Sie dank einer guten Dokumentation nicht dieselben Fragen beantworten. Die Dokumentation stellt auch sicher, dass die Mitarbeiter das Projekt verstehen können, wenn wichtige Mitarbeiter das Unternehmen verlassen oder sich die Rollen ändern. Live-Richtlinien tragen zur Gewährleistung der Datenintegrität bei.
Wenn Sie langen Text schreiben müssen, ist Markdown eine großartige Alternative zu HTML. Manchmal reicht die Markdown-Syntax nicht aus. In diesem Fall können wir den darin enthaltenen HTML-Code verwenden. Zum Beispiel benutzerdefinierte Elemente. Wenn Sie ein Entwurfssystem mit nativen Webkomponenten erstellen, können diese daher problemlos in die Textdokumentation aufgenommen werden. Wenn Sie React (oder ein anderes JSX-Framework wie Preact oder Vue) verwenden, können Sie dies auch mit MDX tun.
Dieser Artikel bietet einen umfassenden Überblick über das Verfassen von Dokumentationen und Richtlinien. Nicht alle hier aufgeführten Tools verwenden MDX, es wird jedoch zunehmend in Dokumentationstools aufgenommen.
Was ist MDX?
Die .mdx Datei hat dieselbe Syntax wie Markdown, ermöglicht es Ihnen jedoch, interaktive JSX-Komponenten zu importieren und in Ihren Inhalt einzubetten. Die Unterstützung für Vue-Komponenten erfolgt in Alpha. Um mit MDX zu arbeiten, installieren Sie einfach die "Create React App". Es gibt Plugins für Next.js und Gatsby. Die nächste Version von Docusaurus (Version 2) wird ebenfalls integriert sein.
Dokumentation mit Docusaurus schreiben
Docusaurus schrieb auf Facebook. Sie verwenden es für jedes Open Source-Projekt außer React. Außerhalb des Unternehmens verwenden es Redux, Prettier, Gulp und Babel.
Projekte, die Docusaurus verwenden.
Mit Docusaurus kann jede Dokumentation geschrieben werden, nicht nur das Frontend. Er hat React unter seiner Haube, aber um es zu benutzen, ist es nicht notwendig, mit ihm vertraut zu sein. Sie benötigen Ihre Markdown-Dateien, eine Prise Magie und eine gut strukturierte, formatierte und lesbare Dokumentation mit einem schönen Design.
Auf der Redux-Website sehen Sie die Standard-Docusaurus-Vorlage
Mit Docusaurus erstellte Websites können auch ein Markdown-basiertes Blog enthalten. Prism.js ist sofort mit der Syntaxhervorhebung verbunden. Trotz der Tatsache, dass Docusaurus erst vor relativ kurzer Zeit auf den Markt kam, wurde es bei StackShare als das beste Tool des Jahres 2018 anerkannt.
Andere Optionen zur Erstellung von Inhalten
Docusaurus wurde speziell zum Erstellen von Dokumentationen entwickelt. Natürlich gibt es eine Million und eine Möglichkeit, eine Site zu erstellen: Sie können Ihre eigene Lösung in jeder Sprache oder in jedem CMS bereitstellen oder den statischen Site-Generator verwenden.
In der Dokumentation zu React, dem Designsystem von IBM, Apollo und Ghost CMS, wird beispielsweise Gatsby verwendet, ein statischer Site-Generator, der häufig für Blogs verwendet wird. Wenn Sie mit Vue arbeiten, ist VuePress eine gute Option für Sie. Eine andere Möglichkeit ist die Verwendung eines in Python - MkDocs geschriebenen Generators. Es ist offen und mit einer einzigen YAML-Datei konfigurierbar. GitBook ist auch eine gute Option, aber es ist nur für offene und gemeinnützige Teams kostenlos. Und Sie können einfach Mardown-Dateien mit Gith hochladen und mit ihnen auf Github arbeiten.
Komponentendokumentation: Docz, Storybook und Styleguidist
Richtlinien, Systemdesign, Komponentenbibliotheken - wie auch immer Sie sie nennen, aber es ist in letzter Zeit sehr beliebt geworden. Das Aufkommen von Komponenten-Frameworks wie React und den hier genannten Tools hat es möglich gemacht, sie aus konzipierten Projekten in nützliche Tools umzuwandeln.
Storybook, Docz und Styleguidist - machen Sie dasselbe: Zeigen Sie interaktive Elemente an und dokumentieren Sie deren API. Ein Projekt kann Dutzende oder sogar Hunderte von Komponenten enthalten - alle mit unterschiedlichen Zuständen und Stilen. Wenn Sie möchten, dass Komponenten wiederverwendet werden, müssen die Benutzer wissen, dass sie vorhanden sind. Katalogisieren Sie dazu einfach die Komponenten. Richtlinien bieten eine durchsuchbare Übersicht über alle Ihre Komponenten. Dies trägt zur Wahrung der visuellen Konsistenz bei und vermeidet wiederholte Arbeiten.
Diese Tools bieten eine bequeme Möglichkeit, verschiedene Zustände anzuzeigen. Es kann schwierig sein, jeden Komponentenzustand im Kontext einer realen Anwendung zu reproduzieren. Anstatt auf eine reale Anwendung zu klicken, sollten Sie eine separate Komponente entwickeln. Sie können schwer erreichbare Zustände simulieren (z. B. den Startstatus).
Neben einer visuellen Demonstration verschiedener Zustände und einer Liste von Eigenschaften ist es häufig erforderlich, eine allgemeine Beschreibung des Inhalts zu verfassen - Begründungen des Designs, Fallstudien oder eine Beschreibung der Benutzertestergebnisse. Markdown ist sehr einfach zu erlernen - im Idealfall sollten Richtlinien eine gemeinsame Ressource für Designer und Entwickler sein. Docz, Styleguidist und Storybook bieten eine Möglichkeit, Markdown einfach mit Komponenten zu mischen.
Docz
Jetzt arbeitet Docz nur mit React, aber es gibt eine aktive Arbeit zur Unterstützung von Preact-, Vue- und Webkomponenten. Docz ist das frischeste der drei Instrumente, aber auf Github konnte er mehr als 14.000 Sterne sammeln. Docz repräsentiert zwei Komponenten - <Playground> und < Props > . Sie werden importiert und 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 <Playground> umschließen, um ein Analogon zum integrierten CodePen oder CodeSandbox zu erstellen. Das heißt, Sie sehen Ihre Komponente und können sie bearbeiten.
<Playground> <Button>click</Button> </Playground>
<Props> zeigt alle verfügbaren Eigenschaften für diese React-Komponente, Standardwerte und ob eine Eigenschaft erforderlich ist.
<Props of={Button} />
Persönlich denke ich, dass dieser MDX-basierte Ansatz am einfachsten zu verstehen und am einfachsten zu bearbeiten ist.
Wenn Sie ein Fan des statischen Gatsby-Site-Generators sind, bietet Docz eine hervorragende Integration.
Styleguidist
Beispiele werden wie Docz mit der Markdown-Syntax geschrieben. Styleguidist verwendet Markdown-Codeblöcke (dreifache Anführungszeichen) in regulären .md Dateien, nicht in MDX.
```js <Button onClick={() => console.log('clicked')>Push Me</Button>
Codeblöcke in Markdown zeigen normalerweise nur den Code an. Bei Verwendung eines Styleguidist wird jeder Codeblock mit einem js , jsx oder javascript Sprach-Tag als React-Komponente angezeigt. Wie in Docz kann der Code bearbeitet werden. Sie können die Eigenschaften ändern und das Ergebnis sofort anzeigen.
Styleguidist erstellt automatisch eine Eigenschaftentabelle aus PropTypes-, Flow- oder Typescript-Deklarationen.
Styleguidist unterstützt jetzt React und Vue.
Märchenbuch
Storybook positioniert sich als "Entwicklungsumgebung für UI-Komponenten". Anstatt Komponentenbeispiele in Markdown- oder MDX-Dateien zu schreiben, schreiben Sie Storys in Javascript-Dateien. Der Verlauf wird durch den spezifischen Status der Komponente dokumentiert. Beispielsweise kann eine Komponente Historien für den Startstatus und den deaktivierten Status haben.
storiesOf('Button', module) .add('disabled', () => ( <Button disabled>lorem ipsum</Button> ))
Storybook ist viel komplizierter als Styleguidist und Docz. Gleichzeitig ist dies die beliebteste Option. Auf Github hat das Projekt mehr als 36.000 Sterne. Dies ist ein Open-Source-Projekt, an dem 657 Teilnehmer beteiligt sind und das von Vollzeitbeschäftigten begleitet wird. Es wird von Airbnb, Algolia, Atlassian, Lyft und Salesforce verwendet. Storybook unterstützt mehr Frameworks als seine Konkurrenten - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte und reguläres HTML.
In einer zukünftigen Version wird es Chips von Docz geben und MDX wird eingeführt.
# Button Some _notes_ about your button written with **markdown syntax**. <Story name="disabled"> <Button disabled>lorem ipsum</Button> </Story>
Die neuen Funktionen des Storybooks werden in den nächsten Monaten schrittweise erscheinen, und dies wird anscheinend ein großer Schritt nach vorne sein.
Zusammenfassung
Die Vorteile der Musterbibliothek werden in Millionen von Artikeln auf Medium hervorgehoben. Wenn sie gut gemacht sind, machen sie es einfach, verwandte Produkte zu erstellen und Identität zu bewahren. Natürlich wird keines dieser Tools auf magische Weise ein Design-System erstellen. Dies erfordert sorgfältiges Design und CSS-Design. Wenn es jedoch darum geht, das Designsystem dem gesamten Unternehmen zur Verfügung zu stellen, sind Docz, Storybook und Styleguidist großartige Optionen.
Vom Übersetzer. Dies ist meine erste Erfahrung auf Habré. Wenn Sie feststellen, dass einige nicht korrekt sind oder Vorschläge zur Verbesserung des Artikels vorliegen, schreiben Sie persönlich.