Haroopad, coltellino svizzero per Documentazione in Markdown

Eccomi qui, nuovamente su questi schermi per parlarvi, come al solito, di esperienze vissute in prima persona. L'argomento di oggi non è prettamente tecnico ma ti permetterà di migliorare un aspetto della tua professione: la documentazione!

Oggi ti presenterò uno strumento che ultimamente ho iniziato a sfruttare maniacalmente nel mio lavoro e per maniacalmente indendo, usarlo a fondo e sentirne la mancanza quando non è a disposizione. Di strumenti di questo genere ne ho provati moltissimi prima di arrivare a lui e per questo, lo ammetto, me ne sono innamorato. Come mi succede con tutte le mie infatuazioni che mi rendono schiavo, ora mi costringe ad usarlo giorno e notte per fare le cose più disparate, tra le quali ho trovato un buco per scriverci sopra questo articolo.

E infatti devo confessarti che questo articolo è proprio il frutto di questa mia passione. L’intero articolo è stato scritto in markdown in Haroopad emi è bastato un semplice copia/incolla per vedere il risultato all’interno di html5AndMore.

Ti ho incuriosito abbastanza? Credo proprio sia giunto il momento di presentartelo.

Ti presento il mio nuovo “amico di penna”.

Questa battuta era pessima, lo so, ma sono stato parecchio tempo a cercare di capire la razza del pennuto ritratta nel logo di questo programma coreano e ora mi si è fuso il cervello. L’unica cosa che sappiamo però è che Haroo significa “Un giorno”, come tiene a ricordarci il programmatore tramite il pannello preferenze.

haroopad-origine-nome

Torniamo alle cose serie e iniziamo a parlare del Markdown, questo modo di scrivere testo semplice, o più comunemente plain text, che piace tanto a noi geek.

Prima di proseguire ti consiglio di scaricare questo editor e di installarlo nel tuo computer, in questo modo potrai testare dal vivo le caratteristiche che man mano ti presenterò.

Il markdown è stato ideato per scrivere senza alzare mai le mani dalla tastiera e già solo per questo sforzo produttivo dovremmo tutti abbandonare strumenti di scrittura obsoleti e distrattivi, sopratutto quelli pieni di funzioni che prendono senso solo in fase di formattazione e che arrecano danno nel momento della “creatività” con tutti quei bottoni da premere, campi da riempire e menù da imparare (qualcuno ha detto Word?)!

Altra motivazione più che valida è che, specialmente tu lettore di AndMore, tutti i readme e wiki dei repository più famosi di software utilizzano questa sintassi per permetterti di caricare la tua documentazione. Anche WordPress sul suo repository di plugin e temi accetta una sua forma ridotta di markdown.

Essendomi spostato molto su BitBucket, ultimamente ho iniziato a spulciare tutte le aree del sito disponibili agli sviluppatori e ho scoperto che non potrei vivere senza markdown. Sarebbe impossibile pianificare i changelog e le milestone, scrivere una wiki, formattare il testo nelle issue, inserire link o referenze e sopratutto scrivere un readme decente.

Da lì ad adottarlo per ogni cosa, il passo è stato brevissimo e ora che ho trovato un editor veramente soddisfacente anche su Linux (si, son pinguino e non me ne vergogno) ci scrivo tutti gli articoli, persino questo!

haroopad

Ora che sai perché è utile il Markdown, Scopri perché mi piace tanto Haroopad

Iniziamo con il dire che è multi-piattaforma, quindi tutti possono utilizzarlo sul proprio PC o Mac, e questo per me è importantissimo perché come ormai saprai, da utente Linux mi trovo spesso a differire dai miei colleghi per parco software e quindi di studiare e discutere su strumenti diversi anche per raggiungere lo stesso risultato. Con Haroopad tutti parlano Markdown e possono avere le stesse feature su tutte le macchine, indipendentemente dal SO che montano.

La seconda cosa, la più ovvia di tutte, è la split-view tra Editor e Anteprima. Dico la più ovvia perchè in effetti ce l’hanno quasi tutti i concorrenti, ma in alcuni l’ho trovata sostituita immodificabilmente da un bottone “Visualizza anteprima” che apriva una finestra a parte in cui bisognava ricaricare ogni volta che si modificava qualcosa. Questa visualizzazione, oltretutto, è resa molto elastica dalle miriadi di personalizzazioni che vi si possono applicare.

Qui entra in gioco la terza nota positiva, ovvero Haroopad è personalizzabile tramite template CSS. Hai capito bene, con poche righe di CSS puoi creare template di anteprima simili (nella tipografia base) ai siti su cui stai pubblicando il contenuto, oppure puoi affidarti ai diversi template già esistenti che rispecchiano diverse interfacce utili come Github, Bitbucket, MediaWiki e altri siti dove è sistematico l’uso di questa sintassi.

Io in questo momento sto scrivendo con il template di AndMore attivo e riesco perfettamente ad immaginare come verrà fuori l’articolo lavorando in locale, comodo no?

haroopad-temi

L’interfaccia è minimale e non ci deconcentra, gli elementi sono pochi e veramente chiari. Ad esempio, le uniche cose veramente visibili nell’area dell’editor (l’area dove ci concentriamo durante la scrittura) sono:

  • il numero di righe scritte,
  • il numero di parole totali,
  • il numero di riga
  • e il numero di parole selezionate.

In realtà ci sono altre due aree nascoste di default che permettono, al passaggio del mouse o cliccando, di attivare il riassunto degli elementi dell’articolo come numero di intestazioni, di paragrafi e di immagini nel documento oppure di richiamare al volo la guida rapida alla sintassi markdown (pulsante azzurro).

haroopad-conteggio-parole

Ovviamente non poteva mancare il supporto al multimarkdown e al GitHub flavored markdown che permettono di inserire ulteriori elementi nei nostri testi.

Oltre alle varie opzioni avanzate per la formattazione del codice ci sono anche feature serie per l’embedding di contenuti multimediali, come video da sorgenti esterne (YouTube e Vimeo ad esempio), Tweet, rimandi a Wikipedia, tracce da SoundCloud, codice da pastebin, foto da Flickr, presentazioni da Slideshare e persino immagini da Instagram. Mi è bastato usare lo speciale tag @(http://linkalvideo.com) per inserire comodamente il video introduttivo in questo articolo e la cosa ancor più bella è che nello stesso identico modo avrei potuto inserire parecchie altre cose.

Altra feature interessante è quella non solo di esportare i documenti in HTML e in PDF ma anche di poterli direttamente inviare via e-mail. Perché è così importante questa cosa? Se conosci servizi come Tumblr, Evernote o WordPress nella sua versione self-hosted? Sai che è possibile inviare articoli e publicarli direttamente verso una casella email specifica. Ritengo che questa sia una caratteristica fantastica perché mi permette di scrivere i miei articoli senza la necessità di disturbare il backend di WordPress!

Haroopad ci permette (e promette al più presto compatibilità completa e dichiarata anche con WordPress in tutte le salse) di inviare via mail con password tutto il testo in formato HTML o markdown puro; così da poter pubblicare una nota, un articolo o magari dare il via ad una ricetta di IFTTT.

Siamo quindi pronti a perdonargli la traduzione italiana piuttosto fantasiosa da e-mail a e-pistola.

haroopad-invia-email

Scrivi formule matematiche e senti il bisogno di LaTex?

Non c’è problema perché Haroopad integra la libreria MathJax che ti permetterà di vedere renderizzata subito ogni formula, anche la più complessa. Questa feature va abilitata nelle impostazioni come anche quella per aggiungere le note a piè pagina in caso di necessità e di default è disabilitata.

Conclusioni

È giunto il momento di iniziare a sperimentare con questo utilissimo strumento ma prima di lasciarti andare volevo rivedere con te i motivi che mi hanno spinto a parlare di questo strumento. Per prima cosa perché ho notato sulla mia pelle che utilizzare la sintassi Markdown velocizza la creazione dei tuoi testi in fin dei conti, proprio come ti annunciavo precedentemente, permette di non alzare mai le mani dalla tastiera.

Se ci pensi per un attimo questa è una cosa incredibilmente utile perché nel 90% dei casi (forse anche di più), quando scriviamo non vogliamo andare a cercare il nostro mouse, trovare il cursore sullo schermo e raggiungere il pulsante che ci serve; questa è un’inutile perdita di tempo che mi ha portato ad utilizzare editor di codice come Atom o Sublime Text.

Non dover perdere tempo a cercare gli strumenti ci permette di focalizzare la nostra mente soltanto sulla creazione del materiale.

Poi le varie integrazioni e la possibilità di avere una preview dal vivo, proprio come successo con BrowserSync, permette di avere un’esperienza utente del tutto immersa senza dover perdere tempo ad aspettare le modifiche.

Insomma ho scritto questo articolo perché da diverso tempo uso Markdown e ritengo questo strumento un must have nel tuo arsenale ma al tempo stesso sono curioso di sapere da te quale programma utilizzi per scrivere in questa sintassi e perché lo hai scelto.

Quindi non esitare oltre e sfrutta la sezione dei commenti per condividere le tue esperienze, abbiamo tutti da scoprire qualcosa da esse!

 

Lascia il tuo Pensiero