Cette page contient les détails d'un projet de rédaction technique accepté pour la Google Season of Docs.
Résumé du projet
- Organisation Open Source:
- Creative Commons
- Rédacteur technique:
- nimishnb
- Nom du projet:
- Guide d'utilisation du vocabulaire
- Durée du projet:
- Durée standard (trois mois)
Project description
Synopsis du projet
Le vocabulaire a un potentiel immense pour être utilisé comme bibliothèque de composants d'interface utilisateur principale pour la création de sites Web. Il a besoin d'un guide pratique robuste, mais accessible aux non-professionnels. Les informations importantes pour les développeurs, telles que les guides de composants, les spécifications d'utilisation et les ajustements de configuration, constituent une partie essentielle de toute documentation. Cela permettra non seulement aux utilisateurs existants de voir comment le vocabulaire continue de croître et d'atteindre de nouveaux jalons, mais aussi de promouvoir l'utilisation de Vocabulary dans des projets plus récents. Les résultats attendus de mon stage ne consistaient pas seulement à rédiger un guide pratique sur l'utilisation des composants préexistants, mais aussi à concevoir et développer une page d'accueil (qui débouchera sur une documentation intégrée pour chacun) pour Vocabulary, Vue-Vocabulary et Fonts.
Plan du projet
Problème:la documentation est l'un des principaux facteurs qui déterminent le succès d'une bibliothèque Open Source. La question principale que les développeurs se posent lorsqu'ils choisissent une pile technologique adaptée pour créer leurs applications est la suivante : "La bibliothèque est-elle bien documentée ? Est-il bien entretenu ? Est-elle compatible avec un nombre d'utilisations et d'erreurs important ?". Ce sont exactement les questions que nous devrions nous poser lorsque nous développons cette idée de projet. Du point de vue de l'ingénierie logicielle:
Analyse des exigences:il est nécessaire d'avoir une documentation concise et consolidée pour répondre à nos besoins. Le manque de documentation nuit aux perspectives futures des applications Open Source. Il s'agit d'un élément essentiel et non négligeable. La page d'accueil qui permet d'accéder à ces documents doit être attrayante et susciter l'intérêt des utilisateurs en un instant. La documentation doit être bien organisée, ce qui permet de la parcourir facilement.
Spécifications:en fonction des exigences, des spécifications peuvent être définies. Le contenu de la documentation peut être formé à partir des données présentes sur les sites Web de centralisation des sous-titres, ainsi que de documentations bien connues, telles que sémantique-ui, scikit-learn, numpy, bootstrap, etc. Le résultat de cette tâche est la page de destination requise et les guides de documentation complets.
Voici quelques problèmes généraux liés au vocabulaire, à Vue-Vocabulary et aux polices:
Il y a une absence de documentation et, même s'il y en a, certaines parties sont éparpillées sur les sites Web Netlify. Cela n'empêche pas les utilisateurs, les développeurs ni les contributeurs externes d'utiliser notre bibliothèque.
Pour accéder à un composant spécifique et copier le code correspondant, vous devez effectuer des clics supplémentaires. Une simple recherche Google avec une requête comme "Vocabulaire de la sous-titrisation pour le composant Tabs" ne renvoie pas les informations souhaitées. Une option de recherche dans les guides de documentation améliorerait considérablement l'expérience utilisateur.
Description un peu plus détaillée des composants, décrivant les détails non évidents.
Aucune option d'exécution en direct. Différents sites, comme JSFiddle, proposent une exécution en direct, ce qui permet aux développeurs de se familiariser avec le composant sans avoir à exécuter une application complète pour voir comment il fonctionne.
La solution
Il existe plusieurs solutions. Je vais toutefois en évoquer quelques-unes ici et présenter ma solution finale dans la partie "Conclusion" :
= readthedocs est une solution bien connue pour écrire de la documentation pour les bibliothèques Open Source. Il est basé sur Sphinx, l'outil de documentation Python.
Avantages :
- Forme de génération de documentation largement acceptée, utilisée par des organisations comme Ethereum (Solidity).
- Une documentation structurée de façon optimale.
- Hébergement statique sans frais.
Inconvénients :
- Manque de contrôle absolu sur le style.
= Utilisation de SphinxNous pourrions également utiliser Sphinx en mode natif pour la partie documentation. Il offre de bonnes fonctionnalités pour tous nos besoins.
Avantages :
- L'outil Python de documentation le plus populaire.
- Il est également compatible avec les recherches de documentation.
- Le CSS par défaut peut être remplacé par un CSS personnalisé. Le HTML peut être contrôlé à l'aide de fichiers .rst.
Inconvénients :
- Cela impliquerait de coder en Python et au format de texte structuré (.rst), ce qui s'écarterait des langages de projet suggérés.
= Utilisation de thèmes JekyllLes thèmes Jekyll sont intégrés aux pages GitHub. Il existe des modèles préexistants qui peuvent être personnalisés en fonction de nos besoins.
Avantages :
- Thèmes de documentation prêts à l'emploi pour tous les besoins.
- Vous pouvez remplacer les styles et le code CSS par défaut par des styles et un code CSS personnalisés, et contrôler le code HTML.
- Récupère le CSS Primer par défaut pour créer les pages.
- Intégration facile aux pages GitHub.
Inconvénients :
- Il n'est pas toujours possible de structurer la documentation de la meilleure façon.
=Utilisation de Pages GitHub Les pages GitHub standards pour créer notre site statique (HTML, CSS, JS).
Avantages :
- Contrôle total de presque tout ce qui est en jeu.
- Une flexibilité maximale pour le choix de la mise en page, des couleurs et des styles
- Utilisation facile des composants de vocabulaire.
- Intégration facile d'extraits de code et de liens d'exécution en direct.
Inconvénients :
- Cette approche peut prendre plus de temps.
= Utilisation de Haroopad Cela fournit une autre solution Markdown.
Avantages :
- Cela impliquerait un codage minutieux.
- L'objectif serait de rédiger parfaitement la documentation.
Inconvénients :
- Manque de contrôle sur le CSS.
- La communauté peut ou non être la plus active.
- Il est possible que MDX ne soit pas compatible.
= Utilisation de MKDocs Cela fournit une autre solution Markdown.
Avantages :
- Cela impliquerait un minimum de codage (encore une fois).
- Écrire plus, coder moins
Inconvénients :
- Manque de contrôle sur le CSS.
- Il est possible que la communauté ne soit pas très active.
- Utilise Python. Vous aurez peut-être également besoin de démarrer une instance Amazon S3.
= Utilisation de VueJS + StorybookJS Cette approche est couramment utilisée dans Vocabulary et ses dépôts associés.
Avantages :
- S'en tenir aux technologies qui fonctionnent parfaitement, compte tenu de vos expériences professionnelles passées.
- Vous connaissez bien le code source.
- Aucune technologie compétente dans cet espace.
Inconvénients :
- Des options plus simples peuvent également être disponibles pour les mêmes objectifs.
En conclusion, l'approche impliquant l'approche VueJS+Storybook (HTML,CSS,JS) semble la mieux adaptée, étant donné que je la maîtrise également. Cependant, cela signifierait également que nous ne ferons pas tout notre possible pour développer cette application. Il serait également assez simple d'utiliser des composants CC-Vocabulary. Cependant, pour décider de la structure de la documentation, nous devons absolument prendre en compte la répartition du contenu entre les sous-titres dans la documentation readthedocs. Le site Web de Semantic-UI (qui utilise StoryBook) m'a impressionné, car il présente un aspect minimaliste et permet de trouver facilement ce que l'on veut en quelques clics. En plus de Semantic-UI, j'ai également examiné Material Design, Primer, Bootstrap, Carbon Design, etc. pour les utiliser comme guides de style d'interface utilisateur et systèmes de conception pour mon travail. Nous pouvons également rechercher des thèmes de documentation Jekyll prêts à l'emploi pour nous en inspirer.