Cette page contient les détails d'un projet de rédaction technique accepté pour 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 (3 mois)
Project description
Synopsis du projet
Vocabulary a un potentiel immense et peut être utilisé comme bibliothèque principale de composants d'interface utilisateur pour la création de sites Web. Ce qu'il faut, c'est un guide pratique à la fois solide et convivial. Des informations importantes pour les développeurs, telles que les guides des composants, les spécifications d'utilisation et les modifications de configuration, constituent une partie essentielle de toute documentation. Cela incitera non seulement les utilisateurs existants à se faire une idée de la façon dont le vocabulaire continue de croître et d'atteindre de nouveaux jalons, mais aussi de promouvoir l'utilisation de Vocabulaire dans des projets relativement récents. Les résultats souhaités de mon stage en tant que stagiaire impliquerait non seulement de rédiger un guide simple sur l'utilisation des composants préexistants, mais aussi de concevoir et développer une page d'accueil (conduisant à une documentation intégrée pour chacun) pour le vocabulaire, la vue-Vocabulaire et les polices.
Plan du projet
Le problème:la documentation est l'une des raisons principales qui déterminent le succès d'une bibliothèque Open Source donnée. Lorsque les développeurs choisissent une pile technologique adaptée pour créer leurs applications, la principale question qui se pose est la suivante : "La bibliothèque est-elle bien documentée ? Est-il bien entretenu ? A-t-elle une assistance importante en termes d'utilisation et d'erreurs ? ». Ce sont exactement les questions que nous devons nous poser lorsque nous abordons cette idée de projet. Du point de vue de l'ingénierie logicielle:
Analyse des exigences: Il est impératif de disposer d'une documentation concise et consolidée pour répondre à nos besoins. Le manque de documentation nuit aux perspectives futures des applications Open Source et constitue de loin un composant essentiel et non négligeable. Les liens vers ces documentations doivent être une page d'accueil attrayante, qui capte l'intérêt des utilisateurs en un instant. La documentation doit être bien organisée, permettant ainsi un flux fluide.
Spécifications:des spécifications peuvent être définies en fonction des exigences. Le contenu de la documentation peut être constitué à partir des données présentes sur les sites Web CC réseau et de quelques sources d'inspiration de documentations bien connues telles que semantic-ui, scikit-learn, Numpy, bootstrap, etc. Le résultat de cette tâche correspondra à la page de destination requise et aux guides de documentation complets.
Voici quelques problèmes d'ordre général liés au vocabulaire, au vocabulaire Vue et aux polices actuellement:
La documentation est manquante et, même s'il y en a une, certaines parties de ces informations sont disséminées sur les sites Web de réseau étendu. Cela ne permet pas aux utilisateurs, aux développeurs ni aux contributeurs externes d'utiliser notre bibliothèque.
Pour accéder à un composant spécifique et copier le code correspondant, il faut des clics supplémentaires. Une simple recherche Google du type "composant d'onglets CC Vocabulaire" ne renvoie pas l'information souhaitée. 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, avec des détails peu évidents.
Aucune option de diffusion en direct. Une exécution en ligne est prise en charge par différents sites, tels que JSFiddle, qui permet aux développeurs de se faire une idée du composant sans exécuter l'intégralité d'une application pour le voir fonctionner.
La solution
Plusieurs solutions sont possibles. Cependant, j'en vais quelques-uns ici et je vous présenterai ma solution finale dans la partie de conclusion :
= Utiliser readthedocs readthedocs est une solution bien connue pour écrire de la documentation sur les bibliothèques Open Source. Il est basé sur Sphinx, l'outil de documentation de Python.
Avantages :
- Forme largement acceptée de génération de documentation, utilisée par des organisations comme Ethereum (Solidity).
- Une documentation structurée de façon optimale.
- Hébergement statique sans frais
Inconvénients :
- Absence de contrôle absolu sur le style
= Utilisation de Sphinx Nous avons pu utiliser sphinx de façon native pour la partie documentation aussi, ce qui nous permet d'offrir des fonctionnalités intéressantes pour toutes nos utilisations.
Avantages :
- L'outil Python le plus populaire pour la documentation.
- Prise en charge des recherches de documentation.
- Le CSS par défaut peut être remplacé par un CSS personnalisé et contrôle le HTML à l'aide de fichiers .rst.
Inconvénients :
- Impliquerait le codage en Python et le format de texte restructuré (.rst), ce qui constitue un écart par rapport aux langages de projet suggérés.
= Utilisation des thèmes Jekyll Les thèmes Jekyll sont intégrés aux pages GitHub et il existe des modèles prédéfinis qui peuvent être personnalisés en fonction de nos besoins.
Avantages :
- Des thèmes de documentation prêts à l'emploi pour toutes les utilisations
- Les styles CSS et les styles par défaut peuvent être remplacés par des styles personnalisés. Vous pouvez également contrôler le code HTML.
- Permet d'extraire le CSS Primer par défaut pour la création des pages.
- Intégration facile aux pages GitHub.
Inconvénients :
- Peut ne pas fournir la meilleure structure de documentation.
=Utiliser les pages GitHub Pages GitHub standards utilisées pour créer notre site statique (HTML, CSS, JS).
Avantages :
- Vous avez un contrôle total sur pratiquement tout ce qui est en question.
- Bénéficiez d'une flexibilité maximale pour choisir la mise en page, les couleurs et les styles.
- Utilisation facile des composants Vocabulary.
- Intégration facile d'extraits de code et de liens d'exécution en direct.
Inconvénients :
- Cette approche peut prendre plus de temps.
= Utiliser Haroopad Cela donne une autre solution Markdown.
Avantages :
- nécessiterait un codage minimal.
- Nous nous concentrerons sur la rédaction parfaite des documentations.
Inconvénients :
- Manque de contrôle sur les CSS.
- Peut ou non bénéficier de la meilleure assistance de la communauté.
- Peut ne pas être compatible avec MDX.
= Utiliser MKDocs Vous disposez ainsi d'une autre solution Markdown.
Avantages :
- nécessiterait (encore une fois) un codage délicat.
- « Plus de code, moins de code ».
Inconvénients :
- Manque de contrôle sur les CSS.
- Peut ne pas bénéficier de la meilleure assistance de la communauté.
- Utilise Python. Vous aurez peut-être également besoin de démarrer une instance Amazon S3.
= Utiliser VueJS +StorybookJS Cette approche est couramment utilisée dans Vocabulary et ses dépôts associés.
Avantages :
- S'en tenir à des technologies qui sont sûres de fonctionner parfaitement, compte tenu des expériences professionnelles passées.
- Vous maîtrisez le code base.
- Aucune technologie compétente dans ce domaine.
Inconvénients :
- Des options plus simples peuvent également être proposées aux mêmes fins.
En conclusion, je pense que l'approche utilisant la méthode VueJS+Storybook (HTML,CSS,JS) semble être la plus adaptée, étant donné que cette approche me convient également. Toutefois, 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-Vocabulaire. Toutefois, pour décider de la structure de la documentation, nous devons absolument prendre en compte la manière dont le contenu est réparti entre les sous-titres de la documentation readthedocs. J'ai été impressionné par le site Web de l'UI sémantique (qui utilise StoryBook) car son aspect minimaliste permet de savoir facilement ce qu'il veut en quelques clics. Outre Semantic-UI, j'ai aussi étudié Material Design, Primer, Bootstrap, Carbon Design, etc. pour les utiliser comme guides de style d'UI et systèmes de conception pour mon travail. Nous pouvons également trouver des idées de thèmes Jekyll prêts à l'emploi dans la documentation.