Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per la stagione dei documenti Google.
Riepilogo del progetto
- Organizzazione open source:
- WordPress
- Technical writer:
- tacitonico
- Nome progetto:
- Guida di stile per la documentazione completa e rinnovata
- Durata del progetto:
- Lunga esecuzione (5 mesi)
Project description
Trama:
WordPress è un'organizzazione software non profit globale che si impegna a servire le comunità globali con software incentrati su accessibilità, prestazioni, sicurezza e facilità d'uso. La causa di WordPress si impegna a democratizzare la pubblicazione e il software open source sul web. Nella nostra era digitale, un sito web è letteralmente la facciata online di un'organizzazione o di un privato e WordPress svolge un immenso compito di servire in modo efficiente centinaia di milioni di utenti, attribuiti al 35% di internet che gestisce, con i propri software. Per servire ulteriormente questi utenti in modo più efficiente, la documentazione si rivela essenziale ed è utilizzata dalla maggior parte degli sviluppatori, degli amministratori e degli utenti finali. Pertanto, la documentazione può essere considerata uno dei fattori principali dell'ecosistema WordPress. L'attuale documentazione di WordPress non include un insieme universale e unificato di regole e linee guida di stile per la pubblicazione. Lo scopo di questa proposta è creare un insieme completo e rinnovato di linee guida relative allo stile della documentazione, universalmente applicabili alla documentazione di WordPress. L'idea del progetto comporta il consolidamento di tutti gli aspetti delle linee guida relative a design e stile, come semantica, sintattica, linee guida grammaticali, punteggiatura, regole specifiche per lo sviluppo, attributi di progettazione e specifiche di formattazione. Incorpora inoltre convenzioni linguistiche come voce, tono, tempo e tutte le parti del discorso, nonché convenzioni di denominazione. Gli strumenti, i linguaggi e le piattaforme utilizzati saranno CMS WordPress, GitHub, Markdown e potranno anche consistere in PHP/MySQL, HTML/CSS e JavaScript.
Piano del progetto:
Stato attuale delle guide di stile per la documentazione di WordPress: Il team di documentazione di WordPress ha implementato una metodologia non dichiarata ma unanime per le linee guida di pubblicazione. Ma, di tanto in tanto, alcuni elementi sono presupposti e il processo diventa speculativo. Non esistono standard e criteri fissi per la scrittura e la pubblicazione di articoli per WordPress. Il team di documentazione ha redatto linee guida di stile specifiche per il progetto, ma nessuna di queste linee guida è universalmente applicabile. La maggior parte delle linee guida sullo stile esistenti non è consolidata in un unico manuale oppure è deprecata e deve essere aggiornata. Di conseguenza, è necessario progettare e sviluppare una guida di stile unificata per standardizzare la documentazione di WordPress.
Obiettivi.
Oltre il 35% dei siti web di Internet utilizza WordPress, che a sua volta indica che milioni di sviluppatori e utenti finali utilizzano le straordinarie funzionalità di WordPress. La documentazione è un elemento essenziale per aiutare questi sviluppatori e utenti a soddisfare queste funzionalità in modo efficiente senza problemi, anche in caso di inconvenienti. L'obiettivo generale di questa proposta di progetto è standardizzare una guida di design e stile, unificare le guide di stile e gli aggiornamenti esistenti, nonché aggiungere nuovi regolamenti e specifiche per la documentazione di WordPress. Ciò consentirebbe facilità d'uso, semplicità e uniformità nella documentazione di WordPress.
Implementazione:
Come suggerito dal mentore (Jon Ang) per questo progetto, il progetto può essere affrontato in 4 fasi: fase di scoperta, definizione, implementazione e manutenzione. Prima dell'inizio del progetto, durante il periodo del tirocinio, collaborerò con il mio mentore e finalizzerò un programma e una tempistica adatti in base alle tempistiche e ai risultati finali successivi. Acquisterò ulteriormente la conoscenza del sistema WordPress e dei protocolli di lavoro per questo progetto.
All'inizio del tirocinio, parlerò e scriverò l'estratto del piano con il mio mentore. Saranno stabiliti i requisiti e le necessità. Innanzitutto, ti illustrerò il flusso della documentazione e il processo di interazione dell'utente. In seguito, verranno delineati i reticoli di layout di ogni sezione, categoria e componente. Questi layout verranno poi esaminati dal mio mentore. Se necessario, i layout verranno riprogettati e alcuni componenti verranno aggiunti/rimossi. Condurrò quindi una ricerca sugli utenti per determinare l'usabilità e la fattibilità del flusso dell'interfaccia. Successivamente, verrà implementata la Guida di stile della documentazione (come illustrato nel diagramma seguente) per sezione. È possibile aggiungere la nostra guida anche alle guide di stile di altre organizzazioni che sono soggette a qualsiasi licenza open source o Creative Commons. Se durante questo periodo si verificano problemi di usabilità, provvederò a riprogettarli.
I test e le ottimizzazioni verranno eseguiti dopo che la guida di stile sarà stata completata e integrata con HelpHub. Eventuali vulnerabilità, elementi o componenti ridondanti vengono rettificati. Verrà eseguito il test dell'interfaccia utente e del codice e, se necessario, verranno corretti bug ed errori indesiderati. Verrà eseguito un controllo finale di qualità per l'intera guida di stile relativa a lingua, grammatica, ortografia, punteggiatura, ecc.
Le attività in attesa a causa di ritardi imprevisti verranno completate nel periodo di buffer. Le funzionalità o caratteristiche aggiuntive che sarebbero considerate fattibili nel corso del progetto possono essere implementate dopo il test finale. Verrà creato un piano di implementazione e verrà inviato il prodotto finito.
Strumenti e metodologie:
La documentazione verrà compilata e modificata su una piattaforma collaborativa, come Documenti Google. Se necessario per la pubblicazione tramite GitHub, è possibile implementare anche linguaggi di markup come Markdown o GitHub Flavored Markdown. Per gli standard di design e stile, è possibile fare riferimento anche alle linee guida relative allo stile open source. Infine, il documento completato verrà formattato e pubblicato utilizzando WordPress.
Tabella dei componenti:
Questo è un elenco esaustivo dei componenti che possono essere implementati nella Guida di stile. Linee guida per i documenti: accessibilità, struttura del documento, codifica, fonti esterne, fatti, caratteri, pubblico globale, inclusività, legalità, accessibilità multipiattaforma, non ambigua, nessuna rivendicazione eccessiva, layout di pagina, correttezza politica, protocolli, sicurezza, struttura della frase, scrittura concisa, tono e stile, imparziale
Linguaggio e grammatica - Abbreviazioni e acronimi, affermazione e negazione, articoli, lettere maiuscole, clausola, discorso diretto/indiretto, prima/seconda/terza persona, generi, Glossario, sostantivi, prefissi e suffissi, preposizioni, pronomi, riferimenti, gergo e gergo, ortografia, termini tecnici, teso, verbo
Punteggiatura: apostrofi e virgolette, due punti e semidue punti, virgole, ellissi, punti esclamativi, trattini e trattini, parentesi, punti, punti interrogativi, barre
Formattazione - Abstract, Procedure, grafiche, annotazioni, nomi di brand, nomi di prodotti, didascalie, snippet di codice, blocchi di codice, data e ora, fusi orari, luoghi, valute, nomi di file, note a piè di pagina, intestazioni e titoli, evidenziazione (grassetto, corsivo, sottolineato, barrato, virgolette, elementi multimediali), rientro e numerazione
Interfaccia utente - Attività, pulsanti, snippet di codice, blocchi di codice, interfaccia a riga di comando, finestre di dialogo, menu e menu a discesa, popup e avvisi, schede, terminologia, elementi dell'interfaccia utente, Windows
Codice: CSS, HTML, JS, Markdown, MySQL, PHP, sintassi, XML
Dizionario/Glossario di utilizzo delle parole - dalla A alla Z