Vous pouvez avoir le meilleur projet open source, mais s'il ne dispose pas d'une bonne documentation, il y a de fortes chances qu'il ne décolle jamais. Au bureau, une bonne documentation vous évitera de 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. Des directives vivantes contribueront à garantir l’intégrité des données.
Si vous devez écrire un texte long, Markdown est une excellente alternative au HTML. Parfois, la syntaxe Markdown ne suffit pas. Dans ce cas, nous pouvons utiliser du 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 peuvent être facilement inclus dans la documentation texte. Si vous utilisez React (ou tout autre framework JSX comme Preact ou Vue), vous pouvez faire la même chose en utilisant MDX.
Cet article est un aperçu général des outils permettant de rédiger de la documentation et de créer des lignes directrices. Tous les outils répertoriés ici n'utilisent pas MDX, mais celui-ci est de plus en plus inclus dans les outils de documentation.
Qu’est-ce que le MDX ?
Dossier .mdx a la même syntaxe que Markdown, mais vous permet d'importer des composants JSX interactifs et de les intégrer dans votre contenu. La prise en charge des composants Vue est en version alpha. Pour commencer à travailler avec MDX, installez simplement « Create React App ». Il existe des plugins pour Next.js et Gatsby. La prochaine version de Docusaurus (version 2) bénéficiera également d'un support natif.
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, il est utilisé par Redux, Prettier, Gulp et Babel.
Projets qui utilisent Docusaurus.
Docusaurus peut être utilisé pour écrire tout documentation, pas seulement pour décrire le frontend. Il a React sous le capot, mais vous n'avez pas besoin de le connaître pour l'utiliser. Il prend vos fichiers Markdown, une pincée de magie et une documentation bien structurée, formatée et lisible avec un beau design est prête.
Sur le site Redux, vous pouvez voir le modèle Docusaurus standard
Les sites Web créés avec Docusaurus peuvent également inclure un blog basé sur Markdown. Prism.js est immédiatement connecté pour la coloration syntaxique. Malgré le fait que Docusaurus soit apparu relativement récemment, il a été reconnu comme le meilleur outil de 2018 sur 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 mille et une façons de créer un site Web : vous pouvez déployer votre propre solution dans n'importe quel langage, CMS ou utiliser un générateur de site statique.
Par exemple, la documentation de React, du système de conception IBM, d'Apollo et de Ghost CMS utilise Gatsby, un générateur de sites statiques 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 open source et configuré à l'aide d'un seul fichier YAML. GitBook est également une bonne option, mais il n'est gratuit que pour les équipes publiques et non commerciales. Vous pouvez également simplement télécharger des fichiers Mardown à l'aide de Git et travailler avec eux dans Github.
Composants de documentation : Docz, Storybook et Styleguidist
Lignes directrices, conception de systèmes, bibliothèques de composants - peu importe comment vous les appelez, cela est devenu très populaire ces derniers temps. L'avènement des frameworks de composants comme React et les outils mentionnés ici les ont transformés de projets vaniteux en outils utiles.
Storybook, Docz et Styleguidist font tous la même chose : afficher des éléments interactifs et documenter leur API. Un projet peut comporter des dizaines, voire des centaines de composants, tous avec des états et des styles différents. Si vous souhaitez que des composants soient réutilisés, les gens doivent savoir qu’ils existent. Pour ce faire, cataloguez simplement les composants. Les directives fournissent un aperçu facile à trouver de tous vos composants. Cela permet de maintenir une cohérence visuelle et d’éviter un travail répétitif.
Ces outils constituent un moyen pratique d’afficher différents états. Il peut être difficile de reproduire chaque état d’un composant dans le cadre d’une application réelle. Au lieu de cliquer sur l'application elle-même, cela vaut la peine de développer un composant distinct. Les états difficiles à atteindre (tels que les états de chargement) peuvent être simulés.
Outre une démonstration visuelle des différents états et une liste de propriétés, il est souvent nécessaire de rédiger une description générale du contenu : justifications de conception, cas d'utilisation ou descriptions des résultats des tests utilisateur. Markdown est très facile à apprendre – idéalement, les directives 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.
Documents
Actuellement, Docz ne fonctionne qu'avec React, mais des travaux actifs sont en cours pour prendre en charge Preact, Vue et les composants Web. Docz est le plus récent des trois outils, mais il a réussi à collecter plus de 14 000 étoiles sur Github. Docz introduit deux composants - <Playground> и < 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 envelopper 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 pouvez le modifier.
<Playground>
<Button>click</Button>
</Playground><Props> affichera toutes les propriétés disponibles pour un composant React donné, les valeurs par défaut et si la propriété est obligatoire.
<Props of={Button} />Personnellement, je trouve que cette approche basée sur MDX est la plus simple à comprendre et la plus simple à utiliser.
Si vous êtes fan du générateur de site statique Gatsby, Docz propose une excellente intégration.
Guide de style
Comme Docz, les exemples sont écrits en utilisant la syntaxe Markdown. Styleguidist utilise des blocs de code Markdown (guillemets triples) dans les fichiers normaux .md fichiers, pas MDX.
```js
<Button onClick={() => console.log('clicked')>Push Me</Button>Les blocs de code dans Markdown affichent généralement simplement du code. Lors de l'utilisation de Styleguidist, tout bloc de code avec une balise de langue js, jsx ou javascript sera rendu en tant que composant React. Comme 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 actuellement en charge React et Vue.
Livre de contes
Storybook se positionne comme un « environnement de développement de composants d'interface utilisateur ». Au lieu d'écrire des exemples de composants dans des fichiers Markdown ou MDX, vous écrivez histoires à l'intérieur des fichiers Javascript. histoire documenter l’état spécifique d’un composant. Par exemple, un composant peut avoir des historiques pour un état chargé et un état désactivé (handicapé).
storiesOf('Button', module)
.add('disabled', () => (
<Button disabled>lorem ipsum</Button>
))Storybook est beaucoup plus complexe que Styleguidist et Docz. Mais en même temps, c'est l'option la plus populaire : le projet compte plus de 36 000 étoiles sur Github. Il s'agit d'un projet open source avec 657 contributeurs et personnel à 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 prochaine version, des fonctionnalités de Docz et MDX seront introduites.
# Button
Some _notes_ about your button written with **markdown syntax**.
<Story name="disabled">
<Button disabled>lorem ipsum</Button>
</Story>Les nouvelles fonctionnalités de Storybook seront déployées progressivement au cours des prochains mois et il semble que ce sera un grand pas en avant.
Les résultats de
Les avantages d'une bibliothèque de modèles sont vantés dans des millions d'articles sur Medium. Lorsqu’ils sont bien exécutés, ils facilitent la création de produits connexes et le maintien de l’identité. Bien entendu, aucun de ces outils ne créera comme par magie un système de conception. Cela nécessite une conception soignée et du CSS. Mais quand vient le temps de rendre un système de conception accessible à l’ensemble de l’entreprise, Docz, Storybook et Styleguidist sont d’excellentes options.
Du traducteur. C'est ma première expérience sur Habré. Si vous trouvez des inexactitudes ou avez des suggestions pour améliorer l'article, écrivez-moi dans un message personnel.
Source: habr.com