VuePress: documentazione semplificata

Quando si tratta di qualsiasi progetto che richiede l'interazione dell'utente (ad es. utenti finali, manutentori, ecc.), c'è un fattore critico che fa la differenza tra successo e fallimento: una buona documentazione. Questo vale indipendentemente da quanto piccolo o grande sia il tuo progetto. Dopotutto, oltre a fornire supporto individuale per il tuo progetto, la documentazione è la prima linea di difesa per gli utenti che stanno cercando di risolvere un problema. E che ti piaccia o no, non sentirai mai gli utenti che si arrendono dopo essere stati incapaci di risolvere il loro problema a causa di una documentazione inadeguata.

Le sfide della creazione di una buona documentazione

Quando si tratta di scrivere una buona documentazione, ci sono quattro problemi ricorrenti che i team incontrano spesso:

1. La documentazione è spesso obsoleta.
   Sebbene nessuna documentazione per un progetto possa essere un'esperienza frustrante, è probabilmente peggio avere una documentazione obsoleta . Dopotutto, lo scopo della documentazione è fornire agli utenti un corpus ufficiale di conoscenze su cui possono fare affidamento. Quando non è aggiornato, gli utenti stanno perdendo tempo e alla fine perdono fiducia nel tuo prodotto.
   
   Il motivo principale per cui la documentazione diventa obsoleta è che la manutenzione della documentazione è separata dalle modifiche al codice . Senza investire molto tempo ed energia, questo può essere difficile da risolvere perché:
   
   1. La documentazione di solito risiede in un servizio di terze parti come Confluence o Wiki,
   2. Gli sviluppatori sono in genere più interessati a scrivere codice che a documentazione.
2. Gli utenti non sono in grado di fornire facilmente feedback.
   Non importa quanto ritieni buona la tua documentazione, alla fine non ha senso senza testarla con utenti reali che possono fornire feedback. Come accennato in precedenza, un pregiudizio comune quando si valuta l'efficacia di cose come la documentazione è non tenere conto degli utenti che non sono stati in grado di risolvere i loro problemi e si sono arresi. Poiché nessun team sarebbe mai in grado di tenere conto di ogni scenario su come gli utenti potrebbero utilizzare il tuo prodotto, gli utenti devono disporre di un modo semplice e affidabile per fornire feedback.
3. La documentazione viene spesso scritta da utenti esperti per utenti esperti.
   Il difetto dell'utilizzo di strumenti standard come wiki o file README è che spesso si rivolgono solo a un insieme specifico di utenti che spesso hanno una conoscenza preesistente della libreria e/o dello stack tecnologico. Di conseguenza, è abbastanza semplice per loro navigare nello spazio e trovare ciò di cui hanno bisogno. Tuttavia, i nuovi utenti non hanno questa conoscenza preliminare e quindi spesso richiedono un'esperienza molto più coinvolgente per coinvolgerli.
   
   Esempi di questo includono:
   
   • Un sito web ben progettato,
   • capacità di ricerca,
   • Navigazione laterale guidata,
   • Metainformazioni facilmente identificabili (ad es. data dell'ultimo aggiornamento),
   • Contenuti coinvolgenti che si estendono oltre un muro di testo difficile da comprendere facilmente.
4. Infrastrutture scadenti che rendono difficile la manutenzione della documentazione.
   Come se scrivere una buona documentazione comprensibile per gli utenti non fosse già abbastanza difficile, la facilità con cui uno sviluppatore può scrivere e/o mantenere la documentazione è fondamentale per la sua fattibilità a lungo termine. Quindi, per ogni ulteriore barriera che gli sviluppatori devono affrontare per scrivere e/o mantenere la documentazione, più è probabile che alla fine fallisca. Di conseguenza, è fondamentale che l'esperienza di creazione e la manutenzione di qualsiasi documentazione siano il più semplici e coinvolgenti possibile.

Se solo ci fosse uno strumento che potesse fare tutte queste cose per noi...

Entra in VuePress

Quando si sente parlare per la prima volta di VuePress, si potrebbe essere tentati di indovinare che si tratta di una fusione di Vue.js e WordPress. Invece, dovresti pensare a VuePress come:

Vue.js + Macchina da stampa

Perché in fondo VuePress è un generatore di siti statici!

Alcuni di voi potrebbero pensare: "Aspetta. Un altro generatore di siti statici? Qual è il problema?"

Sebbene esistano numerosi strumenti che sono generatori di siti statici, VuePress si distingue dal pacchetto per un unico motivo: la sua direttiva principale è rendere più facile per gli sviluppatori creare e mantenere un'ottima documentazione per i loro progetti.

Perché VuePress è così potente per la creazione di documentazione?

La risposta è semplice. È stato progettato con un obiettivo in mente: aiutare gli sviluppatori a creare ottimi siti di documentazione mantenendo un'esperienza di creazione divertente. Ciò significa che fornisce un framework per gli sviluppatori per:

• Crea bellissimi siti di documentazione,
• Vieni con funzionalità predefinite essenziali per tutti i siti di documentazione,
• Ottimizza l'esperienza di creazione per semplificare l'aggiornamento di un file Markdown.

VuePress può coesistere con la tua codebase esistente

Questo è uno dei motivi principali per cui lo consiglio vivamente. Quando si tratta di mantenere la documentazione, un modo per garantire che non sia aggiornata è rendere difficile agli sviluppatori l'aggiornamento dei documenti durante la scrittura del codice. Se rendi difficile l'esperienza di creazione costringendo gli sviluppatori ad aggiornare le cose in due posti diversi, ciò causerà molti attriti e spesso si tradurrà in una documentazione abbandonata nel dimenticatoio. Questo è comunemente visto quando gli sviluppatori devono mantenere uno strumento di terze parti come un wiki, oltre alla base di codice stessa.

Poiché è un generatore di siti statici, ciò significa che può risiedere nello stesso repository esatto del tuo codice.

Come puoi vedere in questa struttura di app Web di esempio, il tuo codice risiederebbe normalmente nella directory src , ma avresti semplicemente una directory docs per contenere tutta la documentazione. Ciò significa che ottieni i vantaggi di:

• Tutta la documentazione è ora controllata dalla versione;
• Le richieste pull ora possono contenere sia la documentazione che le modifiche al codice;
• Creazione di script separati per l'esecuzione simultanea di istanze locali del codice e dei documenti;
• Utilizza le pipeline di compilazione per determinare se le nuove distribuzioni del sito di documentazione sono sincronizzate con le distribuzioni del codice o meno.

Il tema predefinito viene fornito con la configurazione standard

Scrivere la documentazione è già abbastanza difficile così com'è, quindi VuePress scarica molte delle decisioni che normalmente si devono prendere e ha un sacco di impostazioni predefinite integrate per semplificare la tua esperienza di creazione:

• La scrittura dei contenuti viene eseguita principalmente con Markdown.
  Ciò significa che puoi sfruttare la tua conoscenza esistente della sintassi di Markdown per modellare e formattare il tuo testo.

• Evidenziazione della sintassi del codice.
  Se stavi costruendo un sito da solo, dovresti lottare con le librerie di evidenziazione della sintassi dei colori. Ma sei fortunato perché puoi aggiungere blocchi di codice in VuePress è così facile poiché tutto è pronto per l'uso con zero configurazione.

• In primo piano per la definizione dei metadati a livello di pagina.
  Anche se stai creando un file Markdown, puoi utilizzare l'argomento (come YAML, JSON o TOML) per definire i metadati per la tua pagina per rendere ancora più semplice la gestione dei tuoi contenuti!

 --- title: Document Like a Pro lang: en-US description: Advice for best practices tags: - documentation - best practices ---

• Contenitori Markdown personalizzati.
  Nel caso non lo sapessi, Markdown ha estensioni per aggiungere scorciatoie ancora più utili per creare bellissimi componenti dell'interfaccia utente come contenitori personalizzati. E poiché sono così utili nella documentazione, VuePress lo ha già configurato in modo da poterlo utilizzare immediatamente:

Funzionalità di ricerca integrata

Affrontiamolo. Non importa quanto tempo dedichiamo a scrivere un'ottima documentazione, alla fine sarà inutile se gli utenti non riescono a trovarla. Ci sono generalmente due approcci a questo:

1. Attendi che i robot dei motori di ricerca eseguano lentamente la scansione del tuo sito nella speranza che un giorno i tuoi utenti possano trovare la pagina giusta sul tuo sito. Non è un'ottima soluzione.
2. Crea la tua funzionalità di ricerca, ma può essere difficile da implementare per i siti statici poiché non c'è codice lato server in esecuzione per creare indici di ricerca ed eseguire le ricerche. Per non parlare del fatto che questo sta sottraendo tempo di sviluppo al prodotto stesso. Quindi neanche questo è eccezionale.

Fortunatamente per noi, VuePress è qui per salvare la situazione ancora una volta!

VuePress viene fornito con una funzionalità di ricerca integrata che genera il proprio "motore di ricerca" - avete letto bene. Senza alcuna configurazione o configurazione aggiuntiva del database, VuePress è configurato per raschiare tutti i tuoi documenti per generare un semplice motore di ricerca che farà emergere tutti i tuoi h1 e h2 al tuo utente.

Ora, alcuni di voi potrebbero pensare,

"E se volessi qualcosa che fornisca un'indicizzazione di livello inferiore per la ricerca?"

Bene, VuePress ha coperto anche te perché è progettato per integrarsi facilmente con Algolia DocSearch che può fornirti quella funzionalità gratuitamente se soddisfi i loro requisiti:

La navigazione nella barra laterale è semplice come attivare o disattivare la funzione

Per chiunque sia mai stato responsabile della gestione dei contenuti, sai quanto può essere complicato creare una barra laterale con elementi nidificati e quindi tenere traccia della posizione in cui si trova il lettore mentre scorre verso il basso. Quindi, perché dedicare del tempo a questo quando potresti scrivere documenti migliori? Con VuePress, la barra laterale è semplice come attivare la prima pagina di una pagina:

Generazione automatica di importanti metadati comunemente trascurati

Una delle cose più frustranti che un utente può incontrare è la documentazione non aggiornata. Quando un utente segue i passaggi e ha difficoltà a capire perché qualcosa non funziona, essere in grado di scoprire facilmente la data dell'ultimo aggiornamento può essere incredibilmente utile sia per l'utente che per i manutentori del progetto.

Con una semplice configurazione, VuePress può garantire l'output automatico della data dell'ultimo aggiornamento sulla pagina in modo che i tuoi utenti sappiano sempre l'ultima volta che è stato aggiornato.

Inoltre, con un po' di configurazione, VuePress rende anche incredibilmente facile per gli utenti contribuire ai tuoi documenti generando automaticamente un collegamento nella parte inferiore di ogni singola pagina che consente agli utenti di creare facilmente una richiesta pull ai tuoi documenti.

Non è molto più facile di così per i tuoi utenti.

Distribuzione su qualsiasi sito di hosting statico

Poiché VuePress è un generatore di siti statici al suo interno, ciò significa che puoi implementarlo su qualsiasi piattaforma di hosting popolare come:

• Netlizzare
• Pagine GitHub
• Pagine GitLab
• Eroku
• Adesso

Tutto ciò che devi fare per creare il sito è eseguire vuepress build {{ docsDir }} con dove risiede la tua directory e avrai tutto ciò di cui hai bisogno per distribuirlo live sul web!

Nota : per guide più approfondite su come eseguire questa operazione, consulta le guide di distribuzione ufficiali per VuePress.

Sfruttare Vue all'interno del tuo file Markdown

Lo so, lo so. Possiamo usare Vue.js nel nostro Markdown?! Sì, avete letto bene! Sebbene tecnicamente facoltativo, questo è probabilmente uno degli aspetti più interessanti di VuePress perché ti consente di migliorare i tuoi contenuti Markdown come non sei mai stato in grado di fare prima.

Definisci i dati ripetitivi in ​​un unico posto e aggiornali ovunque con l'interpolazione

Nell'esempio seguente, vedrai un breve esempio di come puoi sfruttare le variabili locali (come quelle definite nel frontmatter) e quelle definite globalmente (come il titolo del sito):

 --- title: My Page Title author: Ben Hong --- # {{ $page.title }} Welcome to {{ $site.title }}! My name is {{ $page.author }} and I'll be your guide for today!

Usa i componenti Vue all'interno di Markdown

Ti darò un momento per riprenderti dopo aver letto questo, ma sì, i componenti Vue live con un'istanza Vue completa possono essere tuoi se vuoi! La configurazione richiederà un po' più di lavoro, ma è prevedibile poiché stai creando contenuto personalizzato che verrà eseguito nella documentazione.

Ecco un rapido esempio di come apparirebbe un componente Counter in un file Markdown:

Questa è forse la parte più potente della personalizzazione disponibile per la documentazione poiché significa che ora hai la libertà di creare contenuti personalizzati che va ben oltre le capacità di Markdown standard. Quindi, che si tratti di una demo o di un codice interattivo, le idee sono infinite!

Prossimi passi

Se desideri creare un bellissimo sito di documentazione per consentire ai tuoi utenti di imparare a utilizzare il tuo prodotto, non è molto più semplice di VuePress. E anche se potrebbe essere facile presumere che VuePress debba essere utilizzato solo da progetti che utilizzano Vue.js, questo non potrebbe essere più lontano dalla verità. Ecco solo alcuni esempi dei diversi tipi di progetti che sfruttano VuePress per i loro siti di documentazione:

• CMS artigianale
• UmiJS (che è costruito per React)
• openHAB
• Pavone

Alla fine della giornata, indipendentemente dal fatto che utilizzi VuePress o meno, spero che questo ti abbia aiutato a ispirarti a creare una documentazione migliore per i tuoi utenti.

Ulteriori risorse

Ci sono molte cose interessanti che non ho trattato qui in questo articolo (ad esempio temi, blog e così via), ma se vuoi saperne di più, dai un'occhiata a queste risorse:

• Documenti VuePress ufficiali
• Un elenco curato di risorse correlate a VuePress
• Galleria VuePress
• Blog VuePress Boilerplate