Puoi avere il miglior progetto open source, ma se non ha una buona documentazione, c'è la possibilità che non decolli mai. Una buona documentazione in ufficio ti consente di non rispondere sempre alle stesse domande. Inoltre, la documentazione garantisce che le persone possano comprendere il progetto se i membri chiave dell'azienda lasciano o cambiano ruoli. Linee guida viventi aiutano a mantenere l'integrità dei dati.
Se hai bisogno di scrivere un testo lungo, Markdown è un'ottima alternativa a HTML. A volte la sintassi di Markdown non è sufficiente. In questo caso, possiamo utilizzare HTML al suo interno. Ad esempio, elementi personalizzati. Quindi, se stai costruendo un sistema di design con componenti web nativi, è facile integrarli nella documentazione testuale. Se utilizzi React (o qualsiasi altro framework JSX, come Preact o Vue), puoi fare lo stesso utilizzando 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 viene sempre più frequentemente integrato negli strumenti di documentazione.
Cos'è MDX?
all'interno di ogni container per impostazione predefinita apparirà così: .mdx ha la stessa sintassi di Markdown, ma consente di importare componenti interattivi JSX e integrarli nel tuo contenuto. Il supporto per i componenti Vue è attualmente in alpha. Per iniziare a lavorare con MDX, è sufficiente installare "Create React App". Ci sono plugin per Next.js e Gatsby. La prossima versione di Docusaurus (versione 2) avrà anche il supporto integrato.
Scrivere documentazione con Docusaurus
Docusaurus è stato creato da Facebook. Lo utilizzano in ogni progetto open source, tranne che per React. Al di fuori dell'azienda, è utilizzato da Redux, Prettier, Gulp e Babel.
Progetti che utilizzano Docusaurus.
Docusaurus può essere utilizzato per scrivere da chiunque documentazione, non solo per descrivere il frontend. Ha React sotto il cofano, ma non è necessario conoscere React per utilizzarlo. Prende i tuoi file Markdown e, con un pizzico di magia, la documentazione ben strutturata, formattata e leggibile con un bel design è pronta.
Sul sito di Redux puoi vedere il modello standard di Docusaurus
I siti creati con Docusaurus possono includere anche un blog basato su Markdown. Prism.js è già integrato per l'evidenziazione della sintassi. Nonostante Docusaurus sia relativamente recente, è stato riconosciuto come il miglior strumento del 2018 su StackShare.
Altre opzioni per la creazione di contenuti
Docusaurus è stato specificamente progettato per la creazione di documentazione. Certo, ci sono milioni di modi per creare un sito: puoi implementare una tua soluzione in qualsiasi lingua, CMS o utilizzare un generatore di siti statici.
Ad esempio, la documentazione per React, il sistema di design IBM, Apollo e Ghost CMS utilizzano Gatsby, un generatore di siti statici spesso usato per i blog. Se lavori con Vue, VuePress sarà una buona opzione per te. Un'altra alternativa è utilizzare un generatore scritto in Python: MkDocs. È open source e configurabile tramite un file YAML. GitBook è anche una buona opzione, ma è gratuito solo per team aperti e non commerciali. Inoltre, puoi semplicemente caricare file Markdown utilizzando Git e lavorarci in Github.
Documentazione dei componenti: Docz, Storybook e Styleguidist
Linee guida, sistemi di design, librerie di componenti: qualunque sia il termine che usi, sono diventati molto popolari di recente. L'emergere di framework basati sui componenti, come React, e degli strumenti menzionati qui, ha permesso di trasformarli da progetti vanitosi in strumenti utili.
Storybook, Docz e Styleguidist fanno tutti la stessa cosa: mostrano elementi interattivi e documentano le loro API. Un progetto può avere decine o persino centinaia di componenti, tutti con vari stati e stili. Se desideri che i componenti siano riutilizzabili, le persone devono sapere che esistono. Per questo è sufficiente catalogare i componenti. Le linee guida forniscono una panoramica facile da cercare di tutti i tuoi componenti. Questo aiuta a mantenere la coerenza visiva ed evitare il lavoro duplicato.
Questi strumenti forniscono un modo semplice per visualizzare i vari stati. Può essere difficile riprodurre ogni stato di un componente nel contesto di un'applicazione reale. Invece di cliccare su un'applicazione reale, è opportuno sviluppare un componente separato. È possibile modellare stati difficili da raggiungere (ad esempio, lo stato di caricamento).
Accanto alla dimostrazione visiva di diversi stati e a un elenco di 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 imparare: idealmente, le linee guida dovrebbero essere una risorsa condivisa per designer e sviluppatori. Docz, Styleguidist e Storybook offrono un modo facile per mescolare Markdown con componenti.
Docz
Attualmente Docz funziona solo con React, ma è in corso un attivo lavoro per supportare Preact, Vue e componenti web. Docz è lo strumento più recente dei tre, ma ha già raccolto oltre 14.000 stelle su Github. Docz presenta due componenti — <Playground> e < Props >. Vengono importati e usati nei file .mdx.
import { Playground, Props } from "docz";
import Button from "..\/src\/Button";
## Puoi _scrivere_ **markdown**
### Puoi importare e usare i componenti
Puoi incapsulare i tuoi componenti React con <Playground>, per creare un'alternativa a CodePen o CodeSandbox, cioè puoi vedere il tuo componente e modificarlo.
<Props> mostrerà tutte le proprietà disponibili per questo componente React, i valori predefiniti e se è richiesta una proprietà.
<Props of={Button} />Personalmente, considero questo approccio basato su MDX il più semplice da comprendere e il più facile da usare.
Se sei un fan del generatore di siti statici Gatsby, Docz offre un'ottima integrazione.
Styleguidist
Come in Docz, gli esempi vengono scritti utilizzando la sintassi Markdown. Styleguidist utilizza blocchi di codice Markdown (triple virgolette) in file ordinari .md anziché in MDX.
```js
I blocchi di codice in Markdown mostrano generalmente solo il codice. Utilizzando Styleguidist, qualsiasi blocco di codice con il tag del linguaggio js, jsx o javascript verrà visualizzato come un componente React. Come in Docz, il codice è modificabile: puoi cambiare le proprietà e vedere il risultato in tempo reale.
Styleguidist creerà automaticamente una tabella delle proprietà dagli annunci PropTypes, Flow o Typescript.
Styleguidist attualmente supporta React e Vue.
Storybook
Storybook si posiziona come "ambiente di sviluppo per componenti UI". Invece di scrivere esempi di componenti all'interno di file Markdown o MDX, scrivi delle modifiche. Il supporto ufficiale per l'elenco di blocco è fornito nel corrispondente all'interno di file Javascript. Storia documentano uno stato specifico del componente. Ad esempio, un componente può avere storie per uno stato di caricamento e uno stato disattivato (disabilitato).
storiesOf('Button', module)
.add('disabilitato', () => (
))Storybook è molto più complesso di Styleguidist e Docz. Tuttavia, è anche l'opzione più popolare, con oltre 36.000 stelle su Github. Si tratta di un progetto open source, con 657 collaboratori e supporto da parte di dipendenti a tempo pieno. È 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 saranno introdotte gradualmente nei prossimi mesi e, a quanto pare, rappresenteranno un grande passo avanti.
Conclusioni
I vantaggi della libreria di pattern sono esaltati in milioni di articoli su Medium. Quando sono ben implementati, facilitano la creazione di prodotti correlati e il mantenimento dell'identità. Ovviamente, nessuno di questi strumenti può magicamente creare un sistema di design. Ciò richiede una progettazione attenta del design e del CSS. Ma quando arriva il momento di rendere disponibile il sistema di design per l'intera 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
