Je kunt het beste open source-project hebben, maar als het geen goede documentatie heeft, is de kans groot dat het nooit van de grond zal komen. Op kantoor voorkomt goede documentatie dat u dezelfde vragen beantwoordt. Documentatie zorgt er ook voor dat mensen het project kunnen begrijpen als belangrijke werknemers het bedrijf verlaten of als er rollen veranderen. Levende richtlijnen zullen de data-integriteit helpen waarborgen.
Als u lange tekst moet schrijven, is Markdown een geweldig alternatief voor HTML. Soms is de Markdown-syntaxis niet voldoende. In dit geval kunnen we HTML erin gebruiken. Bijvoorbeeld aangepaste elementen. Als u dus een ontwerpsysteem bouwt met native webcomponenten, kunnen deze eenvoudig worden opgenomen in tekstdocumentatie. Als je React (of een ander JSX-framework zoals Preact of Vue) gebruikt, kun je hetzelfde doen met MDX.
Dit artikel is een breed overzicht van tools voor het schrijven van documentatie en het maken van richtlijnen. Niet alle hier genoemde tools gebruiken MDX, maar het wordt steeds vaker opgenomen in documentatietools.
Wat is MDX?
file .mdx heeft dezelfde syntaxis als Markdown, maar stelt u in staat interactieve JSX-componenten te importeren en deze in uw inhoud in te sluiten. Ondersteuning voor Vue-componenten bevindt zich in alpha. Om met MDX te gaan werken, installeert u gewoon “Create React App”. Er zijn plug-ins voor Next.js en Gatsby. De volgende versie van Docusaurus (versie 2) zal ook native ondersteuning hebben.
Documentatie schrijven met Docusaurus
Docusaurus schreef op Facebook. Ze gebruiken het in 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 om te schrijven een documentatie, niet alleen om de frontend te beschrijven. Het heeft React onder de motorkap, maar je hoeft er niet bekend mee te zijn om het te gebruiken. Er zijn uw Markdown-bestanden nodig, een snufje magie en goed gestructureerde, opgemaakte en leesbare documentatie met een prachtig ontwerp is klaar.
Op de website van Redux kunt u het standaard Docusaurus-sjabloon zien
Websites die met Docusaurus zijn gebouwd, kunnen ook een op Markdown gebaseerde blog bevatten. Prism.js wordt onmiddellijk verbonden voor syntaxisaccentuering. Ondanks het feit dat Docusaurus relatief recent verscheen, werd het op StackShare erkend als de beste tool van 2018.
Andere opties voor het maken van inhoud
Docusaurus is speciaal ontworpen voor het maken van documentatie. Natuurlijk zijn er een miljoen en één manieren om een website te maken: u kunt uw eigen oplossing in elke taal, CMS, implementeren of een statische sitegenerator gebruiken.
Documentatie voor React, IBM design system, Apollo en Ghost CMS maakt bijvoorbeeld gebruik van Gatsby - een statische sitegenerator die vaak wordt gebruikt voor blogs. Werk je met Vue, dan is VuePress een goede optie voor jou. Een andere optie is om een generator te gebruiken die is geschreven in Python - MkDocs. Het is open source en geconfigureerd met behulp van een enkel YAML-bestand. GitBook is ook een goede optie, maar het is alleen gratis voor publieke en niet-commerciële teams. Je kunt ook eenvoudig mardown-bestanden uploaden met Git en ermee werken in Github.
Documentatiecomponenten: Docz, Storybook en Styleguidist
Richtlijnen, systeemontwerp, componentenbibliotheken - hoe je ze ook noemt, het is de laatste tijd erg populair geworden. De komst van componentframeworks zoals React en de hier genoemde tools hebben ze van ijdelheidsprojecten in nuttige tools getransformeerd.
Storybook, Docz en Styleguidist doen allemaal hetzelfde: interactieve elementen weergeven en hun API documenteren. Een project kan tientallen of zelfs honderden componenten bevatten, allemaal met verschillende statussen en stijlen. Als je wilt dat componenten worden hergebruikt, moeten mensen weten dat ze bestaan. Om dit te doen, catalogiseert u eenvoudigweg de componenten. Richtlijnen bieden een overzichtelijk overzicht van al uw componenten. Dit helpt de visuele consistentie te behouden en repetitief werk te voorkomen.
Deze tools bieden een handige manier om verschillende statussen te bekijken. Het kan moeilijk zijn om elke status van een component te reproduceren in de context van een echte toepassing. In plaats van op de daadwerkelijke applicatie te klikken, is het de moeite waard om een afzonderlijk onderdeel te ontwikkelen. Moeilijk bereikbare toestanden (zoals laadtoestanden) kunnen worden gesimuleerd.
Naast een visuele demonstratie van verschillende statussen en een lijst met eigenschappen, is het vaak nodig om een algemene beschrijving van de inhoud te schrijven: ontwerpredenen, gebruiksscenario's of beschrijvingen van gebruikerstestresultaten. Markdown is heel gemakkelijk te leren - idealiter zouden richtlijnen een gedeelde bron moeten zijn voor ontwerpers en ontwikkelaars. Docz, Styleguidist en Storybook bieden een manier om Markdown eenvoudig met componenten te mixen.
Docz
Momenteel werkt Docz alleen met React, maar er wordt actief gewerkt aan de ondersteuning van Preact, Vue en webcomponenten. Docz is de meest recente van de drie tools, maar heeft op Github ruim 14 sterren weten te verzamelen. Docz introduceert twee componenten − <Playground> и < Props >. Ze worden geïmporteerd en gebruikt in bestanden .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>U kunt uw eigen React-componenten verpakken <Playground>om een analoog van de ingebouwde CodePen of CodeSandbox te maken - dat wil zeggen, u ziet uw component en kunt deze bewerken.
<Playground>
<Button>click</Button>
</Playground><Props> toont alle beschikbare eigenschappen voor een gegeven React-component, standaardwaarden en of de eigenschap vereist is.
<Props of={Button} />Persoonlijk vind ik deze op MDX gebaseerde aanpak het gemakkelijkst te begrijpen en het gemakkelijkst om mee te werken.
Als je een fan bent van de statische sitegenerator van Gatsby, biedt Docz een geweldige integratie.
Stijlgids
Net als Docz worden voorbeelden geschreven met behulp van de Markdown-syntaxis. Styleguidist gebruikt Markdown-codeblokken (drievoudige aanhalingstekens) in reguliere bestanden .md bestanden, niet MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Codeblokken in Markdown tonen meestal alleen code. Bij gebruik van Styleguidist: elk codeblok met een taaltag js, jsx of javascript wordt weergegeven als een React-component. Net als Docz is de code bewerkbaar: u kunt eigenschappen wijzigen en direct het resultaat zien.
Styleguidist maakt automatisch een eigenschappentabel op basis van PropTypes-, Flow- of Typescript-declaraties.
Styleguidist ondersteunt momenteel React en Vue.
Storybook
Storybook positioneert zichzelf als een ‘UI-componentontwikkelomgeving’. In plaats van voorbeeldcomponenten in Markdown- of MDX-bestanden te schrijven, schrijft u geschiedenis binnen JavaScript-bestanden. Verhaal documenteer de specifieke staat van een component. Een component kan bijvoorbeeld een geschiedenis hebben voor een geladen status en een uitgeschakelde status (invalide).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Storybook is veel complexer dan Styleguidist en Docz. Maar tegelijkertijd is dit de meest populaire optie: het project heeft meer dan 36 sterren op Github. Het is een open source-project met 000 medewerkers en fulltime medewerkers. Het wordt gebruikt door Airbnb, Algolia, Atlassian, Lyft en Salesforce. Storybook ondersteunt meer raamwerken dan concurrenten - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte en gewone HTML.
In een toekomstige release zullen er features van Docz en MDX worden geïntroduceerd.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>De nieuwe functies van Storybook zullen de komende maanden geleidelijk worden uitgerold en het lijkt erop dat dit een grote stap voorwaarts zal zijn.
Resultaten van
De voordelen van een patronenbibliotheek worden geprezen in miljoenen artikelen op Medium. Als ze goed worden uitgevoerd, maken ze het gemakkelijker om gerelateerde producten te maken en de identiteit te behouden. Natuurlijk zal geen van deze tools op magische wijze een ontwerpsysteem creëren. Dit vereist een zorgvuldig ontwerp en CSS. Maar als het tijd is om een ontwerpsysteem toegankelijk te maken voor het hele bedrijf, zijn Docz, Storybook en Styleguidist geweldige opties.
Van de vertaler. Dit is mijn eerste ervaring met Habré. Als u onjuistheden tegenkomt, of suggesties heeft om het artikel te verbeteren, schrijf mij dan in een persoonlijk bericht.
Bron: www.habr.com