projet DIPY

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:

DIPY

Rédacteur technique:

Areesha Tariq

Nom du projet:

Une restructuration générale axée sur l'utilisateur final

Durée du projet:

Durée standard (3 mois)

Project description

Je suis ingénieur logiciel et je possède une expertise en rédaction technique. J'ai plus de 4 ans d'expérience dans la création de documentation de logiciels, de guides d'utilisateur, de manuels et de descriptions de projets de haute qualité. Je vis à Islamabad, Pakistan (fuseau horaire: UTC+5). Je travaille actuellement en tant que stagiaire à l'équipe d'Outreachy, qui se poursuivra jusqu'au 18 août. J'ai participé à Google Season of Docs en tant que rédacteur technique pour l'organisation OpenELIS Global. La documentation d'origine était en français, limitée et obsolète. J'ai donc créé une documentation en anglais complète et mise à jour pour les utilisateurs finaux. J'ai été sélectionné dans Solidarité de l'organisation Perl & Raku pour la période de mai à août 2020 en tant que développeur backend d'un serveur Open Food Facts. En plus du développement back-end, l'une des principales tâches de ce stage consiste à créer de la documentation pour les modules et les fonctions au format POD. L'année dernière, j'ai commencé à travailler dans le monde de l'Open Source en participant à quelques projets Open Source, puis en participant à Google Season of Docs. Et cette année, j'ai été sélectionné pour Solidarité qui soutient la diversité dans les logiciels open source et sans frais. J'ai une solide maîtrise de Git, car mon projet d'assistance est hébergé sur GitHub, et j'apporte régulièrement des contributions à Open Food Facts et à Mozilla Fenix depuis mars. J'utilise Linux depuis plus de 3 ans et j'utilise des commandes de terminal depuis.

Les outils de documentation et les langages que j'ai utilisés sont Sphinx, Read the docs et Markdown. J'ai aimé cette idée et je veux y travailler, car j'ai une expérience pertinente et j'aimerais utiliser mes connaissances et mes compétences pour contribuer au DIPY. J'ai de l'expérience dans le domaine du traitement d'images numériques, de la vision par ordinateur et du machine learning. Cela m'aidera à mieux comprendre la neuro-imagerie et à créer des documents. J'ai une grande expérience dans le domaine médical. J'ai créé un site Web médical destiné aux médecins, patients, laboratoires, conducteurs d'ambulances. J'ai travaillé sur un autre système utilisé par les médecins, les patients, les infirmières, les assistants de laboratoire et les chercheurs. Cela m'aidera à créer une documentation qui sera plus facile à comprendre par le public.

J'ai examiné la documentation de DIPY et j'y ai noté plusieurs défauts. La documentation comporte de nombreuses lacunes que je prévois d'améliorer. État actuel de la documentation : La documentation manque d'une structure et d'une conception spécifiques La navigation peut être fastidieuse et chronophage, en particulier pour les nouveaux utilisateurs. Les utilisateurs ont du mal à obtenir des informations à partir du guide. Le contenu de la documentation doit être amélioré. En tant que nouvel utilisateur, j'ai eu du mal à accéder au guide de l'utilisateur et au guide du développeur. La documentation doit être remaniée de sorte que les informations requises par l'utilisateur soient facilement accessibles. La documentation manque de cohérence.

Je prévois de procéder comme suit:

Définir une structure et un modèle spécifiques pour la documentation Remodeler la documentation de sorte que les utilisateurs puissent facilement parcourir et trouver les informations requises Produire une feuille de route ou une liste d'éléments de travail pour impliquer la communauté dans le travail de documentation Définir des modèles pour le guide utilisateur et le guide du développeur Définir des modèles pour contribuer au guide Réécrire, restructurer et mettre à jour le guide utilisateur, le guide de développement et le guide de contribution (qui peuvent aider et aider les nouveaux utilisateurs à contribuer au projet pour qu'ils contribuent à la cohérence de la documentation

Guide de l'utilisateur:

Pour le guide de l'utilisateur, je me concentrerai sur l'utilisation d'un langage simple et clair pour aider les utilisateurs à comprendre même les systèmes les plus complexes. Évitez les jargons, les acronymes et autres informations internes qu'un nouvel utilisateur ne connaît peut-être pas afin d'améliorer l'expérience utilisateur. Je vais également me concentrer sur l'utilisation de contenu visuel, y compris des images, des captures d'écran annotées, des graphiques et des vidéos, qui montre rapidement à l'utilisateur comment fonctionne le système. Une bonne documentation nécessite une hiérarchie d'en-têtes et de sous-titres qui permet à l'utilisateur de savoir ce que chaque section lui montrera. Et cette hiérarchie doit suivre un flux logique qui aide l'utilisateur à apprendre à utiliser le système de la manière la plus utile. L'un des principaux objectifs de ce projet est de créer du contenu accessible. Tous les documents et guides respecteraient un style cohérent. Il est indispensable d'utiliser des polices cohérentes et des couleurs complémentaires sur plusieurs documents. Je vais m'assurer que les utilisateurs ont accès à davantage de ressources de l'organisation sur la façon de bien utiliser le système.

Guide du développeur:

Le guide du développeur comprend des conseils et des supports de référence détaillés pour aider les développeurs à créer des contributions au code source de DIPY. Il tente de présenter les différentes options à votre disposition, afin que vous puissiez utiliser la bonne approche, en fonction de ce que vous souhaitez accomplir. Le guide de développement doit être remodelé et restructuré. Je vais réécrire le contenu du guide du développeur. La création de dépendances, le guide de contribution, le guide de style, les conventions de codage, le guide de documentation, l'installation de l'environnement de développement, le débogage, le guide de test, ainsi que d'autres éléments connexes seront inclus et présentés facilement aux développeurs. Lorsque de nouveaux contributeurs se précipitent sur votre projet pour apporter leur première contribution Open Source, ils comptent sur les consignes pour les aider. Ainsi, les directives seraient faciles à lire, complètes et conviviales. Les guides de contribution sont des documents utiles qui expliquent comment les personnes peuvent contribuer au projet open source. La contribution au projet doit être aussi simple et transparente que possible pour les utilisateurs, par exemple : Envoyer un correctif Signaler un bug Devenir un responsable de la maintenance Discuter de l'état actuel du code Proposition de nouvelles fonctionnalités

TEMPLATE

Il s'agit de l'un des modèles que vous pouvez utiliser pour le guide de contribution. Vous pouvez le modifier, et ajouter ou supprimer des sections en fonction des exigences du document.

Contribution au DIPY

• Note de bienvenue

TOC

Code de conduite

• Nos normes
• Exemples de comportements qui contribuent à créer un environnement positif
• Exemples de comportement non autorisé de la part des participants
• Nos responsabilités
• Responsabilités des responsables du projet
• Définition du champ d'application

Champ d'application du Code de conduite

Que faut-il savoir pour vous aider ?

Si vous souhaitez contribuer à une contribution au code, notre projet utilise [insérer la liste des langages de programmation, des frameworks ou des outils utilisés par votre projet]. Si vous n'êtes pas encore prêt à contribuer au code, pas de problème. Vous pouvez également consulter les problèmes de documentation [link to the docs label or tag on your issue tracker] ou les problèmes de conception que nous avons [lien vers le libellé de conception ou le tag dans l'outil de suivi des problèmes si votre projet suit les problèmes de conception]. Si vous souhaitez contribuer au code et en savoir plus sur les technologies que nous utilisons, consultez la liste ci-dessous. Incluez une liste à puces de ressources (tutoriels, vidéos, livres) que les nouveaux contributeurs peuvent utiliser pour découvrir ce que les utilisateurs doivent savoir pour contribuer au projet.

Configurer l'environnement de développement

Dans cette section, je vais ajouter la procédure et les dépendances à installer. Installez $project en exécutant: install project

• Code source: github.com/$project/$project
• Issue Tracker: github.com/$project/$project/issues

Comment contribuer

Signaler un bug

• Avant d'envoyer un rapport de bug
• Comment envoyer un rapport de bug (satisfaisant) ?

Envoyer des modifications

• Protocoles de demande d'extraction
• Réponse de l'équipe
• Réactivité

Demander une amélioration

• Avant d'envoyer une suggestion d'amélioration
• Comment soumettre une suggestion d'amélioration (bonne) ?

Votre première contribution au code

• Problèmes pour débutants
• Demandes d'assistance #### Demande d'extraction
• Processus de création de la demande d'extraction
• Vérifiez que toutes les vérifications de l'état réussissent.

Que se passe-t-il si les vérifications de l'état échouent ?

• Écriture des tests
• Couverture du test

Guides de style

• Messages de commit Git
• Style Standard

Assistance

N'hésitez pas à nous contacter si vous rencontrez des problèmes. Si vous avez besoin d'aide, vous pouvez poser vos questions sur notre liste de diffusion disponible à l'adresse suivante: [e-mail], chat IRC ou [lister toutes les autres plateformes de communication utilisées par votre projet].

Licence

Cette section décrit la licence du projet.

Engagement en temps et communication:

Je vous accorderai plus de 45 heures par semaine, mais en cas d'incident, je compenserai ces heures le week-end. Pendant la période de liaison avec la communauté, je discuterai des moyens de communication et finaliserai les réunions hebdomadaires, les moyens et le temps nécessaires pour ces réunions avec mon mentor. Je tiendrai mon mentor au courant de mon travail ; je partagerai les détails de mon travail par e-mail à mon mentor. Je préférerais utiliser TeamViewer pour communiquer, car elle est facile à utiliser et offre de nombreuses fonctionnalités comme le partage d'écran, etc.