Front-End Documentatie, stijlgidsen en de Opkomst van het MDX –

0
43

U kunt het beste open source-project in de wereld, maar, als het geen goede documentatie, is de kans groot dat zal nooit uit te nemen. In de office, een goede documentatie kan slaan dat u niet herhaaldelijk dezelfde vragen te beantwoorden. Documentatie zorgt ervoor dat mensen kunnen uitzoeken hoe dingen werken als werknemers besluiten om te vertrekken van de vennootschap of wijzigen van rollen. Goed gedocumenteerd codeerrichtlijnen helpen zorgen voor de samenhang van een codebase.

Als je het schrijven van een lange tekst, Markdown is duidelijk een geweldig alternatief voor het ontwerpen van HTML. Soms is het echter Markdown syntax is niet voldoende. Het is altijd mogelijk geweest om te schrijven rechte HTML binnenkant van Markdown-documenten. Dit omvat aangepaste elementen dus, als je het bouwen van een ontwerp native web components, het is gemakkelijk te integreren in uw tekst-gebaseerde documentatie. Als u bezig bent met Reageren (of een ander kader, dat spreekt JSX, zoals Preact of Vue), kunt u hetzelfde doen met behulp van MDX.

Dit artikel is een breed overzicht van de beschikbare instrumenten voor het schrijven van documentatie en voor het bouwen van stijl gidsen. Niet alle tools die hier gebruik maken van de MDX-maar het is in toenemende mate te worden opgenomen in de documentatie van tooling.

Wat is MDX?

Een .mdx-bestand heeft precies dezelfde syntaxis als een gewone Markdown-bestand, maar u kunt importeren interactieve JSX componenten en deze in te sluiten in uw inhoud. Ondersteuning voor Vue onderdelen is in de alpha. Het is gemakkelijk om MDX ingesteld met het Maken van Reageren App. Er zijn MDX-plug-ins voor Next.js en Gatsby. De volgende versie twee release van Docusaurus zal ook komen met ingebouwde ondersteuning.

Schrijven van documentatie met Docusaurus

Docusaurus is gemaakt door en wordt gebruikt door elk open source project, afgezien van Reageren. Het is ook gebruikt door vele grote open source projecten buiten , met inbegrip van Redux, Mooier, de Gulp en Babel.

De projecten maken gebruik van Docusaurus.

U kunt gebruik maken van Docusaurus om het document van alles — het is niet de front-end specifiek. Docusaurus toepassingen Reageren onder de motorkap, maar je hoeft niet te weten dat kader gebruik van te maken. Het zal je Markdown-bestanden en zet ze in een mooi gestructureerd, goed opgemaakt en leesbare documentatie site, met een leuk design direct uit de doos.

De Redux site toont de typische lay-out Docusaurus

Sites die zijn gemaakt met Docusaurus kunt ook een Markdown-based blog. Prism.js standaard is inbegrepen voor nul-setup voor accentuering van de syntaxis. Hoewel relatief nieuw is, Docusaurus heeft bewezen populair, dat wordt verkozen tot de nummer een nieuwe tool van 2018 op StackShare.

Andere opties voor de geschreven inhoud

Docusaurus specifiek geschikt voor gebouw documentatie. Natuurlijk, er zijn duizend en één manieren om een website te maken — dus u kunt uw eigen roll-oplossing met een back-end taal, CMS, of static site generator.

De documentatie sites voor het Reageren, IBM ‘ s design systeem, Apollo en Geest CMS gebruik Gatsby, bijvoorbeeld — een generieke static site generator vaak wordt gebruikt voor blogs. Als u werkt met de Vue framework, VuePress is steeds een populaire optie. MkDocs is een open source static site generator voor het maken van documentatie, geschreven in Python en geconfigureerd met een enkele YAML-bestand. GitBook is een populaire betaalde product dat gratis is voor open-source en non-profit teams. Als je je interne documentatie en willen iets eenvoudig, de leeservaring op GitHub zelf niet half slecht, dus je kon gewoon doen Markdown-bestanden en laat het daarbij.

Het documenteren onderdelen: Docz, Sprookjes en Styleguidist

Style guides, ontwerpen systemen, patroon bibliotheken — hoe je het ook wilt noemen — zijn uitgegroeid tot een enorm populair gebied van zorg in de afgelopen tien jaar. Wat echt het verschil gemaakt in het veranderen van de ijdelheid projecten in bruikbare tools is niet de pontificating van opinieleiders, maar de opkomst van component-gedreven kaders, zoals Reageren, en de gereedschappen die hier zijn vermeld.

Storybook Docz en Styleguidist al veel doen het zelfde ding: display interactieve UI-componenten en documenteren van hun API. Een project kan tientallen of zelfs honderden componenten te houden met een verscheidenheid aan landen en stijlen. Als u wilt de onderdelen worden hergebruikt, mensen moeten weten dat ze bestaan. We steun vindbaarheid wanneer we catalogus met componenten. Een style guide geeft een eenvoudig doorzoekbare en scanbare overzicht van alle UI-componenten. Dit helpt bij het handhaven van visuele consistentie en voorkomt dubbel werk.

Deze tools bieden een handige manier om de verschillende staten. Het kan moeilijk zijn om te reproduceren elke toestand van een component in de context van een echte toepassing. In plaats nodig om te klikken door middel van een echte app, het ontwikkelen van een onderdeel in een isolement kan nuttig zijn. Hard-to-reach-lidstaten (zoals het laden van staat, bijvoorbeeld) kan worden bespot.

Dan Groen schreef een mooi overzicht van de voordelen van het gebruik van Sprookjes, maar het geldt evenzeer voor Docz en Styleguidist:

“Storybook is het echt makkelijk voor ontwerpers die code samen te werken met ingenieurs. Door te werken in de sprookjes die ze niet nodig hebben om een hele milieu actief (docker container, enz.). Voor Golf, we hebben veel belangrijke onderdelen die alleen zichtbaar zijn in het midden van een proces dat is van korte duur en tijdrovend om te reproduceren (d.w.z. een scherm laden die alleen laat zien, terwijl een gebruiker met hun betaalrekening). Voordat Verhalenboek, we hebben niet een goede manier om te werken aan deze onderdelen en werden gedwongen om tijdelijk hacks in orde om ze zichtbaar te maken. Nu, met Sprookjes hebben we een afgelegen plaats om gemakkelijk te werken op hen, die de bonus feature gemakkelijk toegankelijk voor ontwerpers en PMs. Het maakt het ook erg gemakkelijk voor ons om te pronken met deze staten in de sprint demo ‘ s.”

– Dan Groen, Golf Financiële

Evenals het visualiseren van verschillende staten side-by-side en de notering van rekwisieten, het is het vaak handig om te hebben geschreven over de inhoud van een component — of het uitleggen van het ontwerp rationale, use-cases, of het beschrijven van de resultaten van door de gebruiker te testen. Markdown is gemakkelijk genoeg voor *iedereen* te leren — het ideaal van een style guide moet een gezamenlijke bron voor ontwerpers en ontwikkelaars die beide disciplines bijdragen. Docz, Styleguidist en Verhalenboek alle bieden een manier om naadloos in elkaar overvloeien Markdown met de componenten zelf.

Docz

Momenteel Docz is een Reageren alleen-project, maar werkt aan ondersteuning voor Preact Vue en web components. Docz is de nieuwste van de drie instrumenten, maar heeft al bedroeg meer dan 14.000+ sterren op GitHub. Het is, naar mijn mening, is de eenvoudigste oplossing om mee te werken. Docz biedt twee componenten — <Speeltuin> en <Rekwisieten>. Deze worden geïmporteerd en gebruikt direct in .mdx-bestanden.

importeren { Speeltuin, Rekwisieten } van “docz”;
Knop import (importeren) van “../src/Knop”;

## U kunt _write_ **markdown**
### U kunt de import en het gebruik van componenten

<Button>klik</Button>

U kunt wikkel uw eigen Reageren componenten met <Speeltuin> maken het equivalent van een ingesloten CodePen of CodeSandbox — een weergave van de component naast bewerkbare code.

<Speeltuin>
<Button>klik</Button>
</Speeltuin>

<Rekwisieten> zal alle beschikbare attributen voor een bepaald Reageren component, default waarden, en of de ondersteuning is vereist.

<Rekwisieten van={Knop} />

Persoonlijk vind ik dit MDX-benadering op basis van de eenvoudigste te begrijpen en de makkelijkste om mee te werken.

Als je een fan bent van het Reageren op basis van static site generator Gatsby, Docz biedt goede integratie.

Styleguidist

Net als met Docz, voorbeelden zijn geschreven met behulp van Markdown syntax. Styleguidist maakt gebruik van Markdown code blokken (triple backticks) in de reguliere .md-bestanden, in plaats van MDX:

“js
<Button onClick={() => console.log(‘geklikt’)>Druk op Mij</Button>

Code-blokken in Markdown meestal toon enkel de code. Met Styleguidist, een code-blok met een taalcode van de js, jsx of javascript worden weergegeven als een Reageren component, samen met de code. Net als met Docz, de code is bewerkbare — je kunt rekwisieten en direct het resultaat zien.

Styleguidist zal automatisch een tabel maken van rekwisieten van beide PropTypes, Flow of Schrijfmachine verklaringen.

Styleguidist momenteel ondersteunt Reageren en Vue.

Sprookjes

Verhaal verkoopt zich als “een ontwikkelomgeving voor het UI-componenten.” In plaats van schrijven voorbeelden van componenten in Markdown-of MDX-bestanden, kunt u schrijven *verhalen* in Javascript bestanden. Een *verhaal* documenten van een bepaalde toestand van een component. Een onderdeel zou kunnen hebben verhalen voor het laden van staat en uitgeschakeld, bijvoorbeeld.

storiesOf(‘Button’, module)
.add(‘gehandicapten’, () => (
<- Toets uitgeschakeld>lorem ipsum</Button>
))

Storybook is minder eenvoudig te gebruiken dan Styleguidist en Docz. Bij meer dan 36.000 GitHub sterren, want het is de meest populaire optie. Het is een open source project met 657 medewerkers en een full-time beheerder. Het wordt gebruikt door, onder andere, Airbnb, Algolia, Atlassian, Lyft, en Salesforce. Storybook ondersteunt meer kaders dan een andere aanbieding — Reageren, Reageren Native-Vue, Hoekig, Mithril, Ember, Oproer, Slanke en platte HTML worden allemaal ondersteund.

Het schrijven van de documentatie over de componenten die momenteel vereist addons. In een toekomstige versie, het Verhaal is geïnspireerd door de Docz en de vaststelling van MDX.

# Toets

Sommige _notes_ over uw knop geschreven met **markdown syntax**.

<Verhaal name=”disabled”>
<- Toets uitgeschakeld>lorem ipsum</Button>
</Verhaal>

Storybook nieuwe Docs functie wordt uitgerold stapsgewijs de komende paar maanden en het ziet ernaar uit dat het een grote stap vooruit.

Gebruik je @storybookjs voor het onderdeel documenten of een ontwerp van de systemen? U ‘ re gonna love DocBlocks:
📦 Vallen in de MDX –
🏗 Modulair samen te stellen en
🤝 Compatibel w/ @gatsbyjs, #nextjs, enz

🔜 https://t.co/AmE4l9B3FU door @mshilman pic..com/Q48PQCmiEt

— Dominic Nguyen (@domyen) 28 April 2019

Inpakken

De voordelen van het patroon bibliotheken zijn verheerlijkt op misselijkmakende lengte in een miljoen Medium artikelen. Wanneer het goed gedaan, ze bevorderen de visuele consistentie en faciliteren van de totstandkoming van samenhangende producten. Natuurlijk, niets van deze tools kunnen de magie van een ontwerp systeem. Dat neemt voorzichtig nagedacht over het ontwerp en CSS. Maar wanneer het tijd is om te communiceren dat het systeem voor de rest van een organisatie, Docz, Sprookjes en Styleguidist zijn allemaal goede opties.