Du har måske et bedre open source-projekt, men hvis det ikke har god dokumentation, er chancerne for, at det aldrig vil tage fart. På kontoret vil god dokumentation forhindre dig i at besvare de samme spørgsmål igen og igen. Dokumentation sikrer også, at folk kan få mening i projektet, hvis nøglemedarbejdere forlader virksomheden eller roller ændres. Live retningslinjer hjælper med at sikre dataintegritet.
Hvis du skal skrive lang tekst, er Markdown et godt alternativ til HTML. Nogle gange er Markdown-syntaksen ikke nok. I dette tilfælde kan vi bruge HTML inde i det. For eksempel brugerdefinerede elementer. Derfor, hvis du bygger et designsystem med native webkomponenter, er det nemt at inkludere dem i tekstdokumentation. Hvis du bruger React (eller enhver anden JSX-ramme som Preact eller Vue), kan du gøre det samme med MDX.
Denne artikel er en bred oversigt over værktøjer til at skrive dokumentation og skabe en guideline. Ikke alle de værktøjer, der er anført her, bruger MDX, men det bliver i stigende grad inkluderet i dokumentationsværktøjer.
Hvad er MDX?
fil .mdx har samme syntaks som Markdown, men giver dig mulighed for at importere interaktive JSX-komponenter og indlejre dem i dit indhold. Support til Vue-komponenter er i alfa. For at begynde at arbejde med MDX skal du blot installere "Create React App". Der er plugins til Next.js og Gatsby. Den næste version af Docusaurus (version 2) vil også have indbygget understøttelse.
Skrive dokumentation med Docusaurus
Docusaurus skrev på Facebook. De bruger det på alle open source-projekter undtagen React. Uden for virksomheden bruger Redux, Prettier, Gulp og Babel det.
Projekter, der bruger Docusaurus.
Docusaurus kan bruges til at skrive enhver dokumentation, ikke kun for at beskrive frontend. Den har React under motorhjelmen, men du behøver ikke at være bekendt med den for at bruge den. Det kræver dine Markdown-filer, en knivspids magi og velstruktureret, formateret og læsbar dokumentation med et smukt design er klar.
Du kan se standard Docusaurus-skabelonen på Redux-webstedet.
Websteder bygget med Docusaurus kan også omfatte en Markdown-baseret blog. Til syntaksfremhævning er Prism.js straks inkluderet. På trods af at Docusaurus er dukket op relativt for nylig, blev det anerkendt som det bedste værktøj i 2018 på StackShare.
Andre muligheder for oprettelse af indhold
Docusaurus er specielt designet til at skabe dokumentation. Selvfølgelig er der en million og én måder at lave et websted på - du kan implementere din egen løsning på ethvert sprog, CMS, eller bruge en statisk webstedsgenerator.
For eksempel bruger dokumentationen til React, IBM-designsystemet, Apollo og Ghost CMS Gatsby, en statisk webstedsgenerator, der ofte bruges til blogs. Hvis du arbejder med Vue, er VuePress en god mulighed for dig. En anden mulighed er at bruge en generator skrevet i Python - MkDocs. Den er åben og konfigureret med en enkelt YAML-fil. GitBook er også en god mulighed, men den er kun gratis for åbne og ikke-kommercielle hold. Du kan også bare uploade mardown-filer ved hjælp af git og arbejde med dem i Github.
Komponentdokumentation: Docz, Storybook og Styleguidist
Retningslinjer, systemdesign, komponentbiblioteker, hvad end du vil kalde dem, disse er blevet meget populære på det seneste. Fremkomsten af komponentrammeværker såsom React og de her nævnte værktøjer har gjort det muligt at transformere dem fra forfængelighedsprojekter til nyttige værktøjer.
Storybook, Docz og Styleguidist gør det samme: Vis interaktive elementer og dokumenter deres API. Et projekt kan have snesevis eller endda hundredvis af komponenter, alle med forskellige tilstande og stilarter. Hvis du ønsker, at komponenter skal genbruges, skal folk vide, at de findes. For at gøre dette er det nok at katalogisere komponenterne. Retningslinjer giver et overblik over alle dine komponenter, der er let at søge. Dette hjælper med at bevare visuel konsistens og undgår gentagende arbejde.
Disse værktøjer giver en bekvem måde at se forskellige tilstande på. Det kan være svært at replikere enhver tilstand af en komponent i forbindelse med en reel applikation. I stedet for at klikke på den faktiske applikation, er det værd at udvikle en separat komponent. Det er muligt at modellere svært tilgængelige tilstande (f.eks. indlæsningstilstand).
Sammen med en visuel demonstration af forskellige tilstande og en liste over egenskaber er det ofte nødvendigt at skrive en generel beskrivelse af indholdet - designrationaler, use cases eller en beskrivelse af resultaterne af brugertest. Markdown er meget let at lære - ideelt set bør retningslinjer være en fælles ressource for designere og udviklere. Docz, Styleguidist og Storybook tilbyder en måde at nemt blande Markdown med komponenter.
Docz
I øjeblikket arbejder Docz kun med React, men arbejder aktivt på support til Preact, Vue og webkomponenter. Docz er det seneste af de tre værktøjer, men har været i stand til at samle over 14 stjerner på Github. Docz introducerer to komponenter − <Playground> и < Props >. De importeres og bruges i filer .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>Du kan pakke dine egne React-komponenter ind med <Playground>at oprette en analog af den indbyggede CodePen eller CodeSandbox - det vil sige, at du ser din komponent og kan redigere den.
<Playground>
<Button>click</Button>
</Playground><Props> vil vise alle tilgængelige egenskaber for den givne React-komponent, standardværdier og om egenskaben er påkrævet.
<Props of={Button} />Personligt synes jeg, at denne MDX-baserede tilgang er den nemmeste at forstå og den nemmeste at arbejde med.
Hvis du er fan af Gatsbys statiske webstedsgenerator, tilbyder Docz fantastiske integrationer.
stilguide
Som i Docz er eksempler skrevet ved hjælp af Markdown-syntaks. Styleguidist bruger Markdown-kodeblokke (tredobbelte anførselstegn) i almindelige filer .md filer, ikke i MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Kodeblokke i Markdown viser normalt bare koden. Når du bruger Styleguidist, enhver kodeblok med et sprogtag js, jsx eller javascript vil gengives som en React-komponent. Ligesom Docz er koden redigerbar - du kan ændre egenskaber og se resultatet med det samme.
Styleguidist vil automatisk oprette et egenskabsark fra PropTypes, Flow eller Typescript erklæringer.
Styleguidist understøtter nu React og Vue.
Storybook
Storybook fakturerer sig selv som et "UI-komponentudviklingsmiljø". I stedet for at skrive komponenteksempler inde i Markdown- eller MDX-filer, skriver du historie inde i Javascript-filer. Story dokumentere en komponents specifikke tilstand. For eksempel kan en komponent have historier for en indlæsningstilstand og en deaktiveret tilstand (deaktiveret).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Storybook er meget mere kompleks end Styleguidist og Docz. Men samtidig er dette den mest populære mulighed, på Github har projektet mere end 36 stjerner. Dette er et open source-projekt med 000 bidragydere og personaleledsagelse. Det bruges af Airbnb, Algolia, Atlassian, Lyft og Salesforce. Storybook understøtter flere rammer end konkurrenterne - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte og almindelig HTML.
I en fremtidig udgivelse vil der være chips fra Docz og MDX er ved at blive introduceret.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>De nye Storybook-funktioner vil rulle ud gradvist i løbet af de næste par måneder, og det ser ud til, at det vil være et stort skridt fremad.
Resultaterne af
Fordelene ved mønsterbiblioteket hyldes i millioner af artikler på Medium. Når det er gjort godt, gør de det lettere at skabe relaterede produkter og bevare en identitet. Selvfølgelig vil ingen af disse værktøjer på magisk vis skabe et designsystem. Dette kræver omhyggeligt design og CSS-design. Men når det er tid til at gøre designsystemet tilgængeligt for hele virksomheden, er Docz, Storybook og Styleguidist gode muligheder.
Fra en oversætter. Dette er min første oplevelse på Habré. Hvis du finder nogle unøjagtigheder, eller har forslag til forbedring af artiklen - skriv i en personlig.
Kilde: www.habr.com