Scopri Markdown: lo strumento di scrittura per gli sviluppatori di software

Se sei un ingegnere del software, probabilmente hai dedicato molto tempo a perfezionare il tuo ambiente per aumentare la tua produttività. Hai il tuo IDE preferito. Hai il tuo debugger preferito. Hai il tuo strumento di monitoraggio delle prestazioni preferito. Ma che dire del tuo strumento per scrivere documentazione, manuali e rapporti? Dopotutto, scrivere richiede una quantità non banale del tuo tempo, vero? In effetti, è ora di prendere sul serio il tuo strumento di scrittura.

E ricordiamoci che sei un tecnico , quindi gli editor WYSIWYG potrebbero essere o meno l'opzione migliore per te. Non vuoi necessariamente (o ti piace!) navigare nei menu, nelle barre degli strumenti e nelle barre multifunzione per formattare il testo.

E se, invece, potessi facilmente aggiungere tutti i tuoi stili di formattazione direttamente nel testo come semplice sintassi in linea per produrre testo completamente formattato?

Beh, in effetti, puoi. Questo è Markdown ed è di questo che tratta questo tutorial.

Quando di più è di meno...

Il software di elaborazione testi è scritto per soddisfare una gamma estremamente ampia di utenti e casi d'uso e, in quanto tale, deve fornire tutti i tipi di funzionalità. Ma chiaramente, è probabile che solo un piccolo sottoinsieme di quella funzionalità sia rilevante per ogni singolo utente. E per la maggior parte degli utenti, che vogliono semplicemente creare un documento (e non hanno bisogno di progettare una brochure o un poster di marketing), un piccolissimo sottoinsieme delle molte, molte opzioni disponibili è rilevante.

In effetti, Microsoft se ne è resa conto chiaramente alcuni anni fa, quando ha riprogettato l'interfaccia utente di Microsoft Word in gruppi funzionali distinti che hanno chiamato "nastri". Tuttavia, è interessante notare che la maggior parte degli utenti ti dirà di aver trovato la nuova interfaccia più confusa e difficile da navigare rispetto al suo predecessore.

In effetti, a volte più può essere meno quando si tratta di facilità d'uso e produttività.

... e quando meno è di più

Ammettilo, sei un ingegnere del software, non un grafico. Vuoi solo scrivere quel manuale, o documento tecnico, o rapporto, e farla finita. Sarai molto felice e soddisfatto di alcune funzionalità di formattazione di base come intestazioni, elenchi puntati o numerati e blocchi di codice. E, oh ​​sì, sarebbe utile anche una formattazione dei caratteri (grassetto, corsivo, ecc.). Questo è tutto. (E amico, se potessi farlo anche solo in vi, sarebbe davvero fantastico!)

Entra in Ribasso.

Cos'è Markdown?

John Gruber (con il contributo sostanziale del guru tecnico e attivista di Internet Aaron Swartz) ha creato il linguaggio Markdown nel 2004 con l'obiettivo di consentire alle persone "di scrivere utilizzando un formato di testo semplice di facile lettura e facile da scrivere e, facoltativamente convertirlo in XHTML (o HTML) strutturalmente valido”.

Markdown è stato progettato per essere leggibile così com'è, senza sembrare che sia stato contrassegnato con tag o istruzioni di formattazione (a differenza del testo formattato con un linguaggio di markup come RTF o HTML che può essere sia difficile da creare che da leggere nel suo formato non elaborato ).

Markdown ti consente di scrivere utilizzando un formato di testo semplice di facile lettura e scrittura, che può quindi essere convertito in HTML strutturalmente valido. Quindi, per essere del tutto precisi, Markdown è in realtà due cose:

1. Una sintassi di formattazione del testo normale
2. Uno strumento software (la cui prima versione è stata scritta in Perl) che converte la formattazione del testo normale in HTML.

Markdown incorpora una manciata di convenzioni sintattiche semplici, abbastanza intuitive e facili da usare. Soprattutto per te come ingegnere del software, che non è scoraggiato dalla necessità di imparare e utilizzare queste convenzioni di sintassi di base, Markdown può davvero essere il percorso di minor resistenza tra ciò che vuoi scrivere e farlo scrivere.

Impara il ribasso: per iniziare

Markdown è facile da imparare. Super facile. Puoi imparare le basi in cinque minuti e diventerà rapidamente una seconda natura. E, proprio come la relazione tra CSS e preprocessori CSS, puoi usare quanto poco o quanto vuoi.

Se sei abituato a qualsiasi tipo di convenzione di scrittura di testo normale, potresti già avere familiarità con alcune convenzioni di markdown, come numeri o trattini all'inizio di una frase per creare un elenco, asterischi attorno a una parola per enfatizzare e così via su. Quindi, ad esempio, se vuoi visualizzare qualcosa in corsivo, avvolgilo semplicemente in asterischi come *this* (al contrario di una sintassi HTML più goffa come <span>this</span> ).

Allo stesso modo, puoi specificare un'intestazione H1 semplicemente aggiungendo un prefisso '#' alla tua riga (ad esempio, # Section Heading , invece di <h1>Section Heading</h1> ).

Un altro ottimo utilizzo per l'apprendimento di Markdown, in particolare per noi ingegneri del software, è usarlo per la documentazione sui repository di codice sorgente. La maggior parte dei repository include un file README.md ( .md è l'estensione standard per un file Markdown). Github, ad esempio, ha il suo "Markdown al gusto di Github", che aggiunge funzionalità aggiuntive specifiche per la documentazione di sviluppo. Questo può certamente risparmiare tempo nel dover scrivere questa documentazione in HTML.

Come semplice esempio, supponiamo che tu voglia includere il seguente snippet nella tua documentazione:

<h2 style=color:#3863a0;font-size:1.5em;font-weight:600;margin-top:2em;margin-bottom:1em;line-height:1.3em;>Iniziare i plug-in</h2>

Avvia pluginName sul tuo container usando jQuery come segue:

$(function() { $('#container').pluginName(); }); Utilizzando l'ID del nostro contenitore, possiamo avviare pluginName con il metodo jQuery .pluginName() .

Ecco un confronto di come ciò sarebbe fatto in HTML e Markdown:

Per ulteriore aiuto per iniziare, ci sono molti tutorial di Markdown online per aiutarti ad aggiornarti, inclusa una panoramica di Markdown di John Gruber (il creatore di Markdown) e un tutorial di Markdown online.

Analizzatori e strumenti di markdown

Dopo aver scritto il tuo articolo in Markdown, avrai bisogno di un'app per analizzare la sintassi in HTML. Ce ne sono alcuni fantastici che sono gratuiti tra cui:

• StackEdit: editor Markdown basato su browser che ha alcune opzioni di sincronizzazione con servizi popolari come Google Drive e Dropbox
• Online Kramdown Editor - un altro editor Markdown basato su browser con un'interfaccia estremamente semplice
• Mou - il miglior scrittore di Markdown basato su Mac che mi sia imbattuto come un'opzione più geek per gli sviluppatori; tonnellate di funzionalità e gratuite (mentre in versione beta) [questo è quello che ho usato per scrivere questo articolo]
• MarkdownPad - ottimo editor Markdown per Windows
• Testi: un simpatico editor multipiattaforma (Mac e Windows); esporta in più formati come PDF, .doc ed ePub

Alcune delle principali piattaforme hanno già adottato (o almeno consentito) l'uso di Markdown nei loro editor per coloro che desiderano utilizzarlo. Con altri, come WordPress, Evernote e Google Docs, il supporto nativo (al momento della stesura di questo articolo) non è ancora integrato, ma sono state introdotte soluzioni personalizzate da terze parti. Questi includono:

• La nuova popolare piattaforma di blogging Ghost, alla ricerca di snellire la scrittura online, utilizza Markdown per il suo editor di contenuti.
• Per WordPress, il plug-in Jetpack ora supporta ufficialmente Markdown, che puoi abilitare in Impostazioni > Discussione se utilizzi il plug-in. Oppure potresti utilizzare un plug-in come WP-Markdown che converte il contenuto del markdown del tuo post in HTML e torna a Markdown quando è necessario modificarlo.
• Per Evernote, alcune app Markdown come l'editor online Markable o l'editor Mac Byword consentono l'esportazione e la pubblicazione direttamente nelle note. Oppure, se preferisci utilizzare direttamente l'app Web Evernote, puoi utilizzare un'estensione del browser chiamata Markdown Here che converte una nota selezionata scritta in Markdown in testo formattato con un clic del pulsante della barra degli strumenti.
• Google Docs non supporta ancora Markdown in modo nativo, ma alcuni editor (come StackEdit) esporteranno/sincroniranno direttamente con Drive.

Gli svantaggi

Naturalmente, con grande semplicità arrivano i limiti. Come ho già spiegato, Markdown non è stato scritto per complesse attività di elaborazione testi che richiedono funzionalità di formattazione avanzate. Se è quello che ti serve, Markdown non è lo strumento giusto.

Ma per gli sviluppatori che hanno bisogno di scrivere un manuale utente o documentazione tecnica o un rapporto tecnico, Markdown offre un equilibrio quasi perfetto tra semplicità e funzionalità di cui hai bisogno.

Forse il più grande svantaggio, specialmente per noi ingegneri che siamo fanatici del controllo delle modifiche, è l'incapacità di lavorare in modo collaborativo in Markdown e di tenere traccia delle modifiche (una notevole eccezione a questo, tuttavia, è il plug-in StackEdit per Google Docs). E, naturalmente, con uno sforzo minimo, si può semplicemente collaborare a un documento Markdown tramite un repository git e ottenere così tutto il monitoraggio delle modifiche e la collaborazione di cui si ha generalmente bisogno.

Conclusione

Quindi l'apprendimento di Markdown è per tutti? Ovviamente no. Nessuno strumento lo è mai stato.

Ma se sei un ingegnere del software, potrebbe benissimo essere proprio lo strumento di scrittura che stavi cercando. Quindi, se non l'hai ancora provato, dovresti davvero provarlo.