Vous pouvez avoir un meilleur projet open source, mais s'il n'a pas une bonne documentation, il est probable qu'il ne décollera jamais. Au bureau, une bonne documentation vous permettra de ne pas répondre aux mêmes questions. La documentation garantit également que les gens peuvent comprendre le projet si des employés clés quittent l'entreprise ou si les rôles changent. Les directives en direct aident à garantir l'intégrité des données.
Si vous avez besoin d'écrire un texte long, Markdown est une excellente alternative au HTML. Parfois, la syntaxe Markdown n'est pas suffisante. Dans ce cas, nous pouvons utiliser le code HTML à l'intérieur. Par exemple, des éléments personnalisés. Par conséquent, si vous créez un système de conception avec des composants Web natifs, ils sont faciles à inclure dans la documentation textuelle. Si vous utilisez React (ou tout autre framework JSX comme Preact ou Vue), vous pouvez faire de même avec MDX.
Cet article est un aperçu général de la rédaction de documentation et des outils de directives. Tous les outils répertoriés ici n'utilisent pas MDX, mais il est de plus en plus inclus dans les outils de documentation.
Qu'est-ce que MDX?
Le fichier .mdx a la même syntaxe que Markdown, mais vous permet d'importer des composants interactifs JSX et de les incorporer dans votre contenu. La prise en charge des composants Vue est en alpha. Pour commencer à travailler avec MDX, il suffit d'installer la "Create React App". Il existe des plugins pour Next.js et Gatsby. La prochaine version de Docusaurus (version 2) aura également un support intégré.
Rédaction de documentation avec Docusaurus
Docusaurus a écrit sur Facebook. Ils l'utilisent sur tous les projets open source sauf React. En dehors de l'entreprise, Redux, Prettier, Gulp et Babel l'utilisent.
Projets utilisant Docusaurus.
Docusaurus peut être utilisé pour écrire n'importe quelle documentation, pas seulement pour décrire le frontend. Il a React sous sa capuche, mais pour l'utiliser, il n'est pas nécessaire de le connaître. Il prend vos fichiers Markdown, une pincée de magie et une documentation bien structurée, formatée et lisible avec un beau design prêt.
Sur le site Web de Redux, vous pouvez voir le modèle Docusaurus standard
Les sites créés à l'aide de Docusaurus peuvent également inclure un blog basé sur Markdown. Prism.js est immédiatement connecté à la coloration syntaxique. Malgré le fait que Docusaurus soit apparu relativement récemment, il a été reconnu comme le meilleur outil de 2018 chez StackShare.
Autres options de création de contenu
Docusaurus est spécialement conçu pour créer de la documentation. Bien sûr, il existe un million et une façon de créer un site - vous pouvez déployer votre propre solution dans n'importe quelle langue, CMS ou utiliser le générateur de site statique.
Par exemple, la documentation de React, le système de conception d'IBM, Apollo et Ghost CMS utilise Gatsby, un générateur de site statique qui est souvent utilisé pour les blogs. Si vous travaillez avec Vue, VuePress est une bonne option pour vous. Une autre option consiste à utiliser un générateur écrit en Python - MkDocs. Il est ouvert et configurable avec un seul fichier YAML. GitBook est également une bonne option, mais il est gratuit uniquement pour les équipes ouvertes et à but non lucratif. Et vous pouvez simplement télécharger des fichiers mardown en utilisant gith et travailler avec eux sur Github.
Documentation des composants: Docz, Storybook et Styleguidist
Lignes directrices, conception de systèmes, bibliothèques de composants - peu importe comment vous les appelez, mais elles sont devenues très populaires ces derniers temps. L'avènement des frameworks de composants, tels que React et les outils mentionnés ici, ont permis de les transformer de projets vaniteux en outils utiles.
Storybook, Docz et Styleguidist - faites la même chose: affichez des éléments interactifs et documentez leur API. Un projet peut avoir des dizaines, voire des centaines de composants, tous avec des états et des styles différents. Si vous souhaitez que les composants soient réutilisés, les utilisateurs doivent savoir qu'ils existent. Pour ce faire, il vous suffit de cataloguer les composants. Les directives fournissent une vue d'ensemble consultable de tous vos composants. Cela permet de maintenir la cohérence visuelle et d'éviter les travaux répétitifs.
Ces outils offrent un moyen pratique d'afficher différents états. Il peut être difficile de reproduire chaque état de composant dans le contexte d'une application réelle. Au lieu de cliquer sur une application réelle, vous devez développer un composant distinct. Vous pouvez simuler des états difficiles à atteindre (par exemple, l'état de démarrage).
En plus d'une démonstration visuelle de divers états et d'une liste de propriétés, il est souvent nécessaire de rédiger une description générale du contenu - justifications de conception, études de cas ou description des résultats des tests utilisateur. Markdown est très facile à apprendre - idéalement, les lignes directrices devraient être une ressource partagée pour les concepteurs et les développeurs. Docz, Styleguidist et Storybook offrent un moyen de mélanger facilement Markdown avec des composants.
Docz
Maintenant, Docz ne fonctionne qu'avec React, mais il existe un travail actif sur la prise en charge de Preact, Vue et des composants Web. Docz est le plus récent des trois instruments, mais sur Github, il a pu collecter plus de 14 000 étoiles. Docz représente deux composants - <Playground> et < Props > . Ils sont importés et utilisés dans des fichiers .mdx .
import { Playground, Props } from "docz"; import Button from "../src/Button"; ## You can _write_ **markdown** ### You can import and use components <Button>click</Button>
Vous pouvez encapsuler vos propres composants React avec <Playground> pour créer un analogue du CodePen ou du CodeSandbox intégré - c'est-à-dire que vous voyez votre composant et vous pouvez le modifier.
<Playground> <Button>click</Button> </Playground>
<Props> affichera toutes les propriétés disponibles pour ce composant React, les valeurs par défaut et si une propriété est requise.
<Props of={Button} />
Personnellement, je pense que cette approche basée sur MDX est la plus facile à comprendre et à utiliser.
Si vous êtes un fan du générateur de site statique Gatsby, Docz offre une excellente intégration.
Styleguidist
Comme Docz, les exemples sont écrits en utilisant la syntaxe Markdown. Styleguidist utilise des blocs de code Markdown (guillemets triples) dans les fichiers .md normaux, pas dans MDX.
```js <Button onClick={() => console.log('clicked')>Push Me</Button>
Les blocs de code dans Markdown ne montrent généralement que le code. Lorsque vous utilisez Styleguidist, tout bloc de code avec une balise de langage js , jsx ou javascript sera affiché en tant que composant React. Comme dans Docz, le code est modifiable - vous pouvez modifier les propriétés et voir instantanément le résultat.
Styleguidist créera automatiquement une table de propriétés à partir des déclarations PropTypes, Flow ou Typescript.
Styleguidist prend désormais en charge React et Vue.
Livre de contes
Storybook se positionne comme un "environnement de développement pour les composants de l'interface utilisateur". Au lieu d'écrire des exemples de composants dans des fichiers Markdown ou MDX, vous écrivez des histoires dans des fichiers Javascript. L'historique est documenté par l'état spécifique du composant. Par exemple, un composant peut avoir des historiques pour l'état de démarrage et l'état désactivé.
storiesOf('Button', module) .add('disabled', () => ( <Button disabled>lorem ipsum</Button> ))
Storybook est beaucoup plus compliqué que Styleguidist et Docz. Mais en même temps, c'est l'option la plus populaire, sur Github, le projet compte plus de 36 000 étoiles. Il s'agit d'un projet open source, il implique 657 participants et est accompagné d'employés à temps plein. Il est utilisé par Airbnb, Algolia, Atlassian, Lyft et Salesforce. Storybook prend en charge plus de frameworks que ses concurrents - React, React Native, Vue, Angular, Mithril, Ember, Riot, Svelte et HTML standard.
Dans une future version, il y aura des puces de Docz et MDX sera introduit.
# Button Some _notes_ about your button written with **markdown syntax**. <Story name="disabled"> <Button disabled>lorem ipsum</Button> </Story>
Les nouvelles fonctionnalités du Storybook apparaîtront progressivement au cours des prochains mois et, apparemment, ce sera un grand pas en avant.
Résumé
Les avantages de la bibliothèque de modèles sont vantés dans des millions d'articles sur Medium. Lorsqu'ils sont bien faits, ils facilitent la création de produits connexes et le maintien de l'identité. Bien sûr, aucun de ces outils ne créera comme par magie un système de conception. Cela nécessite une conception soignée et une conception CSS. Mais quand vient le temps de mettre le système de conception à la disposition de toute l'entreprise, Docz, Storybook et Styleguidist sont d'excellentes options.
Du traducteur. C'est ma première expérience sur Habré. Si vous trouvez que certains ne sont pas exacts, ou s'il y a des suggestions pour améliorer l'article - écrivez à titre personnel.