Puoi avere il miglior progetto open source, ma se non ha una buona documentazione, è probabile che non decolli mai. Una buona documentazione in ufficio ti permetterà di non rispondere alle stesse domande. La documentazione garantisce anche che le persone possano comprendere il progetto se dipendenti chiave lasciano l'azienda o cambiano ruolo. Le linee guida dinamiche aiutano a garantire l'integrità dei dati.
Se hai bisogno di scrivere un testo lungo, Markdown è un'ottima alternativa all'HTML. A volte la sintassi di Markdown non è sufficiente. In questo caso, possiamo usare l'HTML al suo interno. Ad esempio, elementi personalizzati. Quindi, se stai costruendo un sistema di design con componenti web nativi, è facile includerli nella documentazione testuale. Se stai usando React (o qualsiasi altro framework JSX, come Preact o Vue), puoi fare lo stesso usando MDX.
Questo articolo è una panoramica ampia degli strumenti per la scrittura di documentazione e la creazione di linee guida. Non tutti gli strumenti elencati qui utilizzano MDX, ma questo viene incluso sempre più spesso negli strumenti di documentazione.
Che cos'è MDX?
File .mdx ha la stessa sintassi del Markdown, ma consente di importare componenti interattivi JSX e integrarli nel tuo contenuto. Il supporto per i componenti Vue è in fase alfa. Per iniziare a lavorare con MDX, è sufficiente installare "Create React App". Sono disponibili plugin per Next.js e Gatsby. La prossima versione di Docusaurus (versione 2) avrà anche un supporto nativo.
Scrivere documentazione con Docusaurus
Docusaurus è stato sviluppato da Facebook. Viene utilizzato in ciascun progetto open source, eccetto React. Al di fuori dell'azienda, è usato da Redux, Prettier, Gulp e Babel.
Progetti che utilizzano Docusaurus.
Docusaurus può essere utilizzato per scrivere qualunque documentazione, non solo per descrivere il front-end. Si basa su React, ma non è necessario conoscerlo per utilizzarlo. Prende i tuoi file Markdown e, con un tocco di magia, produce una documentazione ben strutturata, formattata e leggibile con un design accattivante.
Nel sito di Redux puoi vedere il template standard di Docusaurus
I siti creati con Docusaurus possono anche includere un blog basato su Markdown. La sintassi è evidenziata grazie a Prism.js. Nonostante Docusaurus sia comparso relativamente di recente, è stato riconosciuto come il miglior strumento del 2018 su StackShare.
Altre opzioni per la creazione di contenuti
Docusaurus è stato progettato specificamente per la creazione di documentazione. Certo, ci sono milioni di modi per realizzare un sito: puoi avviare la tua soluzione in qualsiasi linguaggio, CMS o utilizzare un generatore di siti statici.
Ad esempio, la documentazione per React, il sistema di design di IBM, Apollo e Ghost CMS utilizzano Gatsby, un generatore di siti statici spesso impiegato per i blog. Se lavori con Vue, VuePress è un'ottima scelta. Un'altra opzione è utilizzare un generatore scritto in Python, MkDocs. È open source e configurabile tramite un file YAML. GitBook è un'altra buona alternativa, ma è gratuito solo per team aperti e non commerciali. Inoltre, puoi semplicemente caricare file markdown utilizzando Git e lavorarci su GitHub.
Documentazione dei componenti: Docz, Storybook e Styleguidist
Linee guida, design del sistema, librerie di componenti: qualunque sia il termine che usate, è un argomento molto in voga al giorno d'oggi. L'emergere di framework per componenti come React e degli strumenti menzionati qui ha permesso di trasformarli da progetti ambiziosi a strumenti utili.
Storybook, Docz e Styleguidist fanno tutte la stessa cosa: mostrano elementi interattivi e documentano le loro API. Un progetto può avere decine o addirittura centinaia di componenti, ognuno con vari stati e stili. Per garantire il riutilizzo dei componenti, è fondamentale che tutte le persone sappiano che esistono. Catalogare i componenti è sufficiente. Le linee guida offrono una panoramica facile da cercare di tutti i vostri componenti, contribuendo a mantenere coerenza visiva e a evitare il lavoro duplicato.
Questi strumenti offrono un modo conveniente per visualizzare diversi stati. Può essere difficile riprodurre ogni stato di un componente nel contesto di un'applicazione reale. Invece di cliccare sull'applicazione reale, è meglio sviluppare un componente separato. È possibile simulare stati difficili da ottenere (ad esempio, lo stato di caricamento).
Oltre a una dimostrazione visiva dei vari stati e a un elenco delle proprietà, è spesso necessario scrivere una descrizione generale del contenuto: giustificazioni del design, casi d'uso o descrizioni dei risultati dei test utente. Markdown è molto semplice da apprendere — idealmente, le linee guida dovrebbero essere una risorsa condivisa per designer e sviluppatori. Docz, Styleguidist e Storybook offrono un modo semplice per mescolare Markdown con componenti.
Docz
Attualmente, Docz funziona solo con React, ma è in lavorazione il supporto per Preact, Vue e componenti web. Docz è il più recente dei tre strumenti, ma è riuscito a raccogliere oltre 14.000 stelle su GitHub. Docz offre due componenti — <Playground> e < Props >. Vengono importati e utilizzati nei file. .mdx.
import { Playground, Props } from "docz";
import Button from "../src/Button";
## Puoi _scrivere_ **markdown**
### Puoi importare e utilizzare i componenti
Puoi avvolgere i tuoi componenti React con <Playground>, per creare un'alternativa a CodePen o CodeSandbox — ovvero puoi vedere il tuo componente e modificarlo.
<Props> mostrerà tutte le proprietà disponibili per questo componente React, i valori predefiniti e se la proprietà è obbligatoria.
<Props of={Button} />Personalmente, ritengo che questo approccio basato su MDX sia il più semplice da comprendere e il più facile da utilizzare.
Se sei un fan del generatore di siti statici Gatsby, Docz offre un'ottima integrazione.
Styleguidist
Come in Docz, gli esempi sono scritti usando la sintassi Markdown. Styleguidist utilizza blocchi di codice Markdown (tre virgolette) in file normali .md file, non in MDX.
```js
I blocchi di codice in Markdown mostrano solitamente solo il codice. Utilizzando Styleguidist, qualsiasi blocco di codice con il tag di lingua js, jsx o javascript verrà visualizzato come un componente React. Come in Docz, il codice è modificabile — puoi cambiare le proprietà e vedere immediatamente il risultato.
Styleguidist genererà automaticamente una tabella delle proprietà dalle dichiarazioni di PropTypes, Flow o Typescript.
Styleguidist ora supporta React e Vue.
Storybook
Storybook si presenta come un «ambiente di sviluppo per componenti UI». Invece di scrivere esempi di componenti all'interno di file Markdown o MDX, si scrive storie all'interno di file Javascript. Storia documentando uno stato specifico del componente. Ad esempio, un componente può avere storie per lo stato di caricamento e lo stato disabilitato (disabled).
storiesOf('Button', module)
.add('disabled', () => (
))Storybook è molto più complesso rispetto a Styleguidist e Docz. Tuttavia, è la scelta più popolare, con oltre 36.000 stelle su GitHub. È un progetto open source, con 657 collaboratori e mantenuto da uno staff interno. Utilizzato da Airbnb, Algolia, Atlassian, Lyft e Salesforce. Storybook supporta più framework rispetto ai concorrenti — React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte e HTML standard.
Nella prossima versione ci saranno funzionalità da Docz e verrà implementato 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 introdotte gradualmente nei prossimi mesi e, a quanto pare, rappresenteranno un grande passo avanti.
Risultati
I vantaggi delle librerie di pattern sono celebrati in milioni di articoli su Medium. Quando tutto è ben fatto, semplificano la creazione di prodotti correlati e il mantenimento dell'identità. Certamente, nessuno di questi strumenti può magicamente creare un sistema di design. Questo richiede una progettazione attenta e CSS. Ma quando arriva il momento di rendere il sistema di design accessibile a tutta l'azienda, Docz, Storybook e Styleguidist sono ottime opzioni.
Dall'autore. Questa è la mia prima esperienza su Habr. Se hai trovato delle imprecisioni o hai suggerimenti per migliorare l'articolo, scrivimi in privato.
Fonte: habr.com
