Cette page contient les détails d'un projet de rédaction technique accepté pour la saison des documents Google.
Résumé du projet
- Organisation Open Source:
- National Resource for Network Biology (NRNB)
- Rédacteur technique:
- Prubhtej_9
- Nom du projet:
- Créer une documentation utilisateur pour SynBioHub et développer des tutoriels pour des cas d'utilisation spécifiques
- Durée du projet:
- Durée standard (3 mois)
Project description
Extrait
La documentation utilisateur est conçue pour aider les utilisateurs finaux à utiliser un produit ou un service. Une bonne documentation utilisateur est très importante, car elle permet aux utilisateurs d'apprendre à utiliser un logiciel, ses fonctionnalités, ses conseils et ses astuces, et de résoudre les problèmes courants rencontrés lors de son utilisation. Elle réduit également les coûts de l'assistance et fait partie de l'identité de l'entreprise du produit. Autrement dit, une bonne documentation utilisateur est le signe d'un produit et d'une équipe de développeurs en bonne santé. Sans une bonne documentation utilisateur, un utilisateur peut ne pas savoir comment faire de manière efficace les choses mentionnées ci-dessus. La documentation utilisateur peut jouer un rôle central dans la réussite d'un produit, car une excellente communication est et sera toujours au cœur de toute entreprise ou tout produit et une excellente documentation ne fait qu'encadrer cette communication et la placer dans un cadre gérable auquel tout le monde peut accéder pour réussir. SynBioHub est un dépôt de conception dédié à la biologie synthétique. Il est disponible à la fois en tant que site Web public et en tant que logiciel Open Source. SynBioHub utilise le langage SBOL (Synthetic Biology Open Language), une norme Open Source pour représenter les conceptions génétiques. Il permet également de partager des éléments de conception à partir de fichiers GenBank et FASTA. SynBioHub permet de publier une bibliothèque de pièces et de conceptions synthétiques en tant que service, de partager des conceptions avec des collaborateurs et de stocker des conceptions de systèmes biologiques localement. Vous pouvez accéder aux données de SynBioHub via l'API HTTP, l'API Java ou l'API Python, puis les intégrer à des outils de CAO pour créer des conceptions génétiques. SynBioHub contient une interface permettant aux utilisateurs d'importer de nouvelles données biologiques dans la base de données, de visualiser des parties d'ADN, d'effectuer des requêtes pour accéder aux parties souhaitées et de télécharger SBOL, GenBank, FASTA, etc. Divers articles de recherche et quelques tutoriels sont également disponibles sur Internet, par exemple: 1. https://pubs.acs.org/doi/abs/10.1021/acssynbio.7b00403 2. https://pubs.acs.org/doi/abs/10.1021/acssynbio.0c00056 SynBioHub dispose d'une documentation qui ne concerne que l'API, tandis qu'aucune documentation n'est disponible pour l'IUG.
État actuel de la documentation:
Actuellement, la documentation utilisateur est disponible à l'adresse "https://synbiohub.github.io/api-docs/#about-synbiohub". Il ne s'agit que de la documentation de l'API. La documentation de l'IUG n'existe pas, ce qui peut aider l'utilisateur à naviguer dans le dépôt de conception. La documentation de l'API nécessite également quelques mises à jour, avec des sujets spécifiques tels que la résolution de problèmes particuliers auxquels un utilisateur peut être confronté. L'organisation a enregistré des tutoriels vidéo, comme celui présenté ici. Il n'existe aucune documentation écrite sur SynBioHub qui puisse guider l'utilisateur.
Pourquoi la documentation utilisateur que vous proposez est-elle une amélioration par rapport à la documentation actuelle ? Je vais créer la documentation sur l'IUG à partir de zéro à l'aide de GitHub et de Markdown, comme l'a suggéré le mentor, Chris Myers. La documentation utilisateur proposée sera structurée pour améliorer et garantir l'efficacité, la cohérence et la tranquillité d'esprit de tout utilisateur final. Il contiendra des guides écrits et les images associées, ainsi que des instructions et des explications sur l'utilisation de chaque fonctionnalité du simulateur open source SynBioHub. Lors des discussions avec M. Myers, il a également été décidé que la documentation de l'API serait fusionnée avec l'IUG et qu'elle contiendrait six sections, dont la sixième sera facultative. Les sections sont mentionnées comme suit : 1. Introduction 2. Instructions d'installation a) À partir d'une image prédéfinie b) À partir de la source c) Configuration NGINX 3. Instructions utilisateur a) Instructions détaillées sur l'utilisation de chaque fonctionnalité de l'IUG b) Tutoriels pour les cas d'utilisation courants 4. Documentation sur les API – Section 5 sur Endpoints. Documentation du plug-in 6. Dépannage et références futures
Partie 1:
Dans cette section, les utilisateurs recevront une présentation détaillée et divers tutoriels sur SynBioHub.
Part-2:
Cette section décrit les différentes méthodes que l'utilisateur peut utiliser pour installer le logiciel Open Source : a) À partir d'une image précompilée b) À partir de la source c) Configuration NGINX
Partie 3:
Il s'agit de la partie la plus importante de la documentation et qui prendra le plus de temps. Dans le présent document, chaque détail d’une minute sera ajouté en contexte à l’interface graphique. Comme indiqué ci-dessus, cette section aborde principalement deux points : des instructions détaillées sur l'utilisation de chaque fonctionnalité de l'IUG et des tutoriels pour les cas d'utilisation courants.
Part-4:
Comme indiqué ci-dessus, l'écran sera utilisé pour générer la documentation de cette partie. Cette section inclut les points de terminaison suivants : 1. Points de terminaison utilisateur 2. Rechercher des points de terminaison. 3. Points de terminaison de téléchargement 4. Téléchargez Endpoints. 5. Points de terminaison d'envoi 6. Points de terminaison des autorisations. 7. Modifier les points de terminaison 8. Points de terminaison d'attachement 9. Points de terminaison d'administration
Part-5:
Cette section comprendra la documentation du plug-in, qui est déjà présente dans l'ancienne documentation SynBioHub. Cette section sera divisée en deux sections: la spécification et l'implémentation du plug-in. Partie 6: [Facultatif] Cette section comprend une liste très courante d'erreurs rencontrées par les utilisateurs, ainsi que des instructions de dépannage. Comme indiqué lors de la discussion avec M. Myers, il a été décidé que cette section pouvait être fusionnée avec la section d'introduction, si cela ne rend pas le document trop long. AnalyseMonsieur Myers et moi avons discuté de la manière de mettre à jour la documentation existante et d'en rédiger une nouvelle pour l'IUG. Au cours de ces quelques conversations, nous avons élaboré une mise en page de base pour la nouvelle documentation, comme indiqué ci-dessus. Un calendrier estimé est indiqué sur la page 5 ci-dessous. Comme indiqué lors de la discussion, je vais utiliser GitHub et Markdown pour créer la documentation de chaque section, à l'exception de la partie 4, dans laquelle Slate sera utilisé. Slate : Slate vous aide à créer une documentation API attrayante, intelligente et responsive. Slate est un outil basé sur Ruby qui génère un site statique de documentation d'API à trois panneaux à partir d'un ensemble de fichiers Markdown. Il a été créé par le développeur Robert Lord en 2013, alors qu'il était stagiaire de 18 ans chez Tripit, une entreprise de logiciels de voyage. Il a convaincu son patron de l'époque de le laisser rendre le projet Open Source, et le reste appartient à l'histoire. Il offre les caractéristiques suivantes : • Une conception épurée et intuitive : avec la version Slate, la description de votre API se trouve à gauche de votre documentation et tous les exemples de code se trouvent à droite. Inspiré de la documentation sur les API de Stripe et de PayPal. Réactivité, l'ardoise est irréprochable sur les tablettes, les téléphones et même sur papier. • Tout sur une seule page : vos utilisateurs n'ont plus besoin de parcourir un million de pages pour trouver ce qu'ils recherchent. Slate regroupe l'intégralité de la documentation sur une seule page. Nous n'avons toutefois pas sacrifié la possibilité d'associer des éléments. Lorsque vous faites défiler la page, le hachage de votre navigateur est mis à jour avec l'en-tête le plus proche. Vous pouvez ainsi créer un lien vers un point particulier de la documentation de manière naturelle et simple. • Slate n'est que du Markdown : lorsque vous rédigez des documents avec Slate, vous n'écrivez que du Markdown, ce qui facilite la modification et la compréhension. Tout est écrit en Markdown. Même les exemples de code ne sont que des blocs de code Markdown. • Écrivez des exemples de code dans plusieurs langues : si votre API comporte des liaisons dans plusieurs langages de programmation, vous pouvez facilement ajouter des onglets pour passer de l'un à l'autre. Dans votre document, vous distinguerez les différentes langues en spécifiant le nom de la langue en haut de chaque bloc de code, comme avec le Markdown GitHub. • Mise en surbrillance de la syntaxe prête à l'emploi pour plus de 100 langues, aucune configuration requise • Une table des matières automatique à défilement fluide à l'extrême gauche de la page. Lorsque vous faites défiler le document, il affiche votre position actuelle. Il est également rapide. Chez TripIt, nous utilisons Slate pour créer de la documentation pour notre nouvelle API, dans laquelle notre table des matières contient plus de 180 entrées. Nous nous sommes assurés que les performances restent excellentes, même pour les documents volumineux. • Laissez vos utilisateurs mettre à jour votre documentation à votre place : par défaut, votre documentation générée par Slate est hébergée dans un dépôt GitHub public. Cela signifie non seulement que vous bénéficiez d'un hébergement gratuit pour vos documents avec GitHub Pages, mais aussi que d'autres développeurs peuvent facilement envoyer des requêtes pull sur vos documents s'ils détectent des fautes de frappe ou d'autres problèmes. Bien entendu, si vous ne souhaitez pas utiliser GitHub, vous pouvez également héberger vos documents ailleurs. • Compatibilité avec les langues RTL Mise en page complète de droite à gauche pour les langues RTL telles que l'arabe, le persan (farsi), l'hébreu, etc. Verdict Slate est l'un des logiciels open source les plus puissants pour générer la documentation. Conformément aux discussions avec mon mentor, M. Chris Myers, je vais utiliser Slate pour la partie 4 et pour les autres parties, GitHub et Markdown seront utilisés. Les sections ci-dessous présentent une vue plus détaillée de la documentation. Structure de la documentation proposée J'ai créé une structure pour le guide de l'utilisateur de SynBioHub, qui se trouve sur la page 2. Cette structure est acceptée et a déjà été modifiée par M. Myers . Objectifs du projet 1. Restructurez la documentation. 2. Mettez à jour la documentation pour qu'elle corresponde aux versions modernes de SynBioHub. 3. Supprimez les informations obsolètes. 4. Réécrivez la documentation utilisateur pour la rendre plus facile à comprendre. 5. Incluez une brève section sur les prérequis dans la documentation destinée aux nouveaux contributeurs afin de renforcer leur compréhension des concepts biologiques de base et de l'interface de SynBioHub.