Potresti avere un progetto open source migliore, ma se non ha una buona documentazione, è probabile che non decollerà mai. In ufficio, una buona documentazione ti impedirà di rispondere sempre alle stesse domande. La documentazione garantisce inoltre che le persone possano dare un senso al progetto se i dipendenti chiave lasciano l'azienda o cambiano i ruoli. Le linee guida in tempo reale aiutano a garantire l'integrità dei dati.
Se devi scrivere un testo lungo, Markdown è un'ottima alternativa all'HTML. A volte la sintassi Markdown non è sufficiente. In questo caso, possiamo usare l'HTML al suo interno. Ad esempio, elementi personalizzati. Pertanto, se stai costruendo un sistema di progettazione con componenti Web nativi, è facile includerli nella documentazione di testo. Se stai usando React (o qualsiasi altro framework JSX come Preact o Vue), puoi fare lo stesso con MDX.
Questo articolo è un'ampia panoramica degli strumenti per scrivere la documentazione e creare una linea guida. Non tutti gli strumenti qui elencati utilizzano MDX, ma viene sempre più incluso negli strumenti di documentazione.
Che cos'è l'MDX?
file .mdx ha la stessa sintassi di Markdown ma ti consente di importare componenti JSX interattivi e incorporarli nei tuoi contenuti. Il supporto per i componenti Vue è in alpha. Per iniziare a lavorare con MDX, basta installare "Create React App". Esistono plugin per Next.js e Gatsby. Anche la prossima versione di Docusaurus (versione 2) avrà il supporto integrato.
Scrivere documentazione con Docusaurus
Docusauro ha scritto su Facebook. Lo usano su tutti i progetti open source tranne React. Al di fuori dell'azienda, Redux, Prettier, Gulp e Babel lo usano.
Progetti che utilizzano Docusaurus.
Docusaurus può essere usato per scrivere qualsiasi documentazione, non solo per descrivere il frontend. Ha React sotto il cofano, ma non devi avere familiarità con esso per usarlo. Ci vogliono i tuoi file Markdown, un pizzico di magia ed è pronta una documentazione ben strutturata, formattata e leggibile con un bel design.
Puoi vedere il modello Docusaurus predefinito sul sito Web di Redux.
I siti creati con Docusaurus possono includere anche un blog basato su Markdown. Per l'evidenziazione della sintassi, Prism.js è immediatamente incluso. Nonostante Docusaurus sia apparso relativamente di recente, è stato riconosciuto come il miglior strumento del 2018 su StackShare.
Altre opzioni per la creazione di contenuti
Docusaurus è specificamente progettato per creare documentazione. Naturalmente, ci sono un milione e un modo per creare un sito Web: puoi distribuire la tua soluzione in qualsiasi lingua, CMS o utilizzare un generatore di siti statici.
Ad esempio, la documentazione per React, il sistema di progettazione IBM, Apollo e Ghost CMS utilizza Gatsby, un generatore di siti statici spesso utilizzato per i blog. Se lavori con Vue, allora VuePress è una buona opzione per te. Un'altra opzione è utilizzare un generatore scritto in Python - MkDocs. È aperto e configurato con un singolo file YAML. Anche GitBook è una buona opzione, ma è gratuito solo per team aperti e non commerciali. Puoi anche caricare file mardown usando git e lavorare con loro in Github.
Componente Documentazione: Docz, Storybook e Styleguidist
Linee guida, design del sistema, librerie di componenti, come volete chiamarle, sono diventate molto popolari ultimamente. L'emergere di framework di componenti come React e gli strumenti qui menzionati ha permesso di trasformarli da progetti di vanità in strumenti utili.
Storybook, Docz e Styleguidist fanno la stessa cosa: visualizzano elementi interattivi e documentano la loro API. Un progetto può avere dozzine o addirittura centinaia di componenti, tutti con stati e stili diversi. Se vuoi che i componenti vengano riutilizzati, le persone devono sapere che esistono. Per fare ciò è sufficiente catalogare i componenti. Le linee guida forniscono una panoramica di facile ricerca di tutti i componenti. Questo aiuta a mantenere la coerenza visiva ed evitare il lavoro ripetitivo.
Questi strumenti forniscono un modo conveniente per visualizzare vari stati. Può essere difficile replicare ogni stato di un componente nel contesto di un'applicazione reale. Invece di fare clic sull'applicazione vera e propria, vale la pena sviluppare un componente separato. È possibile modellare stati difficili da raggiungere (ad esempio, stato di caricamento).
Insieme a una dimostrazione visiva dei vari stati ea un elenco di proprietà, è spesso necessario scrivere una descrizione generale del contenuto: motivazioni di progettazione, casi d'uso o una descrizione dei risultati dei test utente. Markdown è molto facile da imparare: idealmente, le linee guida dovrebbero essere una risorsa condivisa per designer e sviluppatori. Docz, Styleguidist e Storybook offrono un modo per combinare facilmente Markdown con i componenti.
Doc
Attualmente, Docz funziona solo con React, ma sta lavorando attivamente al supporto per Preact, Vue e componenti web. Docz è il più recente dei tre strumenti, ma è stato in grado di raccogliere oltre 14 stelle su Github. Docz introduce due componenti − <Playground> и < Props >. Vengono importati e utilizzati nei file .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## You can _write_ **markdown**
### You can import and use components
<Button>click</Button>Puoi avvolgere i tuoi componenti React con <Playground>per creare un analogo del CodePen o CodeSandbox integrato, ovvero vedi il tuo componente e puoi modificarlo.
<Playground>
<Button>click</Button>
</Playground><Props> mostrerà tutte le proprietà disponibili per il componente React specificato, i valori predefiniti e se la proprietà è richiesta.
<Props of={Button} />Personalmente, trovo che questo approccio basato su MDX sia il più facile da capire e il più facile con cui lavorare.
Se sei un fan del generatore di siti statici di Gatsby, Docz offre ottime integrazioni.
guida di stile
Come in Docz, gli esempi sono scritti usando la sintassi Markdown. Styleguidist utilizza blocchi di codice Markdown (virgolette triple) in file regolari .md file, non in MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>I blocchi di codice in Markdown di solito mostrano solo il codice. Quando si utilizza Styleguidist, qualsiasi blocco di codice con un tag di lingua js, jsx o javascript renderà come un componente React. Come Docz, il codice è modificabile: puoi modificare le proprietà e vedere immediatamente il risultato.
Styleguidist creerà automaticamente una finestra delle proprietà dalle dichiarazioni PropTypes, Flow o Typescript.
Styleguidist ora supporta React e Vue.
Libro di storia
Storybook si definisce un "ambiente di sviluppo di componenti dell'interfaccia utente". Invece di scrivere esempi di componenti all'interno di file Markdown o MDX, scrivi storie all'interno dei file Javascript. storia documentare lo stato specifico di un componente. Ad esempio, un componente potrebbe avere cronologie per uno stato di caricamento e uno stato disabilitato (disabile).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Storybook è molto più complesso di Styleguidist e Docz. Ma allo stesso tempo, questa è l'opzione più popolare, su Github il progetto ha più di 36 stelle. Si tratta di un progetto open source con 000 contributori e accompagnamento del personale. È utilizzato da Airbnb, Algolia, Atlassian, Lyft e Salesforce. Storybook supporta più framework rispetto alla concorrenza: React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte e semplice HTML.
In una versione futura, verranno introdotti i chip di Docz e MDX.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Le nuove funzionalità di Storybook verranno implementate gradualmente nei prossimi mesi e sembra che sarà un grande passo avanti.
Risultati di
I vantaggi della libreria di modelli sono lodati in milioni di articoli su Medium. Se fatti bene, rendono più facile creare prodotti correlati e mantenere un'identità. Naturalmente, nessuno di questi strumenti creerà magicamente un sistema di progettazione. Ciò richiede un'attenta progettazione e progettazione CSS. Ma quando arriva il momento di rendere disponibile il sistema di progettazione a tutta l'azienda, Docz, Storybook e Styleguidist sono ottime opzioni.
Da un traduttore. Questa è la mia prima esperienza su Habré. Se trovi inesattezze o hai suggerimenti per migliorare l'articolo, scrivi in \uXNUMXb\uXNUMXbpersonale.
Fonte: habr.com