BRL-CAD-Projekt

Auf dieser Seite finden Sie die Details zu einem Projekt für technisches Schreiben, das für Google Season of Docs angenommen wurde.

Projektzusammenfassung

Open-Source-Organisation:
BRL-CAD
Technischer Redakteur:
sahibkaur
Projektname:
Ein Leitfaden für Einsteiger in BRL-CAD
Projektlänge:
Standardlänge (3 Monate)

Projektbeschreibung

Erste Schritte mit BRL-CAD

Projektzusammenfassung

Dieses Projekt zielt darauf ab, eine Dokumentation für Nutzer zu erstellen, die nicht nur neu bei BRL-CAD, sondern auch neu bei Open Source sind.

Warum dieses Projekt

Als ich die Website von BRL-CAD zum ersten Mal besucht habe, war ich von Open-Source- und BRL-CAD-Neulingen überwältigt. Ich war überwältigt von der Menge an Informationen auf einmal. Aber im Grunde wusste ich, dass es hier viel zu lernen gibt. Deshalb wollte ich eine Dokumentation für neue Nutzer wie mich erstellen, damit sie diese Community optimal nutzen und sich beim Einstieg wohlfühlen können.

Ziele

Dieses Projekt richtet sich an neue Nutzer. Im Folgenden finden Sie einige Punkte, die ich mit dieser Dokumentation erreichen möchte: Neuen Nutzern den Einstieg erleichtern: Diese Dokumentation richtet sich an neue Nutzer, die nicht nur mit BRL-CAD, sondern auch mit Open-Source-Software noch nicht vertraut sind.

Um dies zu erreichen, werde ich:

  • Achten Sie darauf, dass die Flesch-Kincaid-Bewertung des Dokuments mindestens 50 beträgt. Nach der Flesch-Kincaid-Methode gilt: Je höher der Wert, desto leichter ist das Stück verständlich. Sie können den Wert für die Lesbarkeit online prüfen.
  • Verwenden Sie Aufzählungs- oder nummerierte Listen, damit sich die Leser nicht langweilen oder durch lange Absätze ablenken lassen.
  • Verwenden Sie kürzere Absätze und Sätze, da das Lesen und Verstehen längerer Sätze vergleichsweise mehr geistige Arbeit erfordert.
  • Verwenden Sie Zwischenüberschriften, um den Text aufzuteilen. Eine gut strukturierte Dokumentation: Eine gut strukturierte Dokumentation spielt eine entscheidende Rolle bei der Anleitung neuer Nutzer. So können sie sich nicht verlaufen und wissen, wohin sie gehen und was sie tun. Dazu habe ich eine grobe Mindmap erstellt, die uns dabei helfen kann, diesen Leitfaden für Anfänger auf strukturierte Weise zu dokumentieren.

Projektbeschreibung

Bei diesem Projekt geht es darum, eine Dokumentation für neue Nutzer zu erstellen, damit sie diese Software ausprobieren können.

Unten finden Sie ein Beispiel dafür, wie ich die Dokumentation aussagekräftiger gestalten möchte.

Grundlegende Einführung: BRL-CAD (ausgesprochen „be-are-el-cad“) ist ein computergestütztes Design (CAD) für die solide Modellierung mit konstruktiver Körpergeometrie (CSG). Es ist ein leistungsstarkes, plattformübergreifendes Open-Source-Solid-Modelling-System für die computergestützte 3D-Designentwicklung und grafische Visualisierung. Dir fällt es nicht leicht? Keine Sorge, wir erklären dir, was das ist. Open Source: Open-Source-Software ist Software mit Quellcode, den jeder prüfen, ändern und erweitern kann. Da BRL-CAD eine Open-Source-Software ist, sind Beiträge willkommen, um BRL-CAD noch besser zu machen. Computergestütztes Design (CAD): Mit einfachen Worten bezeichnet CAD die Nutzung von Computerprogrammen zur Erstellung einer zwei- oder dreidimensionalen grafischen Darstellung physischer Objekte. Solides Modelling-System: BRL-CAD konzentriert sich auf die Solid-Modellierung von CAD. Diese Modellierung unterscheidet sich von anderen Formen der geometrischen Modellierung dadurch, dass sie physisch genau ist und den 3D-Raum vollständig beschreibt. Sie simuliert ein Objekt sowohl intern als auch extern. Constructive Solid Geometry (CSG): Mit CSG können komplexe Modelle als Reihe von booleschen Operationen zwischen Primitiven dargestellt werden. Die einfachsten festen Objekte, die für die Darstellung verwendet werden, werden als Primitive bezeichnet. Hier finden Sie grundlegende Informationen zu CSG.

*Wie in der Beschreibung der Projektidee erwähnt: Die Dokumentation deckt mindestens die grundlegende Installation, eine allgemeine Beschreibung der Funktionen, der Modellierungsprinzipien von BRL-CAD, die grundlegende Verwendung der wichtigsten Tools, die Modellierung, den Import/Export, die Analyse und das Rendering ab.

Es folgen kurze Einführungen dazu, wie ich die einzelnen Teile in der Dokumentation behandeln werde.

  • Grundlegende Installation: Ich werde eine detaillierte Anleitung zur Installation der BRL-CAD-Software mit den erforderlichen Screenshots hinzufügen. Das Tutorial für Neueinsteiger ist ein guter Ausgangspunkt für neue Nutzer. Folgende Dinge fehlen mir:
  • Die Schritte in dieser Anleitung für Anfänger sind nicht durch Aufzählungspunkte oder Nummern gekennzeichnet. Eine Schritt-für-Schritt-Anleitung mit einem Screenshot am Ende jedes Schritts erhöht die Wahrscheinlichkeit, dass Nutzer das Tutorial interessant finden.
  • Eine allgemeine Beschreibung der Funktionen: Dieser Abschnitt enthält alle Bereiche, in denen BRL-CAD seine Stärken ausspielen kann. Ein diagrammatischer Ansatz ist besser geeignet, um die Aufmerksamkeit auf diesen Teil zu lenken.
  • Die Modellierungsprinzipien von BRL-CAD: Dieser Teil erfordert weitere Erläuterungen, da der Nutzer BRL-CAD besser verstehen kann, wenn er diese Modellierungsprinzipien gut kennt.
  • Grundlegende Nutzung der wichtigsten Tools: Hier finden Sie separate Anleitungen zu den wichtigsten Tools und ihrer grundlegenden Verwendung. Dabei handelt es sich um detaillierte Anleitungen.
  • Exportieren/Importieren: Nutzer erfahren mehr über die Geometry Conversion Library. BRL-CAD wird sehr häufig zum Konvertieren von Geometrie von einem Format in ein anderes verwendet. In diesem Abschnitt werden Export- und Importkonverter beschrieben.
  • Rendering: Wir besprechen die Grundlagen des Renderings und die Notwendigkeit in unserer Software. Die Nutzer lernen auch, wie Bilder in BRL-CAD gerendert werden.

Außerdem liegt der Fokus auf den folgenden Punkten:

  • Zu Beginn der Dokumentation wird ein grundlegendes Verständnis davon vermittelt, worum es bei dieser Software geht.
  • Informationen dazu, wie Nutzer mit dieser Open-Source-Community in Kontakt treten können; Link zum BRL-CAD-Zulip-Chat.
  • Auf abstrakte Ebene, die Dokumentation ein wenig humorvoll zu gestalten und die neuen Nutzenden aufzufordern, sich nicht von großen Worten entmutigen zu lassen. Mir hat der empathische Ansatz auf der Hauptseite des BRL-CAD-Wikis gefallen.
  • Es enthält Screenshots von einigen erstaunlichen Dingen, die Nutzer mit dieser Software tun können.

Meilensteine

Juli (Prüfungszeitraum für Vorschläge)

  • Ich werde mich mit der Software und den zugehörigen Wiki-Dokumenten besser vertraut machen, während ich die vorhandenen Tutorials durcharbeite.
  • Ich werde die vorhandenen Dokumente verbessern.

1. August bis 7. August (Teambuilding)

  • Mit Mentoren über das Projekt sprechen.
  • Projektdetails optimieren
  • Nehmen Sie bei Bedarf die erforderlichen Änderungen an den Meilensteinen vor.

8. bis 14. August

  • Docbook XML kennenlernen

15. bis 21. August

  • Dokumentation für „Einführung in BRL-CAD“ schreiben
  • Detaillierte Anleitung für die grundlegende Installation schreiben

22. bis 27. August

  • Sie haben die verschiedenen Funktionen von BRL-CAD kennengelernt und sie zusammen mit Screenshots aufgelistet.
  • Erläutern Sie die einzelnen Funktionen auf einer separaten Seite.

28. August bis 3. September

  • Sie können weiterhin an einzelnen Dokumenten arbeiten, um die Funktionen zu testen.

4. bis 10. September

  • Wir arbeiten an den Prinzipien der Modellierung.
  • Alle Modellierungsprinzipien werden erklärt.

11.–17. September

  • Grundlegende Verwendung der wichtigsten Tools
  • Listen Sie Ideen auf, um die grundlegende Verwendung der einzelnen Tools zu dokumentieren.

18.–24. September

  • Die Nutzung der einzelnen Tools dokumentieren.

25. September bis 1. Oktober

  • Arbeiten Sie an der Modellierung, um ein solides Modell für das Tutorial zu erstellen, und schreiben Sie parallel dazu einen Entwurf.

2. bis 8. Oktober

  • Verbessern Sie den Modellierungsentwurf.

2.–8. Oktober

  • Export- und Importkonverter untersuchen

9. bis 15. Oktober

  • Export- und Importdokumente vorbereiten.
  • Starten Sie mit dem Rendern.

16.–22. Oktober

  • Dokumentation der Anleitung zum Rendern

23. bis 29. Oktober

  • Alle Dokumente werden überprüft.

30. Oktober bis 5. November

  • Mit Docbook XML arbeiten

6. November bis 12. November

  • Bitten Sie Mentoren und andere Communitymitglieder um Feedback und arbeiten Sie an den Änderungen.
  • Mit Mentoren sprechen und letzte Änderungen vornehmen.

12.–22. November

  • Prozess zur Diskussion und Änderung
  • Die Dokumentation wird fertiggestellt.

Über mich

Ich schreibe schon seit meiner Schulzeit. Ich kam von der Schule nach Hause und schrieb alles über meinen Tag auf, was ihn besser oder schlechter gemacht hat. Ich habe mir immer die Fehler notiert, die ich gemacht habe, und überlegt, wie ich sie verbessern kann.

Während meiner Ausbildung zum Webdesigner wurden wir gebeten, jeden Tag aufzuschreiben, was wir lernen. Ich würde einige der Probleme dokumentieren, mit denen ich konfrontiert war, und die Lösung dafür.

Ich versuche immer, anderen zu helfen. In der Schule und im College habe ich meinen Freunden Themen erklärt, die ich selbst verstanden hatte. Die Teilnahme an GSoD ist ein großartiger Schritt, mit dem ich als Autorin dazu beitragen kann, diese Open-Source-Community für neue Nutzer auf der ganzen Welt ansprechender und hilfreicher zu gestalten.