Cette page a été traduite par l'API Cloud Translation.

Projet NRNB (National Resource for Network Biology)

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:: National Resource for Network Biology (NRNB)
Rédacteur technique:: Prubhtej_9
Nom du projet:: Créer de la 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

Abstraite

Une documentation utilisateur est conçue pour aider les utilisateurs finaux à utiliser un produit ou un service. Une documentation utilisateur de qualité est très importante, car elle permet aux utilisateurs d'apprendre à utiliser un logiciel, ses fonctionnalités, d'obtenir des conseils et des astuces, mais aussi de résoudre les problèmes courants rencontrés lors de l'utilisation du logiciel. Cela permet également de réduire les coûts d'assistance et fait partie de l'identité d'entreprise du produit. En d'autres termes, une bonne documentation utilisateur est le signe d'un produit sain et de la qualité de l'équipe de développeurs. Sans une documentation utilisateur de qualité, un utilisateur peut ne pas savoir comment effectuer les tâches mentionnées ci-dessus de manière efficace. Les documentations utilisateur peuvent jouer un rôle essentiel dans le succès d'un produit, car une excellente communication est et sera toujours au cœur de toute entreprise ou tout produit et une excellente documentation prend simplement cette communication et la place dans un cadre gérable auquel tout le monde peut accéder pour réussir. SynBioHub est un dépôt de conception pour la biologie synthétique. Il est disponible à la fois sous forme de site Web public et de logiciel open source. SynBioHub utilise SBOL (Synthetic Biology Open Language), une norme Open Source permettant de représenter les conceptions génétiques, et permet également de partager des parties de la conception à partir des fichiers GenBank et FASTA. SynBioHub peut être utilisé pour publier une bibliothèque de pièces et de conceptions synthétiques en tant que service, pour partager des conceptions avec des collaborateurs et pour stocker des conceptions de systèmes biologiques localement. Les données stockées dans SynBioHub sont accessibles via l'API HTTP, l'API Java ou l'API Python, où elles peuvent ensuite être intégrées aux outils de CAO pour créer des conceptions génétiques. L'interface SynbBioHub permet 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. Différents articles de recherche et quelques tutoriels sont également disponibles sur Internet : 1. https://pubs.acs.org/doi/abs.

État actuel de la documentation:

Actuellement, la documentation utilisateur est disponible à l'adresse suivante : "https://synbiohub.github.io/api-docs/#about-synbiohub". Il ne s'agit que de la documentation sur l'API, et celle sur l'IUG n'existe pas, ce qui peut aider l'utilisateur à naviguer dans le référentiel de conception. La documentation de l'API a également besoin d'être mise à jour, avec des sujets spécifiques tels que la résolution de certains problèmes particuliers auxquels un utilisateur peut être confronté. L'organisation a enregistré quelques tutoriels vidéo, comme celui présenté ici. Il n'existe en réalité aucune documentation utilisateur écrite sur SynBioHub qui puisse guider l'utilisateur.

Pourquoi la documentation utilisateur proposée est-elle une amélioration par rapport à la documentation actuelle ? Je vais créer la documentation sur l'interface graphique à partir de zéro en utilisant GitHub et Markdown, comme suggéré par le mentor, M. Chris Myers. La documentation utilisateur proposée sera structurée de manière à améliorer et à garantir l'efficacité, la cohérence et la tranquillité d'esprit de tous les utilisateurs finaux. 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 contiendra 6 sections, dont la 6 sera facultative. Les sections sont présentées comme suit : 1. Introduction 2. Instructions d'installation a) À partir de l'image prédéfinie b) À partir de la source c) Configuration NGINX 3. Instructions utilisateur a) Des instructions détaillées sur la façon d'utiliser chaque fonctionnalité de l'IUG b) Tutoriels pour les cas d'utilisation courants 4. Documentation sur les API : section 5 des points de terminaison. Documentation sur les plug-ins 6. Dépannage et références futures

Partie 1:

Cette section fournit aux utilisateurs une présentation détaillée et divers tutoriels concernant SynBioHub.

Partie 2:

Dans cette section, les différentes manières dont l'utilisateur peut installer le logiciel Open Source à l'aide de différentes méthodes, à savoir : a) À partir d'une image prédéfinie b) À partir de la source c) Configuration NGINX

Partie 3:

Il s’agit de la partie la plus cruciale de la documentation et cela prendra la plupart du temps. Dans cet article, chaque détail sera ajouté en contexte à l’interface graphique. Comme mentionné ci-dessus, cette section traite principalement de deux préoccupations, à savoir des instructions détaillées sur l'utilisation de chaque fonctionnalité de l'IUG et des tutoriels pour les cas d'utilisation courants.

Partie 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. Points de terminaison de recherche 3. Téléchargez Cloud Endpoints. 4. Téléchargez Cloud Endpoints. 5. Points de terminaison d'envoi 6. Points de terminaison d'autorisation. 7. Modifiez les points de terminaison. 8. Points de terminaison des rattachements 9. Points de terminaison d'administration

Partie 5:

Cette section inclut la documentation sur le plug-in, qui figure déjà dans l'ancienne documentation SynBioHub. Cette section est divisée en deux sections : "Spécification du plug-in" et "Implémentation". Partie 6: [Facultatif] Cette section comprend une liste d'erreurs très fréquentes rencontrées par les utilisateurs et contient également des instructions de dépannage. Après avoir discuté avec M. Myers, il a été décidé que cette section pouvait être fusionnée avec la section "Introduction", si elle ne dure pas trop longtemps. Analyse M. Myers et moi avons discuté de la manière de mettre à jour la documentation existante et de rédiger une nouvelle documentation pour l'IUG . Dans ces quelques conversations, nous avons formulé une mise en page de base pour la nouvelle documentation mentionnée ci-dessus et un calendrier d'estimation a été donné à la page 5 ci-dessous. Comme indiqué lors de notre discussion, j'utiliserai GitHub et Markdown pour créer la documentation pour chaque section, à l'exception de la partie 4 de la documentation dans laquelle l'écran sera utilisé. "Slate" : cette fonctionnalité vous aide à créer une documentation d'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é conçu par le développeur Robert Lord en 2013, alors qu'il était stagiaire de 18 ans dans l'entreprise de logiciels de voyage "Tripit". Il a convaincu son patron de l'époque de le laisser en Open Source, et le reste est de l'histoire. Elle offre les fonctionnalités suivantes: • Conception épurée et intuitive – Avec Slate, la description de votre API se trouve à gauche de la documentation, et tous les exemples de code se trouvent à droite. Inspiré des documents sur l'API de Stripe et de PayPal. L'écran est responsif : il offre un rendu optimal sur tablette, sur téléphone et même sur papier. • Une seule et même page : Fini le temps où les utilisateurs devaient parcourir un million de pages pour trouver ce qu'ils voulaient. Slate place toute la documentation sur une seule page. Toutefois, nous n'avons pas sacrifié l'association. Lorsque vous faites défiler la page, le hachage du navigateur est mis à jour vers l'en-tête le plus proche, de sorte que la liaison vers un point précis de la documentation reste naturelle et facile. • Slate est juste au format Markdown : lorsque vous écrivez des documents avec Slate, vous n'écrivez qu'au format Markdown, ce qui le rend facile à modifier et à comprendre. Tout est écrit en Markdown, même les exemples de code ne sont que des blocs de code Markdown. • Rédigez des exemples de code dans plusieurs langages : si votre API comporte des liaisons dans plusieurs langages de programmation, vous pouvez facilement placer des onglets dans des onglets pour passer de l'un à l'autre. Dans votre document, vous distinguerez les différents langages en spécifiant leur nom en haut de chaque bloc de code, comme pour GitHub Flavored Markdown. • Mise en surbrillance de la syntaxe prête à l'emploi pour plus de 100 langues ; aucune configuration requise. • Table des matières à défilement automatique, située à l'extrême gauche de la page. Lorsque vous faites défiler l'écran, votre position actuelle dans le document s'affiche. Il est aussi rapide. Chez TripIt, nous utilisons Slate pour créer la documentation de notre nouvelle API, dont notre table des matières comporte plus de 180 entrées. Nous avons fait en sorte que les performances restent excellentes, même pour les documents volumineux. • Autorisez vos utilisateurs à mettre à jour votre documentation : par défaut, la documentation générée par Slate est hébergée dans un dépôt GitHub public. Non seulement cela signifie que vous bénéficiez d'un hébergement gratuit pour vos documents avec des pages GitHub, mais cela permet également aux autres développeurs d'effectuer facilement des demandes d'extraction sur vos documents s'ils détectent des fautes de frappe ou d'autres problèmes. Bien sûr, si vous ne souhaitez pas utiliser GitHub, vous pouvez également héberger vos documents ailleurs. • Mise en page de droite à gauche complète pour les langues se lisant de droite à gauche, 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. D'après les discussions avec mon mentor, M. Chris Myers, j'utiliserai l'écran pour la partie 4. Pour les autres parties, nous utiliserons GitHub et Markdown. Une vue plus détaillée de la documentation est présentée dans les sections ci-dessous. Structure de la documentation proposée : J'ai créé une structure pour le guide de l'utilisateur SynBioHub disponible à la page 2. Cette structure est acceptée et a déjà été modifiée par M. Myers . Objectifs du projet 1. Restructurer la documentation. 2. Mettez à jour la documentation pour l'adapter aux versions modernes de SynBioHub. 3. Supprimez les informations obsolètes. 4. Réécrire la documentation utilisateur pour qu'elle soit plus facile à comprendre. 5. Inclure une courte section préalable à la documentation à l'intention des nouveaux contributeurs afin de les aider à mieux comprendre les concepts biologiques de base et l'interface de SynBioHub.