Projet BRL-CAD

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:
BRL-CAD
Rédacteur technique:
sahibkaur
Nom du projet:
BRL-CAD : guide du débutant
Durée du projet:
Durée standard (3 mois)

Project description

BRL-CAD : guide du débutant

Extrait du projet

L'objectif de ce projet est de créer une documentation dédiée aux nouveaux utilisateurs de la devise BRL-CAD et de l'Open Source.

Pourquoi ce projet ?

Lorsque j'ai visité le site Web BRL-CAD pour la première fois, j'étais novice en matière d'Open Source et de BRL-CAD. J'ai été submergé par la quantité d'informations d'un coup. Mais au fond, je savais qu'il y avait beaucoup à apprendre ici. Je voulais donc créer de la documentation pour les nouveaux utilisateurs comme moi afin de tirer pleinement parti de cette communauté et de me sentir à l’aise pour commencer.

Buts

Ce projet ciblera les nouveaux utilisateurs. Voici quelques points à retenir dans ma documentation : Pour que les nouveaux utilisateurs se sentent à l'aise: cette documentation s'adresse aux nouveaux utilisateurs non seulement en BRL-CAD, mais aussi en Open Source.

Pour ce faire, je vais:

  • Le score Flesch-Kincaid du document doit être au moins supérieur à 50. Selon la méthode de Flesch-Kincaid, plus le score est élevé, plus l'œuvre est facile à comprendre. Vous pouvez consulter son score de lisibilité en ligne.
  • Utilisez des listes à puces ou des listes numérotées afin 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 cela nécessite relativement plus de travail mental pour lire et comprendre des phrases plus longues.
  • Utilisez des sous-titres pour séparer le texte. Une documentation bien structurée: une documentation bien structurée joue un rôle crucial pour guider les nouveaux utilisateurs. Cela les empêche de se perdre et leur permet de savoir où ils se dirigent et ce qu'ils font. Pour y parvenir, j'ai créé une carte mentale approximative qui nous aidera à documenter ce guide du débutant de façon organisée.

Description du projet

Ce projet se concentre sur la rédaction de documentation pour les nouveaux utilisateurs afin de se familiariser avec ce logiciel.

Vous trouverez ci-dessous un exemple de la façon dont j'ai l'intention de rendre la documentation plus descriptive.

Introduction de base : BRL-CAD (prononcé be-are-el-cad) est une conception assistée par ordinateur (CAD) de modélisation des solides constructifs. Il s'agit d'un puissant système de modélisation robuste, multiplate-forme et Open Source conçu pour la conception assistée par ordinateur 3D et la visualisation graphique. Vous avez du mal à comprendre ? Examinons cela en détail. Open Source: un logiciel Open Source est un logiciel avec du code source que n'importe qui peut inspecter, modifier et améliorer. Le logiciel Open Source BRL-CAD vous invite à contribuer à l'amélioration de BRL-CAD ! Conception assistée par ordinateur (CAD): en termes simples, 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 des solides: BRL-CAD se concentre sur la modélisation des solides, qui se distingue des autres formes de modélisations géométriques par l'accent mis sur la précision physique et la description complète de l'espace 3D. Il simule un objet à la fois en interne et en externe. Géométrie solide constructive (CSG): le CSG permet de représenter des modèles complexes sous la forme d'une série d'opérations booléennes entre les primitives. Les objets solides les plus simples utilisés pour la représentation sont appelés primitives. Pour découvrir les concepts fondamentaux, consultez cette page.

*Comme mentionné dans la description de l'idée de projet : La documentation couvre au minimum l'installation de base, une description globale des fonctionnalités, les principes de modélisation de BRL-CAD, l'utilisation de base des principaux outils, la modélisation, l'importation/exportation, l'analyse et le rendu.

Vous trouverez de brèves présentations sur la façon dont je vais couvrir 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-unes des choses qui me manquent:
  • Les étapes de ce tutoriel pour débutants ne sont ni énumérées ni numérotées. Avoir un tutoriel étape par étape avec une capture d’écran à la fin de chaque étape augmente la probabilité que l’utilisateur soit capté par le tutoriel.
  • Description générale des fonctionnalités: cette section contient les domaines dans lesquels la devise BRL-CAD est la plus puissante. Une approche schématique sera un meilleur moyen d'attirer l'attention sur cette partie.
  • Principes de modélisation de BRL-CAD: cette partie nécessitera davantage d'explications, car l'utilisateur pourra mieux comprendre la devise 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 pour 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 conversions géométriques. L'une des utilisations les plus courantes de BRL-CAD est de convertir des géométries d'un format à un autre. Cette section traite des convertisseurs pour l'exportation et l'importation.
  • Rendu: nous aborderons les bases de l'affichage et sa nécessité dans notre logiciel. Les utilisateurs découvriront également comment effectuer le rendu des images en BRL-CAD.

En outre, l'accent est également mis sur les points suivants:

  • Le début de la documentation a une compréhension de base de ce logiciel.
  • Comment les utilisateurs peuvent entrer en contact avec cette communauté Open Source ; lien vers le chat Zulip (BRL-CAD)
  • Sur le plan abstrait, rendre la documentation un peu humoristique et demander aux nouveaux utilisateurs de ne pas se décourager par des mots grossiers. J'ai aimé 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 en utilisant ce logiciel.

Étapes importantes

Juillet (période d'examen de la proposition)

  • Je me familiariserai avec le logiciel et ses documents wiki en parcourant les didacticiels existants.
  • J'apporterai des améliorations aux documents existants.

1er août – 7 août (association de communautés)

  • Discuter du projet avec les mentors.
  • Affiner les détails du projet.
  • Apportez les modifications requises aux jalons (si nécessaire).

8 août – 14 août

  • Familiarisez-vous avec le format XML de Docbook

15 août – 21 août

  • Rédiger la documentation "Basic Introduction to BRL-CAD"
  • Rédaction d'un tutoriel détaillé pour l'installation de base

22 août – 27 août

  • Explication des différentes fonctionnalités de BRL-CAD et de leur liste accompagnée de captures d'écran
  • Décrivez chaque fonctionnalité sur une autre page.

Du 28 août au 3 septembre

  • Continuez à travailler sur des documents individuels pour les fonctionnalités.

4 septembre – 10 septembre

  • Nous travaillons sur les principes de modélisation.
  • Expliquer tous les principes de modélisation

11 septembre – 17 septembre

  • Travailler sur l'utilisation de base d'outils majeurs.
  • Faites une liste d'idées pour documenter l'utilisation de base de chaque outil.

Du 18 au 24 septembre

  • Documenter l’utilisation de chaque outil.

25 septembre – 1er octobre

  • Travaillez sur la modélisation afin de créer un modèle solide pour le tutoriel et rédigez également un brouillon.

Du 2 au 8 octobre

  • Améliorez le brouillon de la modélisation.

Du 2 au 8 octobre

  • Étudier les convertisseurs pour l'exportation et l'importation.

9 octobre – 15 octobre

  • Préparez l'exportation et l'importation de documents.
  • Commencez à effectuer le rendu.

16 octobre – 22 octobre

  • Documenter le tutoriel de rendu

Du 23 au 29 octobre

  • Examen de toute la documentation.

30 octobre – 5 novembre

  • Travailler sur le fichier XML du Docbook

6 novembre – 12 novembre

  • Demandez l'avis des mentors et des autres membres de la communauté et travaillez sur les changements.
  • Discuter avec les mentors et apporter les derniers changements.

12 novembre – 22 novembre

  • Processus de discussion et de modification.
  • Ajout de la touche finale à la documentation.

À propos de moi

Je travaille dans l'écriture depuis l'école. Je revenais de l'école et j'écrivais tout sur ma journée : ce qui la rendait meilleure ou mauvaise. J'étais toujours soucieuse d'écrire mes erreurs et de savoir comment les améliorer.

Lors de ma formation de concepteur Web, on nous a demandé d’écrire ce que nous apprenions chaque jour. Je documentais certains des problèmes auxquels je devais faire face et la solution.

En tant que personne, je fais toujours de mon mieux pour aider les autres. À l'école et à l'université, j'expliquerais certains sujets à mes amis après avoir compris ces sujets moi-même. Participer à GSoD est une étape formidable à travers laquelle, en tant que rédacteur, je peux contribuer à rendre cette communauté Open Source plus attrayante et utile pour les nouveaux utilisateurs du monde entier.