Je kunt een geweldig open-source project hebben, maar als het geen goede documentatie heeft, is de kans groot dat het nooit zal slagen. Goede documentatie op kantoor voorkomt dat je steeds dezelfde vragen moet beantwoorden. Documentatie zorgt er ook voor dat mensen het project kunnen begrijpen, zelfs als sleutelfiguren het bedrijf verlaten of rollen veranderen. Leefrichtlijnen helpen de integriteit van de gegevens te waarborgen.
Als je een lange tekst moet schrijven, is Markdown een uitstekend alternatief voor HTML. Soms is de syntaxis van Markdown niet voldoende. In dat geval kunnen we HTML binnen Markdown gebruiken. Bijv. op maat gemaakte elementen. Dus als je een ontwerpsysteem bouwt met native webcomponenten, is het eenvoudig om deze in de tekstdocumentatie op te nemen. Als je React (of een andere JSX-framework zoals Preact of Vue) gebruikt, kun je hetzelfde doen met MDX.
Dit artikel is een brede overzicht van tools voor het schrijven van documentatie en het creƫren van richtlijnen. Niet alle tools die hier worden genoemd, gebruiken MDX, maar het wordt steeds vaker opgenomen in documentatietools.
Wat is MDX?
Bestand .mdx heeft dezelfde syntaxis als Markdown, maar maakt het mogelijk om interactieve JSX-componenten te importeren en in je inhoud in te bedden. De ondersteuning voor Vue-componenten bevindt zich in de alfa-fase. Om aan de slag te gaan met MDX, hoeft u alleen maar 'Create React App' te installeren. Er zijn plugins voor Next.js en Gatsby. De volgende versie van Docusaurus (versie 2) zal ook ingebouwde ondersteuning hebben.
Documentatie schrijven met Docusaurus
Docusaurus is ontwikkeld door Facebook. Ze gebruiken het voor elk open-source project, behalve React. Buiten het bedrijf wordt het gebruikt door Redux, Prettier, Gulp en Babel.
Projecten die Docusaurus gebruiken.
Docusaurus kan worden gebruikt voor het schrijven van elk documentatie, niet alleen voor de front-end beschrijving. Het heeft React onder de motorkap, maar je hoeft niet bekend te zijn met React om het te gebruiken. Het pakt je Markdown-bestanden, een snufje magie en goed gestructureerde, opgemaakte en leesbare documentatie met een mooi ontwerp is klaar.
Op de Redux-website kun je de standaard sjabloon van Docusaurus bekijken.
Sites die zijn gemaakt met Docusaurus kunnen ook een blog gebaseerd op Markdown bevatten. Voor syntax highlighting is Prism.js direct geĆÆntegreerd. Hoewel Docusaurus relatief recent is verschenen, werd het uitgeroepen tot het beste hulpmiddel van 2018 op StackShare.
Andere manieren om content te creƫren
Docusaurus is speciaal ontworpen voor het maken van documentatie. Er zijn natuurlijk miljoenen manieren om een website te maken ā je kunt je eigen oplossing op elke taal of CMS opzetten of gebruik maken van een statische sitegenerator.
Bijvoorbeeld, de documentatie voor React, het IBM design systeem, Apollo en Ghost CMS gebruiken Gatsby ā een statische sitegenerator die vaak voor blogs wordt gebruikt. Als je met Vue werkt, is VuePress een goed alternatief voor jou. Een andere optie is om een generator te gebruiken die in Python is geschreven ā MkDocs. Dit is open-source en kan worden geconfigureerd met Ć©Ć©n YAML-bestand. GitBook is ook een goede optie, maar het is gratis alleen voor open en niet-commerciĆ«le teams. En je kunt eenvoudig Markdown-bestanden uploaden met Git en ermee werken in Github.
Documentatie van componenten: Docz, Storybook en Styleguidist
Richtlijnen, design systemen, componentbibliotheken ā hoe je ze ook noemt, ze zijn de laatste tijd erg populair geworden. De opkomst van componentframeworks zoals React en de tools die hier worden genoemd, heeft ervoor gezorgd dat ze zijn geĆ«volueerd van ijdelheidsprojecten naar nuttige hulpmiddelen.
Storybook, Docz en Styleguidist doen allemaal hetzelfde: ze tonen interactieve elementen en documenteren hun API. Een project kan tientallen of zelfs honderden componenten hebben ā allemaal met verschillende toestanden en stijlen. Als je wilt dat componenten hergebruikt worden, moeten mensen weten dat ze bestaan. Het is voldoende om de componenten te catalogiseren. Richtlijnen bieden een gemakkelijk doorzoekbaar overzicht van al je componenten. Dit helpt om visuele consistentie te behouden en dubbele inspanningen te vermijden.
Deze tools bieden een gemakkelijke manier om verschillende toestanden te bekijken. Het kan moeilijk zijn om elke toestand van een component in de context van een echte applicatie na te bootsen. In plaats van door een echte applicatie te klikken, is het beter om een aparte component te ontwikkelen. Je kunt moeilijk bereikbare toestanden modelleren (bijvoorbeeld een laadstatus).
Naast de visuele demonstratie van verschillende toestanden en de lijst met eigenschappen is het vaak nodig om een algemene beschrijving van de inhoud te schrijven ā ontwerpverantwoording, gebruikscases of de resultaten van gebruikerstests. Markdown is heel eenvoudig te leren ā idealiter moet de richtlijn een gezamenlijke bron zijn voor ontwerpers en ontwikkelaars. Docz, Styleguidist en Storybook bieden een manier om eenvoudig Markdown met componenten te mengen.
Docz
Momenteel werkt Docz alleen met React, maar er wordt hard gewerkt aan ondersteuning voor Preact, Vue en webcomponenten. Docz is het nieuwste van de drie tools, maar heeft op Github meer dan 14.000 sterren verzameld. Docz introduceert twee componenten ā <Playground> en < Props >. Ze worden geĆÆmporteerd en gebruikt in bestanden .mdx.
import { Playground, Props } from "docz";
import Button from "..\/src\/Button";
## Je kunt _schrijven_ **markdown**
### Je kunt componenten importeren en gebruiken
Je kunt je eigen React-componenten omhullen met <Playground>, om een vergelijkbare functionaliteit als de ingebouwde CodePen of CodeSandbox te creĆ«ren ā dat wil zeggen, je ziet je component en kunt het bewerken.
<Props> toont alle beschikbare eigenschappen voor die React-component, de standaardwaarden en of de eigenschap vereist is.
<Props of={Button} />Persoonlijk beschouw ik deze MDX-gebaseerde benadering als de eenvoudigste om te begrijpen en het gemakkelijkst om mee te werken.
Als je een fan bent van de statische website-generator Gatsby, biedt Docz uitstekende integratie.
Styleguidist
Net als in Docz worden voorbeelden geschreven met behulp van Markdown-syntaxis. Styleguidist gebruikt Markdown codeblokken (drie aanhalingstekens) in gewone bestanden .md bestanden, en niet in MDX.
```js
Codeblokken in Markdown tonen meestal gewoon de code. Bij gebruik van Styleguidist wordt elk codeblok met de taaltag js, jsx of javascript weergegeven als een React-component. Net als in Docz is de code bewerkbaar ā je kunt eigenschappen wijzigen en het resultaat onmiddellijk zien.
Styleguidist genereert automatisch een eigenschappenlijst uit PropTypes, Flow of Typescript-verklaringen.
Styleguidist ondersteunt nu React en Vue.
Storybook
Storybook positioneert zichzelf als een 'ontwikkelomgeving voor UI-componenten'. In plaats van voorbeelden van componenten binnen Markdown- of MDX-bestanden te schrijven, schrijf je verhalen binnen Javascript-bestanden. Geschiedenis documenteert de specifieke toestand van een component. Een component kan bijvoorbeeld verhalen hebben voor een laadtoestand en een uitgeschakelde toestand (uitgeschakeld).
storiesOf('Button', module)
.add('uitgeschakeld', () => (
))Storybook is veel complexer dan Styleguidist en Docz. Desondanks is het de populairste optie, met meer dan 36.000 sterren op Github. Dit is een open-source project waar 657 bijdragers aan hebben deelgenomen, ondersteund door medewerkers. Het wordt gebruikt door Airbnb, Algolia, Atlassian, Lyft en Salesforce. Storybook ondersteunt meer frameworks dan de concurrentie ā React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte en gewone HTML.
In de toekomstige release zullen functies van Docz worden opgenomen en MDX worden geĆÆntroduceerd.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Nieuwe functies van Storybook zullen geleidelijk over de volgende paar maanden verschijnen en blijken een grote stap voorwaarts te zijn.
Conclusies
De voordelen van een patroonbibliotheek worden geprezen in miljoenen artikelen op Medium. Wanneer alles goed gedaan is, vergemakkelijken ze het creƫren van gerelateerde producten en het behoud van een identiteit. Natuurlijk zal geen van deze tools op magische wijze een ontwerp systeem creƫren. Dit vereist zorgvuldige ontwerping en CSS. Maar wanneer het tijd is om het ontwerp systeem beschikbaar te maken voor het hele bedrijf, zijn Docz, Storybook en Styleguidist uitstekende opties.
Van de vertaler. Dit is mijn eerste ervaring op Habra. Als je onjuistheden hebt gevonden of suggesties hebt ter verbetering van het artikel ā stuur me een privĆ©bericht.
Bron: habr.com
