Questa classe vi fornirà molte opportunità di praticare l’arte della scrittura saggio tecnico. Ecco alcune semplici linee guida che è possibile utilizzare per evitare problemi comuni.
Assegna un nome al file del saggio in base al soggetto (non alla data).
I file techfolio template essay sono denominati con la data in cui sono stati creati (ad es 2015-08-26.md). Non farlo: assegna un nome a ciascun file di saggio per riflettere il suo argomento. Ad esempio, potresti basare il nome del file sul titolo del tuo saggio. Se il tuo saggio, il titolo è “Accendere il fuoco”, quindi il nome del file potrebbe essere “creare-il-fuoco.md”.
non includere spazi nel nome del file: utilizzare “creare-il-fuoco.md”, non “accendere il fuoco.md”.
Se il browser è il download del file, invece di mostrarla, che è probabilmente perché il nome del file non finisce con “.md”.
denominazione Corretta è importante, in modo che l’URL associato con il tuo saggio è di facile lettura, fornisce un’indicazione del suo oggetto.
Non utilizzare mai “reflect” o “reflections” come parte del nome del file.
Crea un titolo interessante che attira il lettore.
Non nominare il tuo saggio con il nome del modulo (ad esempio “Configuration Management”) o il nome dell’esperienza (ad esempio “Reflections on Javascript”). I motori di ricerca spesso sottolineano il titolo delle pagine. Vorresti leggere un saggio basato su un titolo del genere? Con un po ‘ di pensiero, puoi inventare qualcosa di personale (cioè “La catastrofe della gestione della configurazione che mi è quasi costata il mio lavoro”) o intelligente (“Non puoi sempre git quello che vuoi”).
Non usare mai “reflect” o “reflections” come parte del titolo.
Usa l’ortografia e la grammatica appropriate
Non scrivere male le parole. Usa la grammatica appropriata. Se non siete sicuri, avvaletevi di strumenti online per controllare l’ortografia e la grammatica prima della pubblicazione.
Scrivi per il mondo, non per il professore
Anche se molti dei tuoi saggi saranno basati sulle tue esperienze facendo compiti a casa (cioè esperienze), non scrivere il tuo saggio come se fosse un’e-mail privata al professore che spiega l’incarico. Non creare sezioni per rispondere a ciascuna delle “domande” dal prompt. Se lo fai, quasi certamente creerai un saggio noioso che non è interessante da leggere.
Invece, scrivilo “per il mondo”. Assumere qualche professionista tecnico casuale è stato googling e il tuo saggio si avvicinò. Rendere il saggio autonomo, autoesplicativo, e utile a quel professionista casuale. Riduci al minimo le ipotesi che fai sul background di ingegneria del software di quella persona (molto meno il loro background in questa classe!) Fornire collegamenti a materiale di sfondo, se utile.
Non solo si dovrebbe scrivere per una varietà di persone, si dovrebbe scrivere per una varietà di volte. In altre parole, prova a scrivere il tuo saggio in modo tale che se qualcuno lo legge in un anno, fornirà comunque informazioni di valore. Se sei un principiante al soggetto, quindi scrivere per fornire informazioni e comprensione per altri neofiti.
Per rendere un saggio avvincente, di solito è utile “raccontare una storia”. Crea una narrazione, non rispondere solo alle domande.
Formatta il codice in modo appropriato
Assicurati che il codice venga visualizzato correttamente nel tuo post. A tale scopo, utilizzando blocchi di codice recintati e evidenziazione della sintassi. Ecco un esempio di evidenziazione del codice javascript :
function getTotalCost() { let cost = 0; for (let drink of this.drinks) { cost += drink.price; } return cost;}Pensa attentamente prima di includere frammenti di codice di grandi dimensioni (oltre, diciamo 50 righe). Come regola generale, mantieni i frammenti di codice a una lunghezza ragionevole e assicurati che tutto il codice sia direttamente correlato all’argomento del tuo saggio.
Usa le intestazioni interne per strutturare il tuo saggio
I buoni saggi hanno una sorta di struttura interna. Aiuta il lettore a comprendere questa struttura fornendo intestazioni interne. Non iniziare con H1 (cioè # in Markdown), poiché è riservato al titolo del tuo post. Invece, inizia con H2 (## in markdown), quindi crea sottosezioni all’interno di quella sezione con H3 (### in markdown), ecc.
Allo stesso modo, utilizzare elenchi dettagliati o enumerati, tabelle, ecc.
Citazioni di formato e attributo
Occasionalmente vorrai citare un altro scrittore nei tuoi saggi tecnici. Questo va bene finché non presenti quelle parole come tue.
Se stai citando una singola frase o due, puoi semplicemente usare il corsivo, le virgolette e fornire il nome dell’autore. Ad esempio:
Come notato da Steve Jobs, “Il design non è solo quello che sembra e si sente come. Il design è come funziona.”
Per le virgolette più lunghe, utilizzare l’ambiente < blockquote>insieme a <piè di pagina>. Ad esempio:
Un giovane cinico è quasi lo spettacolo più triste da vedere, perché significa che è passato dal non sapere nulla al non credere nulla.
Includi immagini o altri media
Come si suol dire, “Un’immagine vale più di mille parole.”È molto facile includere immagini e video nei tuoi saggi. Se il significato del tuo saggio verrà comunicato in modo più chiaro con le immagini, prenditi il tempo per trovarle e includerle. Per istruzioni su come includere immagini e video, consultare la sezione Formattazione della Guida per l’utente di TechFolio.
Non essere noioso, non essere inappropriato
Solo perché il saggio è di natura tecnica, non deve essere noioso. Cerca di iniettare la tua personalità nella tua scrittura. Puoi avere titoli “intelligenti”, riferimenti alla cultura pop e così via.
D’altra parte, non esagerare con l’intelligenza. Chiediti: sarei imbarazzato se mia madre leggesse questo saggio? (Perché potrebbe. Sarei imbarazzato se un potenziale datore di lavoro leggesse questo saggio? (Perché potrebbe.)
L’obiettivo è essere creativi, mostrare una certa personalità e rendere il saggio divertente da leggere oltre che informativo.
Non scriverlo all’ultimo minuto
La qualità dei tuoi saggi aumenterà notevolmente se li sviluppi come segue:
- Scrivi la prima bozza.
- Fai qualcos’altro per 4 ore.
- Torna indietro e fai un passaggio di modifica sulla prima bozza.
Il passaggio di editing normalmente cattura un sacco di problemi e consentono di affinare i vostri pensieri in modo significativo, fino a quando hai fatto un passo lontano dal saggio per una quantità sufficiente di tempo per permettere a te stesso di vederlo con “occhi freschi”. Il modo migliore per farlo è quello di dormire su di esso durante la notte, ma se non avete molto tempo, quindi almeno fare qualcosa di diverso per un paio d’ore. Questo lascia che il tuo subconscio vada a lavorare sul materiale.
Rivedere il contenuto e l’aspetto del tuo post
Una volta che hai scritto e pubblicato, recuperarlo in un browser e vedere come appare.
Un paragrafo non è sufficiente
Scrivere un saggio di due o tre frasi nella speranza di ottenere un credito parziale non è una buona strategia. Per prima cosa, un tale saggio riflette più male sul tuo personaggio professionale di nessun saggio a tutti. Per un’altra cosa, tendiamo ad assegnare zero punti per saggi che riflettono molto poco sforzo.
Fare uso del Centro di scrittura UH Manoa
Il Centro di scrittura UHM fornisce consulenti che sono addestrati per aiutare in tutte le fasi del processo di scrittura; se si sono appena iniziato, la revisione di una bozza, o ad un certo punto nel mezzo.
È possibile programmare fino a due appuntamenti a settimana e tre appuntamenti a settimana.