Documentazione del prodotto per i professionisti di WordPress

Pubblicato: 2017-07-28

La documentazione del prodotto è generalmente vista come irrilevante, che puoi tagliare gli angoli. Non è visto come qualcosa che può offrire valore al cliente, o come qualcosa che potrebbe influenzare aree di business chiave come le entrate e il marketing. Certo, come professionista di WordPress non avrai bisogno di scrivere documentazione allo stesso modo di Atlassian o Cisco. Di solito, quando le persone pensano alla "documentazione" evocano immagini di spesse guide per l'utente stampate, indicizzate in ordine alfabetico su uno scaffale molto grande che nessuno legge mai.

Ma questo è cambiato:

Con l'avvento di Agile e DevOps, il software di spedizione è diventato più veloce e anche il ciclo di sviluppo è diventato più dinamico. E di conseguenza, la documentazione ora riflette lo stato attuale nella versione più recente, invece di essere qualcosa di statico scritto su carta per sempre. La documentazione è integrata nel ciclo di sviluppo e viene aggiornata con la stessa frequenza del software.

Perché i professionisti di WordPress dovrebbero preoccuparsi della documentazione del prodotto?

Una documentazione utile e aggiornata non solo semplifica la vita dei tuoi utenti, ma aggiunge anche un livello di raffinatezza che diventa una risorsa di marketing come nessun altro. Al contrario, una scarsa documentazione ha un impatto negativo. Probabilmente l'hai sperimentato tu stesso: hai avuto un problema per il quale stavi cercando di trovare la soluzione nella documentazione e quando non l'hai fatto sei finito frustrato (e probabilmente arrabbiato). Peggiora solo se stai pagando per il prodotto.

Se lavori in un'agenzia WordPress, fornire documentazione in tutte le aree di un progetto, dalla progettazione iniziale alle risorse, aggiungerà un livello di professionalità che dimostra che:

Fai attenzione ai dettagli.
Ti preoccupi del tuo cliente abbastanza da fare il possibile.
Sei trasparente e sicuro delle tue decisioni di progettazione e di progetto tecnico.

Mike Puterbaugh, VP Marketing di MindTouch ha scritto un articolo di Mashable che descrive i 5 motivi per cui la documentazione del tuo prodotto è una risorsa di marketing. Ha concluso con quanto segue:

Non è un'impresa sexy, ma ti farà guadagnare il rispetto dei tuoi colleghi, una gestione aziendale più efficace e un team più collaborativo. Perché non si tratta di questo trimestre o di quest'anno, ma piuttosto di influenzare il vantaggio competitivo e la crescita a lungo termine.

Ora che abbiamo stabilito una motivazione sufficiente, faremo:

Esplora i diversi tipi di documentazione del prodotto rilevanti per WordPress.
Discutere le esigenze di ciascun tipo di documentazione e offrire consigli utili.
Offri alcune indicazioni iniziali su come pianificare e collaborare alla documentazione del prodotto. Soprattutto se lavori presso un'agenzia WordPress.

Tipi di documentazione del prodotto WordPress

Un prodotto WordPress non riguarda solo plugin e temi. In questa sezione discuteremo anche della guida in linea, delle API REST e di una cosa curiosa chiamata microcontenuto.

Plugin WordPress

La documentazione del plugin di WordPress deve soddisfare due folle: utenti e sviluppatori. Le esigenze di documentazione di ciascuno sono diverse, così come lo stile di scrittura utilizzato.

Utenti

Le esigenze di documentazione degli utenti ruotano principalmente attorno alla risoluzione dei problemi e alla configurazione. Aggiungi a questo che devi presentare il tuo plug-in in modo attraente in modo da convincere gli utenti a provarlo. Ogni plugin ha una propria pagina nel mercato dei plugin di WordPress. Tieni a mente i seguenti punti:

Scrivi una descrizione convincente e utile che incoraggi il download e l'uso.
Aggiungi screenshot annotati dalla pagina di configurazione del plug-in Dashboard con le descrizioni.
Metti nelle FAQ domande utili e non banali.
Avere un Changelog aggiornato e ben scritto. Non aggiungere note criptiche o concise lì.

Dovresti ricordare che quando gli utenti utilizzano la documentazione, probabilmente hanno fretta e sono ansiosi di trovare una soluzione. Scrivi in modo chiaro, semplice e conciso. Non renderlo più difficile per loro di quanto non lo sia già.

Sviluppatori

Oltre a seguire le migliori pratiche software e gli standard di codifica PHP ufficiali, dovresti concentrare la tua attenzione sulle seguenti aree:

hook di plugin

Questi fanno il lavoro di modificare il comportamento di WordPress. Molto probabilmente il tuo plugin per WordPress li usa. Poiché gli hook dei plugin sono una parte importante del codice, dovresti documentare come li usi e in quali funzioni di WordPress sono coinvolti.

tag modello

I tag modello sono un altro modo in cui un plugin di WordPress può migliorare la funzionalità. Documenta le funzioni dei tag del modello che hai scritto. Includi esempi su come altri utenti o sviluppatori possono utilizzare i tag sul loro sito WordPress.

opzioni

Le opzioni sono un modo per archiviare particolari informazioni in un database WordPress. Questo viene fatto tramite le funzioni add_option e get_options. In questo caso, documentate i parametri che passate a queste funzioni.

Banca dati

I plugin spesso leggono e scrivono molte cose diverse da un database. Poiché si tratta di operazioni fondamentali, documentarle aiuterà notevolmente gli altri sviluppatori a capire come funziona il tuo plugin.

Temi WordPress

Esistono due diverse aree in cui è possibile creare documentazione per i temi. Il primo sono i file di origine. I file CSS commentati sono più facili da capire e leggere rispetto a quelli senza. Usa uno strumento come css_doc per aiutarti. Questo genera uno stile di documentazione JavaDoc e può essere pubblicato:

L'altra area è Guide di stile. Questi documenti descrivono come devono apparire gli elementi e in quali casi devono essere utilizzati. Rafforzano la coerenza e facilitano anche la collaborazione. Puoi leggere l'articolo delle guide di stile del marchio su 20 splendidi esempi di Hubspot in quanto contiene molti ottimi esempi.

Ancora una volta, non dimenticare di consultare gli standard di codifica CSS ufficiali di WordPress.

Documentare gli elementi di design in modo così dettagliato aiuta anche l'onboarding di nuovi dipendenti se sei un'agenzia WordPress. Le guide di stile possono essere utilizzate come tutorial o materiale di riferimento per il lavoro dei clienti nuovi e passati.

Aiuto online

Poiché la guida in linea mira a risolvere un particolare problema dell'utente, iniziare con un elenco di attività e problemi comuni è la strada da percorrere. Anche se all'inizio l'elenco non sarà esaustivo, prenditi il tempo necessario per produrre quanti più oggetti concreti possibile. L'idea è di scrivere un file della guida in linea per ciascuna di queste attività e problemi e collegarli a informazioni correlate. Puoi creare percorsi utente per mappare i diversi percorsi che un utente può intraprendere e fare all'interno della tua applicazione. Immergersi nelle e-mail di supporto per notare domande comuni e aree problematiche è un buon modo per mantenere la tua base di conoscenze aggiornata e utile.

Barry J. Rosenberg, autore di Spring into Technical Writing, offre i seguenti consigli per scrivere buoni file di aiuto:

Mantieni ogni file della guida il più breve possibile. Preferisci gli elenchi numerati agli elenchi puntati. Non divagare, non fare note a piè di pagina e non volere. Mantieni ogni file della guida concentrato su una singola attività distinta.

Microcontenuto

Il microcontenuto ha due definizioni: la prima è che è contenuto come titoli e sezioni che gli utenti sfogliano, al fine di ottenere l'essenza di un particolare articolo. Il secondo sono piccoli frammenti di contenuto che possono reggersi da soli e vengono utilizzati per migliorare l'esperienza dell'utente. Un esempio eccellente in particolare che abbiamo in mente è il bit "molte persone stanno digitando..." di Slack. (sebbene Slack sia pieno di microcontenuti scritti in modo eccellente).

Quel bit viene attivato quando più di 3 persone digitano contemporaneamente nello stesso canale. Invece di stampare semplicemente un elenco di persone che attualmente digitano, Slack prende queste informazioni noiose e le aggiunge un po' di divertimento. La discussione sta iniziando a diventare davvero calda, e si vede. È un eccellente esempio di come la documentazione del prodotto (i messaggi dell'applicazione ne fanno parte, no?) fa parlare di te (e crea meme esilaranti come quelli sopra).

API REST

La documentazione delle API REST è un'arte separata in sé e per sé. Come per tutta la scrittura tecnica, dovresti mirare a concisione, chiarezza e semplicità nelle definizioni. Poiché le API REST hanno il loro formato e le loro complessità, non potresti fare di peggio che studiare l'eccellente guida per la documentazione delle API di Tom Johnson sul suo blog I'd Rather Be Writing.

Collaborazione e pianificazione della documentazione

In definitiva, la documentazione dovrebbe far parte della progettazione del prodotto. Pertanto, dovresti affrontarlo come se avessi una pipeline aggiuntiva nel tuo ciclo software. Ciò significa utilizzare repository software per archiviare la versione della documentazione più aggiornata, utilizzare bug/problemi tracker per monitorare attività e problemi, includere la pianificazione del progetto della documentazione nella tabella di marcia e, ultimo ma non meno importante, collaborare con altre persone. Uno schema approssimativo di come iniziare potrebbe essere il seguente:

Registra tutto ciò che l'utente vorrebbe sapere, nonché le aree per le quali dovrai scrivere del testo.
Una volta che hai tutto, raggruppali in categorie e forma i titoli dei documenti.
Scrivi una specifica per ogni documento specificando cose come titolo, descrizione, pubblico di destinazione, media (che forma avrà il documento), lunghezza, quanto tempo ci vorrà, ecc.
Aggiungi le stime dalle specifiche della documentazione alla pianificazione del tuo progetto.

Poiché la documentazione del prodotto è trasversale a tutte le aree, è quasi certo che dovrai lavorare con persone diverse all'interno dell'organizzazione. È una buona idea sedersi e concordare una sorta di processo su come andrà tutto questo. Come in ogni progetto, è necessario identificare le parti interessate che forniranno assistenza tecnica, nonché coloro che esamineranno e modificheranno le modifiche.

Ci dovrebbero essere diverse fasi del processo. Questi dovrebbero tracciare dove vengono raccolte le informazioni, quando il documento è scritto, quando è pronto per la correzione di bozze letterarie, per i commenti tecnici, la pubblicazione e così via. Enfatizzare la differenza tra commenti letterari, tecnici e relativi al contenuto. Ad esempio, non è molto utile quando chiedi a un team leader di commentare il tuo documento e invece di informazioni tecnicamente correlate, ricevi grida per la grammatica e la punteggiatura.

Chiusura

La documentazione del prodotto è una risorsa che si ripaga a lungo termine. Dà valore al tuo cliente. Potrebbe anche essere così buono, come ad esempio la documentazione dell'API di Stripe, che la gente ne è entusiasta nei forum. Questo crea coinvolgimento e pubblicizza il tuo marchio e il tuo prodotto in modo naturale e potente. Se abbinato a microcontenuti creativi, raggiunge ciò che Mike Puterbaugh intende quando afferma che la documentazione del prodotto è "l'arma segreta del marketing".