Ricerca nel sito web

I nostri linguaggi di markup preferiti per la documentazione


La documentazione è fondamentale per i progetti software open source. Abbiamo chiesto ai nostri contributori quale sia il loro linguaggio di markup preferito per la documentazione.

La documentazione è importante per tanti motivi. La documentazione leggibile lo è ancora di più. Nel mondo del software open source, la documentazione riguarda il modo in cui utilizzare o contribuire a un'applicazione. È come il regolamento di un gioco. 

Esistono molti tipi diversi di documentazione:

  • Tutorial

  • Guide pratiche

  • Guide di riferimento

  • Architettura del software

  • Manuali dei prodotti

Abbiamo chiesto ad alcuni contributori di Opensource.com informazioni sul flusso di lavoro della documentazione tecnica, quale linguaggio di markup preferiscono e perché potrebbero utilizzarne uno rispetto all'altro. Ecco cosa avevano da dire.

AsciiDoc

Negli ultimi anni, Markdown è stato il mio linguaggio standard. Ma recentemente ho deciso di provare AsciiDoc. La sintassi non è difficile e Gedit sul mio desktop Linux la supporta. Ho intenzione di mantenerlo per un po'.

—Alan Formy-Duval

In termini di markup a bassa sintassi, preferisco AsciiDoc. Mi piace perché il suo processo di conversione è coerente e prevedibile, senza variazioni di "sapore" a sorpresa che possano confondere le cose. Mi piace anche il fatto che venga inviato a Docbook, che è una sintassi ricca di markup di cui mi fido per la longevità e la flessibilità.

Ma la scelta "giusta" tende ad essere ciò che un progetto sta già utilizzando. Non scriverei in AsciiDoc se un progetto utilizza Markdown al gusto di fragola. Beh, per essere onesti, potrei scrivere in AsciiDoc e poi convertirlo in Markdown al gusto di fragola con Pandoc.

Penso che ci sia un tempo e un luogo per Markdown. Lo trovo più leggibile di AsciiDoc. Link in AsciiDoc:

http://example.com[Example website]

 Collegamenti in Markdown:

[Example.com](http://example.com)

La sintassi di Markdown è intuitiva e fornisce le informazioni nello stesso modo in cui penso che la maggior parte di noi analizzi gli stessi dati durante la lettura dell'HTML ("Sito web di esempio...oh, è testo blu, ci passo sopra per vedere dove va... va a example.com").

In altre parole, quando il mio pubblico è un lettore umano, scelgo spesso Markdown perché la sua sintassi è sottile ma ha una sintassi sufficiente per rendere possibile la conversione, quindi è comunque un formato di archiviazione OK.

AsciiDoc, per quanto minimale, sembra semplicemente più spaventoso.

Se il mio pubblico è un computer che analizzerà un file, scelgo AsciiDoc.

—Seth Kenlon

testo ristrutturato

Sono un grande fan dei documenti come codice e del modo in cui porta gli strumenti di sviluppo nei flussi di lavoro dei contenuti. Rende più semplice avere revisioni e collaborazione efficienti, soprattutto se i contributori sono ingegneri. 

Sono anche un po' un intenditore di markup, avendo scritto interi libri in AsciiDoc per O'Reilly, molti Markdown per varie piattaforme, inclusi un migliaio di post sul mio blog. Attualmente sono un convertito di reStructuredText e mantengo alcuni degli strumenti in quello spazio. 

—Lorna Mitchell

Menzione obbligatoria di reStructuredText. Questo è il mio punto di riferimento in questi giorni poiché faccio molta programmazione Python. È stato anche lo standard di Python per la documentazione sorgente e i commenti sul codice per anni.

Mi piace il fatto che non soffra così tanto della proliferazione di non standard come fa Markdown. Detto questo, utilizzo molte funzionalità ed estensioni di Sphinx quando lavoro su documentazione più complessa.

—Jeremy Stanley

HTML

Uso raramente i linguaggi di markup se non è necessario.

Trovo però che l'HTML sia più facile da usare rispetto ad altri linguaggi di markup.

—Rikard Grossman-Nielsen

Per me, ci sono vari modi per creare documentazione. Dipende da dove si troverà la documentazione: su un sito web, come parte del pacchetto software o qualcosa di scaricabile.

Per Scribus, la documentazione interna è in HTML, poiché per accedervi viene utilizzato un browser interno. Su un sito web, potrebbe essere necessario utilizzare una lingua Wiki. Per qualcosa di scaricabile potresti creare un PDF o un EPUB.

Tendo a scrivere la documentazione in un editor di testo semplice. Potrei usare XHTML, in modo da poter poi importare questi file in un produttore di EPUB come Sigil. E, naturalmente, Scribus è la mia app preferita per creare un PDF, anche se probabilmente importerei un file di testo creato con un editor di testo. Scribus ha il vantaggio di includere e controllare con precisione il posizionamento della grafica.

Markdown non mi ha mai preso piede e non ho mai provato AsciiDoc.

—Greg Pittman

Sto scrivendo molta documentazione in HTML in questo momento, quindi inserirò un plug-in per HTML. È possibile utilizzare HTML per creare siti Web o documentazione. Tieni presente che i due non sono proprio la stessa cosa: quando crei siti Web, la maggior parte dei designer si preoccupa della presentazione. Ma quando scrivi documentazione, gli scrittori tecnologici dovrebbero concentrarsi sui contenuti.

Quando scrivo la documentazione in HTML, mi attengo ai tag e agli elementi definiti dall'HTML e non mi preoccupo di come apparirà. In altre parole, scrivo la documentazione in HTML "senza stile". Posso sempre aggiungere un foglio di stile in seguito. Quindi, se ho bisogno di rendere più forte una parte del testo (come un avvertimento) o aggiungere enfasi a una parola o frase, potrei utilizzare i tag e , in questo modo:

<p><strong>Warning: Lasers!</strong> Do <em>not</em> look into laser with remaining eye.</p>

Oppure, per fornire un breve esempio di codice all'interno del corpo di un paragrafo, potrei scrivere:

<p>The <code>puts</code> function prints some text to the user.</p>

Per formattare un blocco di codice in un documento, utilizzo

< span style=" background-color:#f3f3f3">.. 
in questo modo:

void
print_array(int *array, int size)
  {
  for (int i = 0; i < size; i++) {
  printf("array[%d] = %d\n", i, array[i]);
  }
}

Il bello dell'HTML è che puoi visualizzare immediatamente i risultati con qualsiasi browser web. E tutta la documentazione che scrivi in HTML senza stile può essere resa più bella in seguito aggiungendo un foglio di stile.

—Jim Hall

Inaspettato: LibreOffice

Negli anni '80 e '90, quando lavoravo su System V Unix, SunOS e infine Solaris, utilizzavo le macro mm con nroff, troff e infine groff< /codice>. Leggi informazioni su MM utilizzando groff_mm (a condizione che tu li abbia installati.)

MM non è realmente un linguaggio di markup, ma sembra tale. È un insieme molto semantico di macro troff e groff. Contiene la maggior parte delle cose che gli utenti del linguaggio di markup si aspetterebbero: intestazioni, elenchi numerati e così via.

Sulla mia prima macchina Unix era disponibile anche Writers' Workbench, il che è stato un vantaggio per molti nella nostra organizzazione che dovevano scrivere rapporti tecnici ma non scrivevano in modo particolarmente "coinvolgente". Alcuni dei suoi strumenti sono arrivati a BSD o Linux: stile, dizione e aspetto.

Ricordo anche uno strumento SGML (Generalized Markup Language) standard fornito con, o forse acquistato per, Solaris all'inizio degli anni '90. L'ho usato per un po', il che potrebbe spiegare perché non mi dispiace digitare il mio codice HTML.

Ho usato Markdown un bel po', ma detto questo, dovrei anche dire "quale Markdown", perché ci sono infiniti gusti e livelli di funzionalità. Per questo motivo non sono un grande fan di Markdown. Immagino che se avessi molto Markdown da fare probabilmente proverei a gravitare verso qualche implementazione di CommonMark perché in realtà ha una definizione formale. Ad esempio, Pandoc supporta CommonMark (così come molti altri).

Ho iniziato a utilizzare AsciiDoc, che preferisco di gran lunga a Markdown poiché evita la conversazione "quale versione stai utilizzando" e fornisce molte cose utili. Ciò che mi ha rallentato in passato rispetto ad AsciiDoc è che per qualche tempo sembrava richiedere l'installazione di Asciidoctor, una toolchain Ruby che non ero ansioso di installare. Ma al giorno d'oggi ci sono più implementazioni almeno nella mia distribuzione Linux. Curiosamente Pandoc emette AsciiDoc ma non lo legge.

Quelli di voi che ridono di me perché non voglio una toolchain Ruby per AsciiDoc ma mi accontento di una toolchain Haskell per Pandoc… vi capisco.

Arrossisco nell'ammettere che oggigiorno utilizzo principalmente LibreOffice.

—Chris Hermansen

Documentati ora!

La documentazione può essere ottenuta attraverso molte strade diverse, come hanno dimostrato gli autori qui. È importante documentare come utilizzare il codice, soprattutto in open source. Ciò garantisce che altre persone possano utilizzare e contribuire correttamente al tuo codice. È anche saggio dire ai futuri utenti cosa fornisce il tuo codice. 

Articoli correlati: