Articolo originale: The freeCodeCamp Publication Style Guide
Grazie per condividere la tua esperienza e le tue intuizioni con la comunità degli sviluppatori.
La nostra pubblicazione ti aiuterà ad istruire ed ispirare sviluppatori, designer e data scientist in tutto il mondo.
freeCodeCamp.org è uno dei siti di tecnologia più visitati del web e può aiutarti a raggiungere migliaia di persone che beneficeranno della tua saggezza.
La nostra no profit ha anche una grande presenza sui social media, forte accessibilità, SEO, e una solida reputazione come seria risorsa di apprendimento. Tutto ciò si tradurrà in più lettori per i tuoi articoli.
In questa guida di stile ti daremo consigli su come massimizzare il tuo impatto rendendo i tuoi articoli più efficaci possibile.
Questo non è il posto per sfide del tipo "un post al giorno" o post di osservazione stile flusso di coscienza.
Porta i tuoi fatti. Porta le tue citazioni. Porta i tuoi frammenti di codice. Porta le tue visualizzazioni di dati.
Anni di dati mostrano che quanto più un articolo va in profondità, tanto più a lungo una persona lo leggerà, e tanto più probabilmente lo condividerà con i suoi amici.
Se non sei in grado di scrivere almeno 500 parole sul tuo argomento, prova a fare un po' più di ricerca su di esso.
Immergendoti e ampliando la tua ricerca, sarai in grado di fornire maggiori informazioni ai tuoi lettori.
Le persone sono impegnate. Quindi devi catturare immediatamente la loro attenzione. Come puoi farlo? Con un titolo avvincente.
Il Titolo: L'unica parte del tuo articolo che verrà letta dal 100% delle persone
Prima che tu inizi a scrivere la tua storia, spendi del tempo a comporre un titolo avvincente. L'intero articolo scaturirà quindi da quel titolo e vi si ricollegherà per sostenerlo.
Durante gli ultimi 7 anni, abbiamo sperimentato diversi format. Abbiamo riscontrato che i tutorial tecnici approfonditi sono i più utili per i milioni di sviluppatori che leggono la nostra pubblicazione in tutto il mondo.
Ecco alcune strutture di titoli che abbiamo scoperto funzionare bene per i tutorial:
- "Come aggiustare…"
- "Come costruire…"
- “Come fare [attività] con [strumento]”
- "Come funziona [qualcosa]"
- "La guida [aggettivo] per…"
- “Cosa è [nome]? In parole semplici, per favore.”
- “Cosa è esattamente un [nome]?”
- “Perché [qualcosa] è importante.”
- “Impara [qualcosa] in N ore”
- "Una storia di [qualcosa]”
- “La storia dietro [qualcosa]”
- "Il manuale [qualcosa]" (per tutorial più lunghi di almeno 20,000 parole)
Aggiungi un'immagine di copertina
Una volta scelto il tuo titolo chiaro ed esaustivo, aggiungi una bella immagine di copertina. Clicca l'ingranaggio nell'angolo in alto a destra.
Alcuni contributori creano le loro immagini di copertina per i loro articoli. Un sito gratuito come Canva.com può aiutarti con questo procedimento. (Se vuoi evitare che i bordi della tua immagine vengano tagliati quando il tuo articolo è condiviso su Facebook o Twitter, usa un rapporto di aspetto dell'immagine di 1.91:1.)
Alcune cose da tenere a mente quando crei un'immagine di copertina:
- Usa colori con un bel contrasto in modo da far risaltare immagini e testo
- Non usare troppo testo nelle immagini – concentrati sul soggetto o sulle parole chiave principali (ad esempio, invece di usare tutto il testo: "Come costruire una app per ordinare cibo da asporto con React", potresti solo dire "Come costruire una app con React".)
- In generale, ricorda: semplice di solito è meglio per le immagini di copertina. Ciò che vuoi è un'immagine accattivante e facile da vedere/leggere su dispositivi più piccoli.
- Puoi usare le tue immagini di copertina come aiuto per costruire ilo tuo "brand" come scrittore. Se crei delle immagini con uno stile particolare, le persone inizieranno a riconoscere i tuoi tutorial soltanto dall'immagine di copertina.
Se non hai un'immagine, puoi scaricare un'immagine senza bisogno di attribuzione da un sito come Pexels, Unsplash, o Wikipedia, salvarla e poi caricarla su Ghost.
Per favore, non creare hotlink a immagini. Invece, scarica ogni immagine che vuoi usare e trascinala nel tuo articolo su Ghost. In questo modo freeCodeCamp può servire le immagini attraverso i propri affidabili CDN (per una migliore prestazione e accessibilità). Per favore cerca di tenere la dimensione delle immagini sotto 1MB.
Imposta l'URL del tuo post
Puoi impostare l'URL del tuo articolo direttamente. Raccomandiamo di tenerlo corto e descrittivo come “machine-learning-with-pytorch-tutorial” o “from-retail-worker-to-software-developer”.
Scegli i tuoi tag
Puoi scegliere da uno a cinque tag per il tuo articolo. Una volta che li hai scelti, fallo sapere al team editoriale e li aggiungeremo per te.
Questi tag renderanno più facile per i lettori scoprire i tuoi articoli attraverso la ricerca e la navigazione dei tag.
Il primo tag che scegli è il più importante, e verrà mostrato sopra l'articolo, così.
Per favore non cambiare nessuna delle meta-informazioni nel menù. La nostra pubblicazione ha dei valori predefiniti adatti per questi.
Consigli per scrivere un articolo che le persone leggeranno davvero
Grammatica, spelling e formattazione sono importanti
Leggere articoli che sono chiari e ben formattati è più facile. Ecco alcuni consigli per rendere i tuoi articoli più leggibili possibile:
- Mantieni la semplicità. Usa un linguaggio semplice e diretto dove possibile.
- Usa frasi brevi. Dividi le frasi più lunghe in frasi più brevi. Questo aiuterà le persone e leggere più velocemente e capire meglio.
- Usa paragrafi brevi. Dividi i paragrafi lunghi in paragrafi di una o due frasi. I muri di testo faranno abbandonare l'articolo ai tuoi lettori o li faranno passare alla modalità "scrematura".
- Pulisci la punteggiatura. Troppi punti esclamativi creano distrazione!!! I punti e virgola sono raramente necessari; usa un punto e basta. E i puntini di sospensione sono... beh... di solito un po' troppo.
- Usa dei sottotitoli per strutturare il tuo testo. La nostra pubblicazione offre intestazioni grandi e piccole per il tuo toolkit. Usa le intestazioni grandi per gli argomenti principali, e le sotto-intestazioni più piccole per le sezioni all'interno di questi argomenti.
- Non fare un uso eccessivo di grassetto, corsivo o entrambi. Troppa formattazione rende il testo difficile da leggere. Specialmente se usi grassetto e corsivo insieme. Usa grassetto e corsivo separatamente e sporadicamente.
- Rimuovi le abbreviazioni. Rendono gli articoli più difficili da capire. Scrivi per esteso ogni acronimo che non è ben noto. Cambia le espressioni latine come "e.g" in "ad esempio" e "...ecc." in "come...".
Rileggi il tuo articolo. Poi rileggilo ancora.
Alcuni contributori scrivono rapidamente in modo da mettere le proprie idee su carta velocemente. Altri contributori svolgono tutta la loro ricerca prima di scrivere una sola parola.
Qualunque sia il tuo processo di scrittura, assicurati di allontanarti dal tuo articolo e tornarci con uno sguardo nuovo.
Rileggi il tuo articolo. Poi leggilo ad alta voce. Sarai sorpreso da quanti piccoli errori, errori di ortografia, e frasi sgraziate incontrerai.
Evidenzia la sintassi del tuo codice
Puoi creare un blocco di codice digitando tre backtick (```), seguite da uno spazio.
Puoi anche specificare il linguaggio di programmazione con cui vuoi evidenziare la sintassi.
Ad esempio, digitare ```js ti darà la colorazione della sintassi JavaScript. E supportiamo anche la colorazione della sintassi di una dozzina di altri linguaggi di programmazione popolari.
Rimani in tema
Il tempo dei tuoi lettori non è infinito. Aiuta i tuoi lettori a ottenere quanto più valore possibile dai tuoi articoli prima che debbano andare avanti con le loro vite.
Mantieni i tuoi articoli tecnici approfonditi in ogni loro sezione
- Scrivi un'introduzione concisa che dice ai lettori cosa realizzeranno.
- Usa una lista numerata come questa per indicare i passaggi.
- Inserisci quanti più dettagli possibile.
- Chiudi ricordando ai lettori cosa hanno realizzato.
Scrivi lunghi articoli comprensivi di tutto invece di articoli divisi per parti
Abbiamo osservato più e più volte che le persone non si preoccuperanno di leggere la seconda, la terza o l'ennesima parte di una serie se non hanno letto tutte le parti precedenti.
Allo stesso tempo, abbiamo visto che gli articoli molto lunghi e approfonditi funzionano sorprendentemente bene. Le persone inseriranno il tuo articolo tra i preferiti o lo condivideranno sui social media per poi tornarci in seguito.
Quando le persone vedono che un articolo è lungo, assumeranno spesso che è serio e completo. Questo ispira le persone a rallentare e spendere davvero del tempo leggendo il tuo articolo. Molte persone apriranno persino un editor di codice e programmeranno a casa.
Mantienilo quanto più adatto a tutti possibile
La comunità di freeCodeCamp è principalmente composta da adulti, ma ci sono anche bambini.
Cerca di non usare volgarità a meno che non sia in una citazione diretta, e stai alla larga da meme potenzialmente offensivi.
Infine, se un articolo sembra violare il codice di condotta, lo cancelleremo immediatamente. Ma ne salveremo una copia e te la invieremo ad uso personale, così che tu non perda il tuo lavoro.
Usa immagini senza attribuzione necessaria o immagini che hai creato tu
Puoi includere screenshot e altre immagini che hai creato da te. Ma se non possiedi i diritti dell'immagine, usa un'immagine simile che però non ha bisogno di attribuzione. Queste non richiedono costi di licenza o attribuzione.
Di nuovo, se hai bisogno un'immagine di stock, alcuni siti web dove puoi trovare queste immagini sono Pexels, Unsplash e Wikipedia.
Inoltre, come promemoria, per favore non usare hot-link a immagini. Invece, scarica ogni immagine che vuoi usare nel tuo tutorial e trascinala su Ghost. In questo modo, freeCodeCamp può fornire le immagini attraverso i nostri CDN affidabili (per una prestazione e un'accessibilità migliori). E per favore, cerca anche di mantenere la dimensione delle immagini sotto 1 MB.
Alcune immagini – come i webcomic – sono create pensando alla condivisione. Per queste, puoi inserire l'immagine e poi dire "Image credit: XKCD" con un link alla specifica pagina del webcomic.
Cita sempre le tue fonti e non plagiare.
Il plagio si verifica quando qualcuno fa passare il lavoro scritto di qualcun altro (o un'immagine, del codice e così via) come proprio. È un reato grave che rende le persone passibili di licenziamento dal lavoro ed espulsione da scuola. E viene preso altrettanto seriamente anche nelle pubblicazioni di freeCodeCamp.
Poche persone sono state così sfacciate da tentare il plagio sulle pubblicazioni di freeCodeCamp. Ma ce ne sono state alcune negli scorsi 7 anni. Le abbiamo intercettate, abbiamo rimosso i loro articoli e li abbiamo bannati a vita dalla comunità.
Non preoccuparti – non plagerai niente accidentalmente. Il plagio è un atto intenzionale.
Come citare le tue fonti in modo adeguato
Se stai parafrasando (o citando direttamente) qualcosa che qualcuno ha detto in un altro articolo, video, corso o altro mezzo, dovresti citarlo. Questo significa aggiungere un link alla fonte originale e usare la formattazione con le virgolette, così:
"Questo gioco è controllato interamente digitando in un'interfaccia a riga di comando. Poiché il gioco è in real time, questo può portare a momenti intensi di digitazione rapida dei comandi quando cerchi di salvare i tuoi droni dai pericoli." (Fonte: Quincy Larson)
Questo include testo (o codice) preso da documentazione ufficiale, StackOverflow, GitHub e altre risorse simili. Se stai copiando e incollando qualcosa da una fonte simile, assicurati di citarlo a linkarlo.
Attribuisci sempre citazioni alle persone che le hanno dette in origine. Se si tratta di una citazione su più righe, puoi utilizzare formattazione a citazione come questa per suddividere i paragrafi più lunghi:
“Quando hai intelletto di tuo, è un piacere dare credito agli altri per il proprio.”
― Criss Jami
Se il tuo codice è pesantemente ispirato (o preso in prestito) da quello di qualcun altro, dovresti dargli credito.
Prima di pubblicare un articolo che si appoggia pesantemente sul lavoro di qualcun altro, chiediti: il mio articolo espande sostanzialmente il lavoro di quella persona? Se no, potrebbe non esserci bisogno di un articolo.
Una nota finale sull'utilizzo delle parole di altre persone: è sempre meglio usare le proprie ogni volta che puoi. Quindi, invece di copiare/incollare e quotare le fonti eccessivamente, cerca di digerire le informazioni e spiegarle con parole tue. Ti aiuterà a capirle meglio e non rischierai di plagiare il lavoro di qualcun altro.
Ma se proprio devi citare o prendere in prestito da un altra fonte, assicurati di farlo correttamente.
Alcuni esempi di plagio
Qui ci sono un paio di esempi di plagio – cioè, cosa non fare. Il primo dovrebbe essere abbastanza chiaro (è copiato parola per parola):
Testo originale:
Solo una breve nota prima di iniziare: l'interfaccia desktop e l'app mobile di Instagram sono piuttosto diverse. La maggior parte delle persone usa Instagram sul proprio dispositivo mobile (tramite l'app Instagram) perché è lì che puoi postare foto. (Fonte: Abbey Rennemeyer)
Testo plagiato:
Ok, tutti pronti a conoscere Instagram? Andiamo!
Solo una breve nota prima di iniziare: l'interfaccia desktop e l'app mobile di Instagram sono piuttosto diverse. La maggior parte delle persone usa Instagram sul proprio dispositivo mobile (tramite l'app Instagram) perché è lì che puoi postare foto.
Ora che lo abbiamo chiarito, siamo pronti a partire.
Come puoi vedere, il testo plagiato è inserito in mezzo a del testo originale. È allettante aggiungere frasi o paragrafi che qualcun altro ha scritto davvero bene. Ma a meno che tu non citi quelle parti, si tratta di plagio.
Il secondo esempio, qui sotto, potrebbe non essere altrettanto evidente. Ma se stai parafrasando strettamente le parole di qualcun altro, è comunque plagio.
Testo originale:
Ci sono molti motivi per cui potresti voler condividere foto e video su Instagram.
Magari stai avviando un'attività o lanciando un prodotto. Potresti voler lavorare per una compagnia che vuole avere una presenza Instagram. Magari vuoi creare un tuo brand personale come fotografo, viaggiatore, o artista. O vuoi solo condividere ciò che ti piace al momento tramite immagini.
Qualunque sia la ragione, Instagram è un ottimo posto per condividere idee, messaggi, e arte online. (Fonte)
Testo plagiato:
Ci sono molte ragioni per pubblicare foto e video su Insta.
Magari stai avviando la tua attività o lanciando qualche prodotto. Magari lavori per un'organizzazione che vuole avere una presenza su Instagram. O magari vuoi creare il tuo brand. O vuoi solo condividere ciò che stai facendo adesso tramite immagini.
In ogni caso, Instagram è un ottimo posto su cui postare idee, messaggi e arte online.
Come puoi vedere, il testo qui sopra è pesantemente basato sul testo originale. Può cambiare qualche parola, o lasciarne fuori qualcuna, ma è chiaro che la persona non lo ha scritto da sola. Di nuovo, questo non va bene e verrebbe considerato plagio.
Se hai domande su cosa costituisce un plagio, fai qualche ricerca e assicurati di sapere come citare correttamente le tue fonti e creare un lavoro originale.
Nessun cross-posting, per favore.
Il cross-posting generalmente è inefficace. Se vuoi che molte persone leggano il tuo articolo, ti raccomandiamo di pubblicarlo con una singola pubblicazione – sia essa quella di freeCodecamp, il tuo blog, o una rivista online.
Un paio di eccezioni:
- Può valere la pena eseguire il cross-posting di un articolo all'interno di un ambiente controllato (che non è indicizzato da Google) come LinkedIn.
- Se vuoi mettere in evidenza i tuoi scritti provenienti da altre pubblicazioni sul tuo blog affinché i potenziali datori di lavoro possano vederli, puoi eseguire il cross-post sul tuo blog e utilizzare semplicemente un URL canonico per puntare alla pubblicazione originale. Questo ridurrà la probabilità che Google si confonda e mostri la versione sbagliata tra i suoi risultati.
Puoi comunque prendere alcuni dei tuoi lavori dal tuo blog personale su un argomento simile (tipo "Plugin di Visual Studio" o "Comandi Bash Avanzati") e raccoglierli in un unico, lungo articolo di freeCodeCamp.
La nostra filosofia è che, poiché passeremo ore a istruirti sul tuo articolo, modificarlo meticolosamente e pubblicizzarlo alla grande comunità di freeCodeCamp, ti chiediamo di non pubblicarlo in cross-posting su siti di pubblicazione libera come Medium.
Modi accettabili di pubblicizzarti nei tuoi articoli
freeCodeCamp.org è una organizzazione no-profit supportata da donatori. Non vogliamo dare l'impressione di avere "posizionamenti pubblicitari pagati" (non ne abbiamo) poiché questo potrebbe scoraggiare le persone dal farci donazioni.
Allo stesso tempo, capiamo bene che potresti voler pubblicizzare il tuo ultimo libro, corso o applicazione SaaS, incoraggiare le persone a iscriversi alla tua mailing list o a seguirti su Twitter.
Ti chiediamo di mantenere ciò quanto più elegante possibile. Va bene inserire una frase con una call-to-action al tuo prodotto alla fine del tuo articolo.
Non aprire il tuo articolo con un link al tuo prodotto, questo sembra spam. E non usare link affiliati nei tuoi articoli a meno che non siano link a libri o corsi che hai creato personalmente.
Tieni inoltre presente che non accettiamo account relativi a marchi. Proibiamo ogni sorta di ghostwriting. E non trasferiamo articoli da un impiegato di una compagnia a un altro.
E per favore – non scrivere storie per conto di altre persone che non si sono ancora guadagnate il loro account di contributore di freeCodeCamp.
Nota che per i tuoi scopi di SEO – a differenza della maggior parte dei siti popolari – tutti i link sulle nostre pubblicazioni sono rel="doFollow". Ciò significa che sì – ogni pagina a cui fai un collegamento (incluso un tu blog) otterrà un vantaggio nelle classifiche Google. Tienilo a mente e non te ne approfittare troppo.
Completare il processo
Una volta che sei sicuro che la storia sia pronta per i lettori, manda per email un link alla tua bozza a ilenia@freecodecamp.org. Il nostro team editoriale la esaminerà rapidamente e apporterà delle modifiche per rafforzare ulteriormente il tuo articolo prima di pubblicarlo.
Le cose principali a cui teniamo sono il titolo e i paragrafi di apertura. Se notiamo problemi di formattazione del testo o errori grammaticali, correggeremo anche quelli.
Se pensiamo ancora che il tuo articolo necessiti di un lavoro significativo, te lo diremo e potrai inviarlo nuovamente dopo aver apportato le modifiche.
Infine, una nota importante: se un'azienda ti sta pagando per scrivere un articolo e poi provare a pubblicarlo su freeCodeCamp, per favore comunicalo al team editoriale quando invii la bozza.
Altri consigli utili
Markdown GitHub
Sapevi che puoi utilizzare il Markdown in stile Github per comporre i tuoi articoli?
Puoi incollare il markdown in /news e verrà istantaneamente convertito in testo formattato.
Puoi anche digitare la sintassi markdown all'inizio di una riga – ad esempio # o ## per le intestazioni, o * per gli elenchi puntati – per poi iniziare a scrivere. Il testo cambierà in accordo con il formato specificato.
Vai piano con gli embed
Puoi incorporare cose come i tweet e video Youtube, se vuoi. Clicca l'icona + all'inizio di una nuova riga, e puoi scegliere da una varietà di strumenti di incorporamento.
Detto ciò, ti incoraggiamo ad usarli di rado per tre motivi:
- Gli embed fanno una chiamata a servizi esterni, come Twitter, che potrebbero rallentare l'esperienza
- Molte persone che leggono le pubblicazioni lo fanno utilizzando i lettori dello schermo. Un'ampia porzione della comunità degli sviluppatori vive con disabilità visive (o cecità completa). Gli embed sono meno accessibili del testo.
- Ogni articolo in pubblicazione ha una versione Accelerated Mobile Pages, e gli embed potrebbero non funzionare correttamente lì.
Se ancora non hai una account contributore, puoi richiederlo qui (o se vuoi pubblicare in inglese consulta la guida in inglese per i contatti corretti).
Grazie per aver condiviso le tue opinioni con la comunità degli sviluppatori.
Speriamo che questa guida ti aiuti a scrivere articoli migliori in modo che l'intera comunità possa beneficiare della tua conoscenza.
Buona programmazione!
— Il team editoriale di freeCodeCamp