Progetto BRL-CAD

Questa pagina contiene i dettagli di un progetto di documentazione tecnica accettato per la stagione della documentazione di Google.

Riepilogo del progetto

Organizzazione open source:
BRL-CAD
Redattore tecnico:
sahibkaur
Nome del progetto:
Guida introduttiva a BRL-CAD
Durata del progetto:
Durata standard (3 mesi)

Project description

Guida per principianti a BRL-CAD

Estratto del progetto

Questo progetto mira a creare documentazione dedicata agli utenti che non solo non hanno mai utilizzato BRL-CAD, ma non hanno mai utilizzato software open source.

Perché questo progetto

Quando ho visitato per la prima volta il sito web BRL-CAD, dato che ero alle prime armi con l'open source e il BRL-CAD, sono stato sopraffatto dalla quantità di informazioni contemporaneamente. Ma in fondo sapevo che c'era molto da imparare qui. Per questo motivo, ho voluto creare una documentazione per i nuovi utenti come me, in modo che possano trarre il massimo vantaggio da questa community e iniziare a utilizzarla in tutta tranquillità.

Obiettivi

Questo progetto avrà come target i nuovi utenti. Ecco alcuni punti che la mia documentazione mira a raggiungere: Assicurarsi che i nuovi utenti si sentano a proprio agio: poiché questa documentazione è per nuovi utenti non solo per la prima volta che utilizzano BRL-CAD, ma anche per i nuovi utenti open source.

Per farlo:

  • Assicurati di mantenere il punteggio Flesch-Kincaid del documento almeno superiore a 50. Secondo il metodo Flesch-Kincaid, più alto è il punteggio, più facile è comprendere il testo. Puoi controllare il punteggio di leggibilità online.
  • Utilizza elenchi puntati o numerati per evitare che i lettori si annoino o si distraggano con paragrafi lunghi.
  • Utilizza paragrafi e frasi più brevi, perché la lettura e la comprensione di frasi più lunghe richiedono un maggiore impegno mentale.
  • Utilizza sottotitoli per suddividere il testo. Documentazione ben strutturata: la documentazione ben strutturata svolge un ruolo fondamentale nell'aiutare i nuovi utenti. In questo modo non si perdono e sanno dove stanno andando e cosa stanno facendo. Per farlo, ho creato una mappa mentale approssimativa che può aiutarci a documentare questa guida per principianti in modo organizzato.

Descrizione del progetto

Questo progetto si concentra sulla stesura della documentazione per consentire ai nuovi utenti di utilizzare questo software.

Di seguito è riportato un esempio di come intendo rendere la documentazione più descrittiva.

Introduzione di base: BRL-CAD (pronunciato be-are-el-cad) è un progetto CAD con modellazione solida a geometria solida costruttiva (CSG). Si tratta di un potente sistema di modellazione solida open source, multipiattaforma per la progettazione 3D assistita dal computer e la visualizzazione grafica. Non riesci a capire? Esaminiamo la questione nel dettaglio. Open source: il software open source è un software con codice sorgente che chiunque può ispezionare, modificare e migliorare. Poiché BRL-CAD è un software open source, puoi contribuire e migliorare BRL-CAD rispetto a prima! Computer Aided Design (CAD): in parole semplici, il CAD è l'utilizzo di programmi informatici per creare rappresentazioni grafica bidimensionali o tridimensionali di oggetti fisici. Sistema di modellazione solida: BRL-CAD si concentra sulla modellazione solida CAD. La modellazione solida si distingue da altre forme di modellazione geometrica per l'attenzione alla precisione fisica e alla descrizione completa dello spazio 3D. Simula un oggetto sia internamente che esternamente. Costruttiva Geometry Solid Solid (CSG): CSG consente di rappresentare modelli complessi come una serie di operazioni booleane tra le primitive. Gli oggetti solidi più semplici utilizzati per la rappresentazione sono chiamati primitive. Per comprendere i gruppi di segmenti di pubblico di base, visita questa pagina.

*Come indicato nella descrizione dell'idea del progetto: La documentazione coprirà almeno l'installazione di base, una descrizione generale delle funzionalità, dei principi di modellazione di BRL-CAD, l'utilizzo di base degli strumenti principali, la modellazione, l'importazione/esportazione, l'analisi e il rendering.

Di seguito sono riportate brevi introduzioni su come tratterò ogni parte della documentazione.

  • Installazione di base: aggiungerò un tutorial passo passo per installare il software BRL-CAD insieme agli screenshot richiesti. Il tutorial per i neofiti è un punto di partenza ideale per i nuovi utenti. Ecco alcune funzionalità che mi mancano:
  • I passaggi di questo tutorial per principianti non sono elencati o numerati. Un tutorial passo-passo con uno screenshot alla fine di ogni passaggio aumenta le probabilità che l'utente venga coinvolto nel tutorial.
  • Una descrizione generale delle funzionalità: questa sezione conterrà tutte le aree in cui BRL-CAD può fare miracoli. Un approccio diagrammatico sarà un modo migliore per attirare l'attenzione su questa parte.
  • Principi di modellazione di BRL-CAD: questa parte richiederà ulteriori spiegazioni perché l'utente può comprendere meglio BRL-CAD una volta acquisita una solida conoscenza di questi principi di modellazione.
  • Utilizzo di base degli strumenti principali: conterrà dei tutorial separati sui principali strumenti e sul loro utilizzo di base. Si tratta di tutorial passo passo.
  • Esportazione/importazione: gli utenti verranno a conoscenza della libreria di conversioni della geometria. Uno degli usi più comuni di BRL-CAD è la conversione della geometria da un formato all'altro. In questa sezione vengono descritti i convertitori di esportazione e importazione.
  • Rendering: illustreremo le nozioni di base del rendering e la sua necessità nel nostro software. Gli utenti impareranno anche a eseguire il rendering delle immagini in BRL-CAD.

Oltre a questo, l'attenzione è rivolta anche ai seguenti punti:

  • All'inizio della documentazione troverai una panoramica di base di questo software.
  • In che modo gli utenti possono connettersi con questa community open source; link alla chat Zulip BRL-CAD.
  • A livello astratto, rendere la documentazione un po' umoristica e chiedere ai nuovi utenti di non scoraggiarsi da parole volgari. Mi è piaciuto l'approccio empatico utilizzato nella pagina principale della wiki di BRL-CAD.
  • Saranno presenti screenshot di alcune fantastiche funzionalità che gli utenti possono utilizzare con questo software.

Traguardi

Luglio (periodo di revisione delle proposte)

  • Mi familiarizzerò con il software e con la relativa documentazione della wiki mentre esamino i tutorial esistenti.
  • Apporrò miglioramenti ai documenti esistenti.

1° agosto - 7 agosto (consolidamento della community)

  • Discutere con i mentor del progetto.
  • Perfezionare i dettagli del progetto.
  • Apporta le modifiche necessarie nei traguardi (se necessario).

8 agosto - 14 agosto

  • Acquisisci familiarità con Docbook XML

15 agosto - 21 agosto

  • Redazione della documentazione per "Introduzione di base a BRL-CAD"
  • Scrivere un tutorial passo passo per "Installazione di base"

22 agosto - 27 agosto

  • Esplorare le varie funzionalità di BRL-CAD e elencarle insieme agli screenshot.
  • Spiega le singole funzionalità in una pagina separata.

28 agosto - 3 settembre

  • Continua a lavorare sui singoli documenti per le funzionalità.

4 settembre - 10 settembre

  • Lavoro sui principi di definizione del modello.
  • Spiegazione di tutti i principi di modellazione.

11-17 settembre

  • Utilizzo di base degli strumenti principali.
  • Elenca le idee per documentare l'utilizzo di base di ciascun strumento.

18 - 24 settembre

  • Documentare l'utilizzo di ogni strumento.

25 settembre - 1° ottobre

  • Lavora alla modellazione per creare un modello solido per il tutorial e scrivi una bozza.

2 ottobre - 8 ottobre

  • Migliora la bozza della definizione del modello.

2 ottobre - 8 ottobre

  • Studio dei convertitori di esportazione e importazione.

9-15 ottobre

  • Prepara l'esportazione e l'importazione dei documenti.
  • Inizia a lavorare al rendering.

16 ottobre - 22 ottobre

  • Tutorial sul rendering della documentazione.

23-29 ottobre

  • Sto esaminando tutti i documenti.

30 ottobre - 5 novembre

  • Lavorare con il file XML Docbook

6-12 novembre

  • Chiedi le recensioni dei mentori e di altri membri della community e lavora ai cambiamenti.
  • Discuti con i mentori e apporta i cambiamenti finali.

12 - 22 novembre

  • Processo di discussione e modifiche.
  • Ultimi ritocchi alla documentazione.

Informazioni su di me

Mi occupo di scrittura fin dai tempi della scuola. Tornavo a casa da scuola e scrivevo tutto ciò che mi era successo durante la giornata, cosa l'aveva resa migliore o peggiore. Ho sempre voluto annotare gli errori che facevo e come potevo migliorarli.

Durante la mia formazione come web designer, ci è stato chiesto di scrivere quello che impariamo ogni giorno. Documenterò alcuni dei problemi che ho riscontrato e la relativa soluzione.

Come persona, faccio sempre del mio meglio per aiutare gli altri. Durante la scuola e l'università, spiegavo alcuni argomenti ai miei amici dopo averli compresi. Partecipare al GSoD è un passo splendido attraverso il quale, in qualità di scrittore, posso contribuire a rendere questa community open source più coinvolgente e utile per i nuovi utenti di tutto il mondo.