Sie können das beste Open-Source-Projekt haben, aber wenn es keine gute Dokumentation gibt, besteht die Wahrscheinlichkeit, dass es nie erfolgreich wird. Eine gute Dokumentation im BĂŒro ermöglicht es Ihnen, nicht stĂ€ndig dieselben Fragen zu beantworten. Dokumentation stellt auch sicher, dass die Leute sich im Projekt zurechtfinden, wenn SchlĂŒsselmitarbeiter das Unternehmen verlassen oder die Rollen sich Ă€ndern. Lebendige Richtlinien helfen, die DatenintegritĂ€t zu gewĂ€hrleisten.
Wenn Sie einen langen Text schreiben mĂŒssen, ist Markdown eine ausgezeichnete Alternative zu HTML. Manchmal reicht die Markdown-Syntax jedoch nicht aus. In diesem Fall können wir HTML innerhalb von Markdown verwenden, zum Beispiel benutzerdefinierte Elemente. Wenn Sie also ein Designsystem mit nativen Webkomponenten erstellen, lassen sie sich leicht in die Textdokumentation integrieren. Wenn Sie React (oder ein anderes JSX-Framework wie Preact oder Vue) verwenden, können Sie dasselbe mit MDX tun.
Dieser Artikel bietet einen umfassenden Ăberblick ĂŒber die Tools zum Schreiben von Dokumentationen und zum Erstellen von Richtlinien. Nicht alle hier aufgefĂŒhrten Werkzeuge nutzen MDX, aber es wird zunehmend in Dokumentationstools integriert.
Was ist MDX?
Die Datei .mdx hat die gleiche Syntax wie Markdown, ermöglicht jedoch das Importieren interaktiver JSX-Komponenten und deren Einbettung in Ihren Inhalt. Die UnterstĂŒtzung von Vue-Komponenten befindet sich in der Alphaphase. Um mit MDX zu arbeiten, reicht es aus, âCreate React Appâ zu installieren. Es gibt Plugins fĂŒr Next.js und Gatsby. Die nĂ€chste Version von Docusaurus (Version 2) wird ebenfalls eine integrierte UnterstĂŒtzung haben.
Dokumentation mit Docusaurus schreiben
Docusaurus wurde bei Facebook entwickelt. Sie verwenden es in jedem Open-Source-Projekt auĂer React. AuĂerhalb des Unternehmens verwenden es Redux, Prettier, Gulp und Babel.
Projekte, die Docusaurus verwenden.
Docusaurus kann verwendet werden, um kann diese Dokumentation zu schreiben, nicht nur zur Beschreibung des Frontends. Es basiert auf React, aber um es zu verwenden, mĂŒssen Sie mit React nicht vertraut sein. Es nimmt Ihre Markdown-Dateien, eine Prise Magie, und gut strukturierte, formatierte und lesbare Dokumentation mit ansprechendem Design ist bereit.
Auf der Website von Redux können Sie die Standardvorlage von Docusaurus einsehen.
Websites, die mit Docusaurus erstellt wurden, können auch einen Blog auf Markdown-Basis beinhalten. Prism.js ist sofort integriert, um die Syntax hervorzuheben. Obwohl Docusaurus relativ neu ist, wurde es auf StackShare als das beste Werkzeug des Jahres 2018 anerkannt.
Andere Möglichkeiten zur Erstellung von Inhalten
Docusaurus wurde speziell fĂŒr die 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, CMS oder mithilfe eines Static Site Generators implementieren.
Beispielsweise verwenden die Dokumentation fĂŒr React, die IBM Design System, Apollo und Ghost CMS Gatsby â ein Static Site Generator, der hĂ€ufig fĂŒr Blogs verwendet wird. Wenn Sie mit Vue arbeiten, wird VuePress eine gute Wahl fĂŒr Sie sein. Eine andere Möglichkeit ist die Verwendung eines in Python geschriebenen Generators â MkDocs. Es ist Open Source und wird ĂŒber eine YAML-Datei konfiguriert. GitBook ist auch eine anstĂ€ndige Option, aber es ist nur fĂŒr Open-Source- und Nicht-Profit-Teams kostenlos. Eine weitere Möglichkeit besteht darin, Markdown-Dateien einfach ĂŒber Git hochzuladen und sie in GitHub zu bearbeiten.
Dokumentation von Komponenten: Docz, Storybook und Styleguidist
Richtlinien, Designsysteme, Komponentebibliotheken â egal wie Sie sie nennen, aber sie sind in letzter Zeit sehr beliebt geworden. Das Aufkommen komponentenbasierter Frameworks wie React und der hier erwĂ€hnten Werkzeuge hat es ermöglicht, sie von eitlen Projekten in nĂŒtzliche Werkzeuge zu verwandeln.
Storybook, Docz und Styleguidist tun dasselbe: Sie zeigen interaktive Elemente an und dokumentieren deren API. Ein Projekt kann Dutzende oder sogar Hunderte von Komponenten haben â alle mit verschiedenen ZustĂ€nden und Stilen. Wenn Komponenten wiederverwendet werden sollen, mĂŒssen die Leute wissen, dass sie existieren. Es genĂŒgt, die Komponenten zu katalogisieren. Richtlinien bieten eine ĂŒbersichtliche Ăbersicht ĂŒber alle Ihre Komponenten. Das hilft, visuelle Konsistenz zu bewahren und Wiederholungsarbeit zu vermeiden.
Diese Werkzeuge bieten eine bequeme Möglichkeit, verschiedene ZustÀnde einzusehen. Es kann schwierig sein, jeden Zustand einer Komponente im Kontext einer realen Anwendung zu reproduzieren. Anstatt in einer echten Anwendung zu klicken, sollte man eine separate Komponente entwickeln. Es ist möglich, schwer erreichbare ZustÀnde zu simulieren (z. B. den Ladezustand).
Neben der visuellen Demonstration 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 leicht mit Komponenten zu mischen.
Docz
Zurzeit funktioniert Docz nur mit React, aber es wird aktiv an der UnterstĂŒtzung von Preact, Vue und Webkomponenten gearbeitet. Docz ist das neuesten der drei Werkzeuge, hat aber auf Github ĂŒber 14.000 Sterne gesammelt. Docz bietet zwei Komponenten an â <Playground> und < Props >. Diese werden in Dateien importiert und verwendet .mdx.
import { Playground, Props } from "docz";
import Button from "..\/src\/Button";
## Sie können _schreiben_ **Markdown**
### Sie können Komponenten importieren und verwenden
Sie können Ihre eigenen React-Komponenten mit Hilfe von <Playground>, um eine Art integrierten CodePen oder CodeSandbox zu erstellen â das heiĂt, Sie sehen Ihre Komponente und können sie bearbeiten.
<Props> zeigt alle verfĂŒgbaren Eigenschaften fĂŒr diese React-Komponente, Standardwerte und ob eine Eigenschaft erforderlich ist.
<Props of={Button} />Ich persönlich finde diesen Ansatz auf MDX-Basis am einfachsten zu verstehen und am unkompliziertesten zu handhaben.
Wenn Sie ein Fan des Static-Site-Generators Gatsby sind, bietet Docz eine hervorragende Integration.
Styleguidist
Wie bei Docz werden die Beispiele unter Verwendung der Markdown-Syntax geschrieben. Styleguidist verwendet Markdown-Codeblöcke (dreifache AnfĂŒhrungszeichen) in normalen Dateien .md Dateien, nicht in MDX.
```js
Codeblöcke in Markdown zeigen normalerweise einfach Code. Bei der Verwendung von Styleguidist wird jeder Codeblock mit der Sprache js, jsx oder javascript als React-Komponente angezeigt. Wie auch bei Docz ist der Code bearbeitbar â Sie können Eigenschaften Ă€ndern und sofort das Ergebnis sehen.
Styleguidist erzeugt automatisch eine Eigenschaften-Tabelle aus PropTypes, Flow oder Typescript-Deklarationen.
Styleguidist unterstĂŒtzt jetzt React und Vue.
Storybook
Storybook positioniert sich als "Umgebung zur Entwicklung von UI-Komponenten". Anstatt Beispiele fĂŒr Komponenten innerhalb von Markdown- oder MDX-Dateien zu schreiben, schreiben Sie der Ănderungen. innerhalb von Javascript-Dateien. Geschichte dokumentieren einen spezifischen Zustand der Komponente. Zum Beispiel kann eine Komponente 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, und das Projekt hat auf Github mehr als 36.000 Sterne. Es ist ein Open-Source-Projekt, an dem 657 Teilnehmer mitwirken und stĂ€ndige Mitarbeiter unterstĂŒtzen. Es wird von Airbnb, Algolia, Atlassian, Lyft und Salesforce genutzt. Storybook unterstĂŒtzt mehr Frameworks als die Konkurrenz â React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte und Standard-HTML.
In einer zukĂŒnftigen Version werden Funktionen aus Docz implementiert und MDX integriert.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Neue Funktionen von Storybook werden schrittweise in den kommenden Monaten eingefĂŒhrt und scheinen ein groĂer Fortschritt zu sein.
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 Pflege der IdentitĂ€t. NatĂŒrlich wird keines dieser Werkzeuge magisch eine Design-System schaffen. Das erfordert sorgfĂ€ltige Design- und CSS-Planung. Aber wenn es Zeit ist, ein Design-System fĂŒr das gesamte Unternehmen zugĂ€nglich zu machen, sind Docz, Storybook und Styleguidist groĂartige Optionen.
Von einem Ăbersetzer. Dies ist meine erste Erfahrung auf HabrĂ©. Wenn Sie Ungenauigkeiten gefunden haben oder VorschlĂ€ge zur Verbesserung des Artikels haben â schreiben Sie mir eine Nachricht.
Quelle: habr.com
