Sie haben vielleicht ein besseres Open-Source-Projekt, aber wenn es nicht über eine gute Dokumentation verfügt, wird es wahrscheinlich nie erfolgreich sein. Im Büro verhindert eine gute Dokumentation, dass Sie immer wieder dieselben Fragen beantworten. Die Dokumentation stellt außerdem sicher, dass die Mitarbeiter das Projekt nachvollziehen 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 lange Texte schreiben müssen, ist Markdown eine großartige Alternative zu HTML. Manchmal reicht die Markdown-Syntax nicht aus. In diesem Fall können wir darin HTML verwenden. Zum Beispiel benutzerdefinierte Elemente. Wenn Sie also ein Designsystem mit nativen Webkomponenten erstellen, ist es einfach, diese in die Textdokumentation einzubinden. 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 Tools zum Schreiben von Dokumentation und zum Erstellen einer Richtlinie. Nicht alle der hier aufgeführten Tools verwenden MDX, es wird jedoch zunehmend in Dokumentationstools integriert.
Was ist MDX?
Datei .mdx hat die gleiche Syntax wie Markdown, ermöglicht Ihnen jedoch den Import interaktiver 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 arbeiten, installieren Sie einfach „Create React App“. 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 schreiben mit Docusaurus
Docusaurus schrieb auf Facebook. Sie verwenden es in jedem Open-Source-Projekt außer React. Außerhalb des Unternehmens nutzen Redux, Prettier, Gulp und Babel es.
Projekte, die Docusaurus verwenden.
Docusaurus kann zum Schreiben verwendet werden keine Dokumentation, nicht nur zur Beschreibung des Frontends. Es verfügt über React unter der Haube, aber Sie müssen nicht damit vertraut sein, um es zu verwenden. Es braucht Ihre Markdown-Dateien, eine Prise Magie und fertig ist eine gut strukturierte, formatierte und lesbare Dokumentation mit einem schönen Design.
Sie können die Standardvorlage von Docusaurus auf der Redux-Website sehen.
Mit Docusaurus erstellte Websites können auch einen Markdown-basierten Blog enthalten. Zur Syntaxhervorhebung ist Prism.js sofort enthalten. Obwohl Docusaurus erst vor relativ kurzer Zeit auf den Markt kam, wurde es auf StackShare als bestes Tool des Jahres 2018 ausgezeichnet.
Weitere Optionen zur Inhaltserstellung
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önnen Ihre eigene Lösung in einer beliebigen Sprache oder einem beliebigen CMS bereitstellen oder einen statischen Site-Generator verwenden.
Beispielsweise verwenden die Dokumentationen für React, das IBM Designsystem, Apollo und Ghost CMS Gatsby, einen statischen 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 besteht darin, einen in Python geschriebenen Generator zu verwenden – MkDocs. Es ist mit einer einzigen YAML-Datei geöffnet und konfiguriert. GitBook ist ebenfalls eine gute Option, allerdings ist es nur für offene und nichtkommerzielle Teams kostenlos. Sie können Mardown-Dateien auch einfach mit Git hochladen und in Github damit arbeiten.
Komponentendokumentation: Docz, Storybook und Styleguidist
Richtlinien, Systemdesign, Komponentenbibliotheken, wie auch immer Sie sie nennen wollen, diese sind in letzter Zeit sehr beliebt geworden. Das Aufkommen von Komponenten-Frameworks wie React und den hier genannten Tools hat es möglich gemacht, sie von Vanity-Projekten in nützliche Tools umzuwandeln.
Storybook, Docz und Styleguidist machen dasselbe: interaktive Elemente anzeigen und ihre API dokumentieren. 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 Leute wissen, dass sie existieren. Dazu reicht es aus, die Komponenten zu katalogisieren. Richtlinien bieten einen leicht durchsuchbaren Überblick über alle Ihre Komponenten. Dies trägt dazu bei, die visuelle Konsistenz aufrechtzuerhalten und sich wiederholende Arbeiten zu vermeiden.
Diese Tools bieten eine bequeme Möglichkeit, verschiedene Zustände anzuzeigen. Es kann schwierig sein, jeden Zustand einer Komponente im Kontext einer realen Anwendung zu reproduzieren. Anstatt auf die eigentliche Anwendung zu klicken, lohnt es sich, eine eigene Komponente zu entwickeln. Sie können schwer erreichbare Zustände (z. B. Ladezustand) simulieren.
Neben einer visuellen Demonstration verschiedener Zustände und einer Liste von Eigenschaften ist es oft notwendig, eine allgemeine Beschreibung des Inhalts zu verfassen – Designgründe, Anwendungsfälle oder eine Beschreibung der Ergebnisse von Benutzertests. 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.
Dok
Derzeit arbeitet Docz nur mit React, arbeitet aber aktiv an der Unterstützung für Preact, Vue und Webkomponenten. Docz ist das jüngste der drei Tools, konnte aber bereits über 14 Sterne auf Github sammeln. Docz führt zwei Komponenten ein: <Playground> и < Props >. Sie werden importiert und in Dateien verwendet .mdx.
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 damit umschließen <Playground>um ein Analogon des integrierten CodePen oder der 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 die angegebene React-Komponente, Standardwerte und ob die Eigenschaft erforderlich ist.
<Props of={Button} />Ich persönlich finde, dass dieser MDX-basierte Ansatz am einfachsten zu verstehen und am einfachsten zu handhaben ist.
Wenn Sie ein Fan von Gatsbys statischem Site-Generator sind, bietet Docz großartige Integrationen.
Styleguide
Wie in Docz werden Beispiele mithilfe der Markdown-Syntax geschrieben. Styleguidist verwendet Markdown-Codeblöcke (dreifache Anführungszeichen) in regulären Dateien .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 von Styleguidist jeder Codeblock mit einem Sprach-Tag js, jsx oder javascript wird als React-Komponente gerendert. Wie bei Docz ist der Code editierbar – Sie können Eigenschaften ändern und das Ergebnis sofort sehen.
Styleguidist erstellt automatisch ein Eigenschaftenblatt aus PropTypes-, Flow- oder Typescript-Deklarationen.
Styleguidist unterstützt jetzt React und Vue.
Märchenbuch
Storybook bezeichnet sich selbst als „Entwicklungsumgebung für UI-Komponenten“. Anstatt Komponentenbeispiele in Markdown- oder MDX-Dateien zu schreiben, schreiben Sie Geschichten in Javascript-Dateien. Geschichte dokumentieren den spezifischen Zustand einer Komponente. Beispielsweise könnte eine Komponente über Historien für einen Ladezustand und einen deaktivierten Zustand verfügen (behindert).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Storybook ist viel komplexer als Styleguidist und Docz. Aber gleichzeitig ist dies die beliebteste Option, auf Github hat das Projekt mehr als 36 Sterne. Dies ist ein Open-Source-Projekt mit 000 Mitwirkenden und Mitarbeiterbetreuung. Es wird von Airbnb, Algolia, Atlassian, Lyft und Salesforce verwendet. Storybook unterstützt mehr Frameworks als die Konkurrenz – React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte und einfaches 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 Storybook-Funktionen werden in den nächsten Monaten schrittweise eingeführt und es sieht so aus, als ob dies ein großer Schritt nach vorne sein wird.
Ergebnisse
Die Vorteile der Musterbibliothek werden in Millionen von Artikeln auf Medium gelobt. Wenn sie gut gemacht sind, erleichtern sie die Erstellung verwandter Produkte und die Wahrung einer Identität. Natürlich wird keines dieser Tools auf magische Weise ein Designsystem 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.
Von einem Übersetzer. Dies ist meine erste Erfahrung auf Habré. Wenn Sie Ungenauigkeiten feststellen oder Vorschläge zur Verbesserung des Artikels haben, schreiben Sie uns persönlich.
Source: habr.com