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:
- BRL-CAD
- Rédacteur technique:
- sahibkaur
- Nom du projet:
- Guide du débutant pour BRL-CAD
- Durée du projet:
- Durée standard (trois mois)
Project description
Guide du débutant pour BRL-CAD
Aperçu du projet
Ce projet vise à créer une documentation destinée aux utilisateurs qui ne connaissent pas seulement BRL-CAD, mais aussi le logiciel Open Source.
Pourquoi ce projet
Lorsque j'ai visité le site Web de BRL-CAD pour la première fois, j'ai été submergé par la quantité d'informations disponibles. En effet, je n'avais aucune expérience de l'open source et de BRL-CAD. Mais au fond de moi, je savais qu'il y avait beaucoup à apprendre. Je voulais donc créer une documentation pour les nouveaux utilisateurs comme moi afin de tirer le meilleur parti de cette communauté et de se sentir à l'aise pour commencer.
Objectifs
Ce projet ciblera les nouveaux utilisateurs. Voici quelques points que ma documentation vise à atteindre : Mettre les nouveaux utilisateurs à l'aise: cette documentation s'adresse aux nouveaux utilisateurs de BRL-CAD, mais aussi aux nouveaux utilisateurs de logiciels Open Source.
Pour ce faire, je vais:
- Assurez-vous que le score Flesch-Kincaid du document est d'au moins 50. Selon la méthode Flesch-Kincaid, plus le score est élevé, plus le texte est facile à comprendre. Vous pouvez vérifier son score de lisibilité en ligne.
- Utilisez des listes à puces ou numérotées pour que les lecteurs ne s'ennuient pas ou ne soient pas distraits par de longs paragraphes.
- Utilisez des paragraphes et des phrases plus courts, car lire et comprendre des phrases plus longues nécessite un effort mental plus important.
- Utilisez des sous-titres pour séparer le texte. Documentation bien structurée: une documentation bien structurée joue un rôle crucial pour guider les nouveaux utilisateurs. Cela les évite de se perdre et leur permet de savoir où ils se dirigent et ce qu'ils font. Pour ce faire, j'ai créé une carte mentale approximative qui peut nous aider à documenter ce guide du débutant de manière organisée.
Description du projet
Ce projet consiste à rédiger une documentation pour permettre aux nouveaux utilisateurs de se familiariser avec ce logiciel.
Vous trouverez ci-dessous un exemple de la façon dont je compte rendre la documentation plus descriptive.
Présentation de base : BRL-CAD (prononcé "be-are-el-cad") est un logiciel de conception assistée par ordinateur (CAO) de modélisation solide de géométrie constructive des solides (CSG). Il s'agit d'un puissant système de modélisation robuste, multiplate-forme et Open Source, conçu pour la conception 3D assistée par ordinateur et la visualisation graphique. Vous n'arrivez pas à vous détourner de la tête ? Examinons cela en détail. Open Source: logiciel dont le code source peut être inspecté, modifié et amélioré par n'importe qui. Étant donné que BRL-CAD est un logiciel Open Source, nous vous invitons à contribuer à son amélioration. Conception assistée par ordinateur (CAD): en d'autres termes, la CAO consiste à utiliser des programmes informatiques pour créer une représentation graphique en deux ou trois dimensions d'objets physiques. Système de modélisation solide: le modèle BRL-CAD se concentre sur la modélisation des solides éléments CAO. La modélisation des solides se distingue des autres formes de modélisation géométrique par sa précision physique et sa description complète de l'espace 3D. Il simule un objet à la fois en interne et en externe. Géométrie constructive des solides (CSG, constructive solid geometry): la CSG permet de représenter des modèles complexes sous la forme d'une série d'opérations booléennes entre des primitives. Les objets solides les plus simples utilisés pour la représentation sont appelés primitives. Pour comprendre les principes de base de la CSG, cliquez ici.
*Comme indiqué dans la description de l'idée de projet : la documentation doit au minimum couvrir l'installation de base, une description globale des fonctionnalités, des principes de modélisation de BRL-CAD, l'utilisation de base des principaux outils, la modélisation, l'importation/l'exportation, l'analyse et le rendu.
Vous trouverez ci-dessous de brèves introductions sur la façon dont je couvrirai chaque partie de la documentation.
- Installation de base: je vais ajouter un tutoriel par étapes pour installer le logiciel BRL-CAD, ainsi que les captures d'écran requises. Le tutoriel destiné aux débutants est un bon point de départ pour les nouveaux utilisateurs. Voici quelques éléments qui me manquent:
- Les étapes de ce tutoriel pour les débutants ne sont pas numérotées ni sous forme de puces. Si vous disposez d'un tutoriel étape par étape avec une capture d'écran à la fin de chaque étape, il est plus probable que l'utilisateur soit captivé par le tutoriel.
- Une description générale des fonctionnalités: cette section contient tous les domaines dans lesquels BRL-CAD peut faire des merveilles. Une approche schématique est plus efficace pour attirer l'attention sur cette partie.
- Principes de modélisation de BRL-CAD: cette partie nécessitera plus d'explications, car l'utilisateur sera plus à même de comprendre BRL-CAD une fois qu'il aura bien compris ces principes de modélisation.
- Utilisation de base des principaux outils: nous proposerons des tutoriels distincts sur les principaux outils et leur utilisation de base. Il s'agit de tutoriels détaillés.
- Exportation/Importation: les utilisateurs découvriront la bibliothèque de conversion de géométrie. L'un des cas d'utilisation les plus courants de BRL-CAD consiste à convertir une géométrie d'un format à un autre. Dans cette section, nous allons parler des convertisseurs d'exportation et d'importation.
- Rendu: nous aborderons les bases du rendu et la nécessité de l'utiliser dans notre logiciel. Les utilisateurs apprendront également à afficher des images dans BRL-CAD.
En outre, l'accent est mis sur les points suivants:
- Le début de la documentation vous donnera une compréhension de base de ce logiciel.
- Comment les utilisateurs peuvent se connecter à cette communauté Open Source ; lien vers le chat zulip de BRL-CAD.
- Sur un plan abstrait, en rendant la documentation un peu humoristique et en demandant aux nouveaux utilisateurs de ne pas se laisser décourager par les grands mots. J'ai apprécié l'approche empathique utilisée sur la page principale du wiki BRL-CAD.
- Il contiendra des captures d'écran de certaines choses incroyables que les utilisateurs peuvent faire avec ce logiciel.
Étapes
Juillet (période d'examen des propositions)
- Je me familiariserai avec le logiciel et ses documents wiki en parcourant les tutoriels existants.
- Je vais améliorer les documents existants.
1er août au 7 août (création de liens au sein de la communauté)
- Discuter du projet avec des mentors
- Affiner les détails du projet.
- Apportez les modifications nécessaires aux jalons (si nécessaire).
8 août – 14 août
- Se familiariser avec le format XML des Docbook
15 août – 21 août
- Rédaction de la documentation pour « Basic Introduction to BRL-CAD »
- Rédaction d'un tutoriel détaillé sur l'installation de base
22 août – 27 août
- Exploration des différentes fonctionnalités de BRL-CAD et liste de celles-ci avec des captures d'écran.
- Présentez les différentes fonctionnalités sur une autre page.
28 août – 3 septembre
- Poursuivez le travail sur les documents individuels pour les fonctionnalités.
4 septembre – 10 septembre
- Travailler sur les principes de modélisation
- Expliquer tous les principes de modélisation
Du 11 au 17 septembre
- Travaillez sur l'utilisation de base des principaux outils.
- Faites une liste d'idées pour documenter l'utilisation de base de chaque outil.
18 septembre – 24 septembre
- Documenter l'utilisation de chaque outil
25 septembre – 1er octobre
- Travaillez sur la modélisation pour créer un modèle solide pour le tutoriel et rédigez un brouillon en parallèle.
2 octobre – 8 octobre
- Améliorer le brouillon de modélisation.
2 octobre – 8 octobre
- Étudier les convertisseurs en export et en importation
9 octobre - 15 octobre
- Préparez les documents d'exportation et d'importation.
- Commencez à travailler sur le rendu.
16 octobre – 22 octobre
- Documentation du tutoriel de rendu.
23 octobre – 29 octobre
- examiner tous les documents ;
30 octobre – 5 novembre
- Travailler sur le fichier XML Docbook
Du 6 au 12 novembre
- Demandez des avis à vos mentors et aux autres membres de la communauté, puis travaillez sur les modifications.
- Discuter avec des mentors et apporter les modifications finales
Du 12 au 22 novembre
- Discuter et modifier le processus
- Apportez les touches finales à la documentation.
À propos de moi
J'ai commencé à écrire à l'école. Je rentrais de l'école et je rédigeais un journal de ma journée, ce qui l'avait rendue meilleure ou pire. J'étais toujours enthousiaste à écrire les erreurs que j'avais commises et comment puis-je les améliorer.
Au cours de ma formation en tant que concepteur Web, on nous a demandé d'écrire ce que nous apprenons tous les jours. Je documenterais certains des problèmes auxquels j'ai été confronté et la solution à ceux-ci.
En tant que personne, je fais toujours de mon mieux pour aider les autres. Pendant mes jours d'école et d'université, j'expliquais certains sujets à mes amis après avoir compris ces sujets moi-même. Participer au GSoD est une excellente étape à travers laquelle je, en tant que rédacteur, contribue à rendre cette communauté Open Source plus attrayante et utile pour les nouveaux utilisateurs du monde entier.