Progetto BRL-CAD

Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per Google Season of Docs.

Riepilogo del progetto

Organizzazione open source:
BRL-CAD
Technical writer:
sahibkaur
Nome progetto:
Guida per principianti al BRL-CAD
Durata del progetto:
Durata standard (3 mesi)

Project description

Guida per principianti al BRL-CAD

Estratto del progetto

Questo progetto mira a creare una documentazione dedicata agli utenti che non solo non hanno familiarità con il modello BRL-CAD, ma hanno anche familiarità con l'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 con BRL-CAD, mi sono sentita sopraffatta dalla quantità di informazioni in una volta sola. Ma, in fondo, sapevo che c'era molto da imparare. Quindi, volevo creare una documentazione per i nuovi utenti come me per ottenere molto da questa community e sentirsi a proprio agio.

Obiettivi

Questo progetto avrà come target nuovi utenti. Ecco alcuni punti che la mia documentazione mira a raggiungere: Per garantire che i nuovi utenti si sentano a proprio agio: questa documentazione è rivolta non solo ai nuovi utenti di BRL-CAD, ma anche all'open source.

A questo scopo, mi occuperò di:

  • Assicurati che il punteggio Flesch-Kincaid del documento sia almeno superiore a 50. Secondo il metodo di Flesch-Kincaid, più alto è il punteggio, più facile è capire il testo. Puoi verificare il punteggio di leggibilità online.
  • Utilizza elenchi puntati o numerati in modo che i lettori non si annoino o distraggano i paragrafi.
  • Usa frasi e paragrafi più brevi perché richiedono un lavoro relativamente più mentale per leggere e comprendere frasi più lunghe.
  • Utilizza i sottotitoli per suddividere il testo. Documentazione ben strutturata: una documentazione ben strutturata svolge un ruolo fondamentale nel guidare nuovi utenti. Impedisce loro di perdersi e può far sapere loro dove si stanno dirigendo e cosa stanno facendo. A questo scopo, ho creato una mappa mentale approssimativa che può aiutarci a documentare questa guida per principianti in modo organizzato.

Descrizione del progetto

Questo progetto è incentrato sulla scrittura di documentazione per consentire ai nuovi utenti di mettere a disposizione 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 modello CAD a geometria solida costruttiva (CSG) a modellazione solida. Si tratta di un potente sistema di modellazione solida, multipiattaforma e open source, per la progettazione 3D computerizzata e la visualizzazione grafica. Non riesci a capire come procedere? Esaminiamo la questione nel dettaglio. Open source: un software open source è un software con codice sorgente che chiunque può esaminare, modificare e migliorare. Poiché BRL-CAD è un software open source, puoi contribuire e migliorare BRL-CAD. Computer Aided Design (CAD): in parole semplici, il CAD è l'uso di programmi informatici per creare rappresentazioni grafiche a due o tre dimensioni 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'enfasi sulla precisione fisica e sulla completa descrizione dello spazio 3D. Simula un oggetto sia internamente che esternamente. Geometria solida costruttiva (CSG): la tecnologia CSG consente di rappresentare modelli complessi come una serie di operazioni booleane tra primitive. Gli oggetti solidi più semplici utilizzati per la rappresentazione sono chiamati primitive. Per una comprensione generale di CSG, visita questa pagina.

*Come accennato nella descrizione dell'idea del progetto: La documentazione riporterà quanto meno l'installazione di base, una descrizione complessiva 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.

Qui trovi 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 nuovi utenti è un buon punto di partenza per i nuovi utenti. Ecco alcune delle cose che mancano:
  • I passaggi di questo tutorial per principianti non sono puntati o numerati. Avere un tutorial passo passo con uno screenshot alla fine di ogni passaggio aumenta le probabilità che l'utente si interessi al tutorial.
  • Descrizione generale delle funzionalità: questa sezione conterrà tutte le aree in cui BRL-CAD ha il potere di mostrare miracoli. Un approccio schematico 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 che avrà una solida conoscenza di questi principi di modellazione.
  • Utilizzo di base degli strumenti principali: in questa sezione, saranno disponibili tutorial separati degli strumenti principali e del relativo utilizzo di base. Questi saranno tutorial passo passo.
  • Esportazione/importazione: gli utenti impareranno a conoscere la libreria di conversione della geometria. Uno degli utilizzi più comuni di BRL-CAD è la conversione della geometria da un formato a un altro. In questa sezione vengono illustrati gli utenti che hanno completato l'esportazione e l'importazione.
  • Rendering: vedremo gli aspetti di base del rendering e la sua esigenza nel nostro software. Gli utenti impareranno anche come eseguire il rendering delle immagini in BRL-CAD.

A parte questo, ci concentreremo anche sui seguenti punti:

  • All'inizio della documentazione si avrà una comprensione di base di cosa tratta questo software.
  • In che modo gli utenti possono entrare in contatto con questa community open source; aggiungi un link alla chat zulip BRL-CAD.
  • A livello astratto, rendere la documentazione un po' divertente e chiedere ai nuovi utenti di non farsi scoraggiare dalle parolacce. Mi è piaciuto l'approccio empatico utilizzato nella pagina principale del wiki BRL-CAD.
  • Contiene screenshot di alcune straordinarie cose che gli utenti possono fare utilizzando questo software.

Traguardi

Luglio (periodo di revisione della proposta)

  • Prenderò maggiore familiarità con il software e i suoi documenti wiki mentre analizzerò i tutorial esistenti.
  • Apporterò miglioramenti ai documenti esistenti.

1° agosto - 7 agosto (legami comunitari)

  • Discutere del progetto con i mentori.
  • Perfezionamento dei dettagli del progetto.
  • Apporta le modifiche necessarie agli obiettivi (se necessario).

8-14 agosto

  • Acquisisci familiarità con Docbook XML

15 agosto - 21 agosto

  • Documentazione di scrittura per "Introduzione di base a BRL-CAD"
  • Scrivi un tutorial passo passo per l'"Installazione di base"

22-27 agosto

  • Esplorazione di varie funzionalità di BRL-CAD e loro elenco insieme a screenshot.
  • Spiega le singole funzionalità in un'altra pagina.

28 agosto - 3 settembre

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

4-10 settembre

  • al lavoro sui principi di base dei modelli.
  • Spiegazione di tutti i principi di definizione del modello.

11-17 settembre

  • Lavora sull'utilizzo di base degli strumenti principali.
  • Elenco di idee per documentare l'utilizzo di base di ogni strumento.

18-24 settembre

  • Documentare l'utilizzo di ogni strumento.

25 settembre-1° ottobre

  • Lavora sulla definizione del modello per creare un solido modello per il tutorial, oltre a scrivere una bozza.

2-8 ottobre

  • Migliora la bozza di definizione del modello.

2-8 ottobre

  • Studio degli utenti che hanno effettuato una conversione nelle esportazioni e nelle importazioni.

9 - 15 ottobre

  • Preparare l'esportazione e l'importazione dei documenti.
  • Inizia a lavorare sul rendering.

16-22 ottobre

  • Documentare il tutorial sul rendering.

23 - 29 ottobre

  • Esame di tutti i documenti.

30 ottobre-5 novembre

  • Lavorare sul file XML del documento

6 novembre-12 novembre

  • Chiedi recensioni ai mentori e ad altri membri della community e lavora ai cambiamenti.
  • Discutere con i mentori e apportare cambiamenti finali.

12-22 novembre

  • Processo di discussione e modifica.
  • Daremo un ultimo tocco alla documentazione.

Informazioni su di me

Ho iniziato a scrivere sin dai tempi scolastici. Tornavo a casa da scuola e scriverevo tutto sulla mia giornata; cosa ha migliorato o peggiorato la mia giornata? Ho sempre voluto scrivere gli errori che ho commesso e come posso migliorarli.

Durante la mia formazione come web designer, ci è stato chiesto di scrivere cosa impariamo ogni giorno. Documenterei alcuni dei problemi che ho affrontato e la loro soluzione.

Come persona, faccio sempre il mio meglio per aiutare gli altri. A scuola e all'università, spiegavo alcuni argomenti ai miei amici dopo averli compresi io. Partecipare a GSoD è uno splendido passo attraverso il quale, come scrittrice, posso contribuire a rendere questa community open source più coinvolgente e utile per i nuovi utenti di tutto il mondo.