projet DIPY

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:

DIPY

Rédacteur technique:

Areesha Tariq

Nom du projet:

Restructuration de haut niveau et orientation client

Durée du projet:

Durée standard (trois mois)

Project description

Je suis ingénieur logiciel et je possède une expertise en rédaction technique. J'ai plus de quatre ans d'expérience dans la rédaction de documentations logicielles, de guides utilisateur, de manuels et de descriptions de projets de haute qualité. Je vis à Islamabad, au Pakistan (fuseau horaire: UTC+5). Je travaille actuellement en tant que stagiaire chez Outreachy, qui continuera jusqu'au 18 août. J'ai participé à la Google Season of Docs en tant que rédactrice 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 complète et à jour pour les utilisateurs finaux en anglais. J'ai été sélectionné dans Outreachy pour l'organisation Perl &Raku pour la phase de mai à août 2020 en tant que développeur backend pour le serveur Open Food Facts. En plus du développement backend, l'une des tâches principales de cet stage consiste à créer de la documentation pour les modules et les fonctions au format POD. J'ai découvert l'univers Open Source l'année dernière lorsque j'ai contribué à quelques projets Open Source et participé à la Google Season of Docs. Cette année, j'ai été sélectionné dans Outreachy pour la diversité dans les logiciels Open Source et sans frais. Je maîtrise bien Git, car mon projet Outreachy est hébergé sur GitHub. Je contribue régulièrement à Open Food Facts et à Mozilla Fenix depuis mars. J'utilise Linux depuis plus de trois ans et j'utilise des commandes de terminal depuis.

Les outils et langages de documentation que j'ai utilisés sont Sphinx, Read the docs et Markdown. J'ai aimé cette idée et je souhaite travailler dessus, car j'ai de l'expérience dans ce domaine et j'aimerais mettre à profit mes connaissances et mes compétences pour contribuer à DIPY. J'ai de l'expérience dans les domaines du traitement d'images numériques, de la vision par ordinateur et du machine learning. Cela m'aidera à mieux comprendre la neuroimagerie et à créer de la documentation. J'ai une vaste expérience dans le domaine médical. J'ai développé un site Web médical pour les médecins, les patients, les laboratoires et les ambulanciers. 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 plus facile à comprendre pour le public.

J'ai parcouru la documentation de DIPY et y avons noté plusieurs défauts. La documentation présente plusieurs failles que je prévois d'améliorer. État actuel de la documentation : La documentation manque de structure et de conception spécifiques La navigation peut être fastidieuse et prendre du temps, en particulier pour les nouveaux utilisateurs Les utilisateurs peuvent avoir du mal à obtenir des informations dans le 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 restructurée de manière à ce 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 la parcourir et trouver les informations requises Produire une feuille de route ou une liste d'éléments de travail pour faire participer la communauté à d'autres travaux de documentation Définir des modèles pour le guide de l'utilisateur et le guide du développeur Définir des modèles pour contribuer au guide Réécrire, restructurer et mettre à jour le guide de l'utilisateur, le guide de développement et le guide de contribution (qui peuvent aider et motiver les nouveaux utilisateurs à contribuer au projet) Améliorer la cohérence de la documentation pour les images non textuelles

Guide de l'utilisateur :

Pour le guide de l'utilisateur, je me concentrerais sur l'utilisation d'un langage simple et clair pour aider les utilisateurs à comprendre même les systèmes les plus complexes. Pour une meilleure expérience utilisateur, évitez d'utiliser du jargon, des acronymes et d'autres informations internes qu'un nouvel utilisateur ne connaîtrait peut-être pas. Je me concentrerai également sur l'utilisation de contenus visuels, y compris les images, les captures d'écran annotées, les graphiques et les vidéos, qui permettent de comprendre rapidement le fonctionnement du système. Une bonne documentation nécessite une hiérarchie d'en-têtes et de sous-en-têtes qui permet à l'utilisateur de savoir ce que chaque section lui montrera. 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 des contenus accessibles. Tous les documents et guides doivent respecter un style cohérent. Il est essentiel d'utiliser des polices et des couleurs cohérentes dans plusieurs documents. Je vais m'assurer que les utilisateurs ont accès à davantage de ressources de l'entreprise pour savoir comment réussir avec le système.

Guide du développeur:

Le guide du développeur comprend de nombreux conseils et supports de référence pour aider le développeur à créer des contributions au code source de DIPY. Il tente de présenter les différentes options qui s'offrent à vous 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. Les dépendances de compilation, 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 et les éléments associés seront inclus et facilement accessibles aux développeurs. Lorsque de nouveaux contributeurs enthousiastes se précipitent sur votre projet pour apporter leur première contribution Open Source, ils se fient aux consignes de contribution pour s'orienter. Les consignes seront ainsi faciles à lire, complètes et conviviales. Les guides de contribution sont des documents utiles qui expliquent comment contribuer au projet Open Source. Les utilisateurs doivent pouvoir contribuer au projet aussi facilement et aussi clairement que possible, que ce soit pour : Envoyer un correctif Signaler un bug Devenir un mainteneur Discuter de l'état actuel du code Proposer de nouvelles fonctionnalités

TEMPLATE

Il s'agit de l'un des modèles que vous pouvez utiliser pour le guide de contribution. Il peut être modifié, et des sections peuvent être ajoutées ou supprimées en fonction des exigences du document.

Contribution à DIPY

• Message de bienvenue

TOC

Code de conduite

• Nos normes
• Exemples de comportements qui contribuent à créer un environnement positif
• Exemples de comportements inacceptables de la part des participants
• Nos responsabilités
• Responsabilités des responsables de projet
• Portée

Champ d'application du code de conduite

Que dois-je savoir pour vous aider ?

Si vous souhaitez contribuer en fournissant du code, notre projet utilise [insérer la liste des langages de programmation, frameworks ou outils utilisés par votre projet]. Si vous ne vous sentez pas encore prêt à contribuer au code, ce n'est pas un 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 rencontrons [link to design label or tag on issue tracker if your project tracks design issues]. 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 savoir 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 d'installation et les dépendances à installer. Installer $project en exécutant: install project

• Code source: github.com/$project/$project
• Outil de suivi des problèmes: github.com/$project/$project/issues

Comment participer

Signaler un bug

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

Envoyer des modifications

• Protocoles de requêtes d'extraction
• Réponse de l'équipe
• Rapidité de la réponse

Demander une amélioration

• Avant d'envoyer une suggestion d'amélioration
• How Do I Submit A (Good) Enhancement Suggestion?

Votre première contribution de code

• Problèmes pour les débutants
• Assistance demandée en cas de problèmes #### Demande d'extraction
• Processus de création d'une demande d'extraction
• Vérifiez que toutes les vérifications d'état réussissent.

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

• Écrire des tests
• Couverture des tests

Guides de style

• Messages de commit Git
• Style Standard

Assistance

Si vous rencontrez des problèmes, n'hésitez pas à nous en faire part. Si vous avez besoin d'aide, vous pouvez poser vos questions sur notre liste de diffusion à l'adresse suivante: [e-mail], IRC chat ou [indiquez toute autre plate-forme de communication utilisée par votre projet].

Licence

Cette section décrit la licence du projet.

Engagement de temps et communication:

Je travaillerai plus de 45 heures par semaine, mais en cas de problème, je compenserai ces heures le week-end. Pendant la période de consolidation de la communauté, je discuterai des moyens de communication et je finaliserai les réunions hebdomadaires, les moyens et les horaires avec mon mentor. Je tiendrai mon mentor informé de mon travail et lui enverrai les détails par e-mail. Je préfère utiliser TeamViewer pour communiquer, car il est facile à utiliser avec de nombreuses fonctionnalités comme le partage d'écrans, etc.