Documentare plugin e temi di WordPress

La documentazione è qualcosa che di solito viene apprezzata solo quando c'è un problema e hai bisogno di risposte rapide. In questo articolo, esamineremo i motivi per cui scrivere documentazione per le tue risorse WordPress è importante per la tua pratica come sviluppatore WordPress e per la qualità dei temi e dei plug-in che spedisci.

Perché la documentazione è importante?

Mantenere una serie aggiornata di documentazione sui tuoi progetti, risorse o prodotti è importante per molte ragioni.

Innanzitutto, è un'esperienza comune guardare qualcosa che hai realizzato 2 mesi fa e che non hai più toccato da allora, e non avere idea di cosa significhi. Quando lo sviluppi, hai tutto nella tua testa ma quella comprensione non ci sarà in futuro. Quindi, sia l'utilizzo di commenti di codice in linea o la scrittura di note di testo normale in Markdown, fa molto per salvare il tuo sé futuro dalla confusione.

In secondo luogo, mantenere le tue risorse documentate è utile per altri sviluppatori di WordPress. E questo ha senso anche se sei un libero professionista solitario (a un certo punto sei obbligato a collaborare con altre persone). Dovranno utilizzare tali risorse o gli verrà chiesto di mantenerle e/o aggiornarle. È molto frustrante dover usare codice non documentato scritto da qualcun altro, che non è in giro per fornire supporto o spiegare alcuni bit difficili.

Infine, la documentazione aggiunge quell'aspetto "lucido" ai tuoi prodotti e i tuoi clienti ti ameranno di più.

5 principi per una documentazione efficace

La scrittura tecnica è una disciplina a sé stante e viene utilizzata per comunicare informazioni tecniche in modo chiaro e inequivocabile. (Non solo i computer, avvocati e medici, ad esempio, usano anche un proprio linguaggio tecnico). Per questo motivo, un documento che è considerato scrittura tecnica di solito segue un certo stile e obbedisce a una serie di regole.

Esaminiamo i 5 più importanti in modo che tu possa scrivere una documentazione efficace per i tuoi prodotti!

• Preferisci usare meno parole di quelle che useresti normalmente nella tua scrittura: ogni parola dovrebbe avere uno scopo. Sii diretto e semplice. La documentazione è solitamente ricercata quando una persona è nei guai e vuole trovare rapidamente una soluzione. Ad esempio, una frase come "La mancata distruzione dell'oggetto Q introdurrà perdite di memoria" è preferibile a "La mancata distruzione dell'oggetto Q causerà l'introduzione di perdite di memoria".
• Preferisci usare la voce attiva anziché quella passiva: “ Clicca il pulsante in alto a destra” invece di “Il pulsante in alto a destra deve essere cliccato ”. L'uso di una voce attiva cancella qualsiasi ambiguità su chi fa cosa. La voce passiva viene utilizzata solo quando è necessario concentrarsi sull'oggetto, piuttosto che sul soggetto (ad esempio, la piattaforma di Pressidium è costruita pensando alla sicurezza ) .
• Usa un linguaggio descrittivo quando devi descrivere concetti e un imperativo quando devi descrivere una procedura passo-passo (come i tutorial).
• Usa elenchi puntati quando devi elencare cose che non hanno un ordine e elenchi numerati quando l'ordine dei punti è significativo.
• Assicurati di aver testato tu stesso le istruzioni prima di presentarle!

Documentare i plugin di WordPress

I plugin di WordPress sono come qualsiasi altro software. Forniscono una certa funzionalità, richiedono l'installazione e talvolta anche la risoluzione dei problemi. Non importa quanto siano semplici, è sempre una buona idea fornire una quantità adeguata di documentazione, perché non tutti gli utenti condividono la stessa competenza tecnica.

Ospita il tuo sito web con Pressidium

GARANZIA DI RIMBORSO DI 60 GIORNI

GUARDA I NOSTRI PIANI

La pubblicazione del tuo plug-in WordPress su wordpress.org ti fornirà un posto dove inserire istruzioni di installazione, schermate, domande frequenti e persino un registro delle modifiche! Riempirli con informazioni utili e di qualità è la chiave per rendere il tuo plugin più popolare:

• Scrivi una descrizione convincente e utile che alla fine indurrà l'utente a scaricare il tuo plug-in e visitare il tuo sito web.
• Aggiungi screenshot annotati che spieghino ogni elemento di configurazione del tuo plug-in in aggiunta a quelli che mostrano come appare il tuo plug-in nel browser.
• Metti nelle FAQ domande che non siano banali. Un buon modo per scoprire strani casi limite è chiedere a un amico non esperto di computer di utilizzare il tuo plug-in.
• Avere un Changelog aggiornato e ben scritto. Le battute concise e criptiche sono un grande no-no e mostrano che non ti importa davvero dei tuoi utenti.
• Assicurati che il codice del tuo plug-in sia ben commentato e segua le migliori pratiche software e gli standard di codifica ufficiali.

Se sei bloccato e hai bisogno di ispirazione, conduci una piccola ricerca e guarda come viene scritto il testo nei plugin popolari che hanno centinaia di migliaia di installazioni, rispetto a quelli meno utilizzati.

Documentare i temi di WordPress

Documentare i temi di WordPress è una questione completamente diversa. Il problema più comune con i temi WordPress è non sapere quale sezione corrisponde a quale elemento visivo. Non tutti parlano correntemente CSS:

• Crea una gerarchia di tutte le sezioni del tuo CSS, con le descrizioni corrispondenti.
• Per ogni sezione, aggiungi uno screenshot con annotazioni che descriva in dettaglio ogni funzionalità, insieme a un piccolo esempio. Non dimenticare di usare la voce attiva e il linguaggio imperativo, quando mostri come fare qualcosa che richiede all'utente di seguire le istruzioni.
• Usa uno strumento come css_doc per aiutarti. Questo genera uno stile di documentazione JavaDoc e può essere pubblicato.
• A volte i commenti sul codice non sono sufficienti ed è necessario creare un documento Style Guide per il tuo tema CSS. I documenti delle guide di stile descrivono come devono apparire gli elementi e in quali casi devono essere utilizzati. Rafforzano la coerenza e facilitano anche la collaborazione. Vedi questo esempio di Google.
• Usa un framework CSS come Blueprint CSS. Questo ti aiuterà nello sviluppo fornendoti una serie di strumenti come una griglia personalizzabile, tipografia predefinita che funziona, ripristino CSS del browser e molto altro.
• Ancora una volta, non dimenticare di consultare gli standard di codifica CSS ufficiali di WordPress.