Questa pagina contiene i dettagli di un progetto di documentazione tecnica accettato per la stagione della documentazione di Google.
Riepilogo del progetto
- Organizzazione open source:
- WordPress
- Redattore tecnico:
- tacitonico
- Nome progetto:
- Un insieme completo e rinnovato di guide di stile della documentazione
- Durata del progetto:
- A lungo termine (5 mesi)
Project description
Trama:
WordPress è un'organizzazione software non profit globale che si dedica a fornire alle comunità globali software che enfatizza l'accessibilità, le prestazioni, la sicurezza e la facilità d'uso. La missione di WordPress è democratizzare la pubblicazione e il software open source sul web. Nella nostra era digitale, un sito web è letteralmente la facciata online di un'organizzazione/di un privato; e WordPress ha l'enorme compito di fornire in modo efficiente centinaia di milioni di utenti, ovvero il 35% di internet, con il proprio software. Per offrire un servizio più efficiente a questi utenti, la documentazione si rivela essenziale e viene utilizzata dalla maggior parte degli sviluppatori, degli amministratori e degli utenti finali. Pertanto, la documentazione può essere stabilita come fattore principale dell'ecosistema WordPress. La documentazione attuale di WordPress non include un insieme universale e unificato di regole e linee guida di stile per la pubblicazione. Lo scopo di questa proposta è quello di creare un insieme completo e rinnovato di linee guida relative allo stile della documentazione, universalmente applicabili alla documentazione WordPress. L'idea del progetto prevede il consolidamento di tutti gli aspetti delle linee guida di design e stile, come semantica, sintassi, linee guida grammaticali, punteggiatura, regole specifiche per lo sviluppo, attributi di design e specifiche di formattazione. Inoltre, incorpora convenzioni linguistiche come voce, tono, tempo, tutte le parti del discorso e convenzioni di denominazione. Gli strumenti, i linguaggi e le piattaforme utilizzati saranno WordPress CMS, GitHub, Markdown e potrebbero includere anche PHP/MySQL, HTML/CSS e JavaScript.
Progetto:
Attuale guida di stile per la documentazione di WordPress: Il team di documentazione di WordPress ha implementato una metodologia non dichiarata, ma unanime, per la pubblicazione delle linee guida. A volte, però, 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 scritto linee guida di stile specifiche per i progetti, ma nessuna applicabile universalmente. La maggior parte delle linee guida di stile esistenti non è raggruppata in un unico manuale o sono deprecate e devono essere aggiornate. 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 è basato su WordPress, il che indica che milioni di sviluppatori e utenti finali utilizzano le impressionanti funzionalità di WordPress. La documentazione è un elemento essenziale per aiutare questi sviluppatori e utenti a utilizzare in modo efficiente queste funzionalità 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 esistenti e aggiornarle, nonché aggiungere nuove normative e specifiche per la documentazione di WordPress. Ciò consentirebbe la facilità d'uso, la semplicità e l'uniformità nella documentazione di WordPress.
Implementazione:
Come suggerito dal mentor (Jon Ang) per questo progetto, è possibile affrontarlo in quattro fasi: scoperta, definizione, implementazione e manutenzione. Prima dell'inizio del progetto, durante il periodo precedente l'internship, lavorerò con il mio mentore e finalizzerò un programma e una tempistica adeguati in linea con le tempistiche e i risultati previsti. Imparerò più a fondo il sistema WordPress e i protocolli di lavoro per questo progetto.
All'inizio dello stage, discuterò e redigerò la bozza del riepilogo del piano con il mio mentore. Verranno determinati i requisiti e le necessità. Innanzitutto, illustrerò il flusso della documentazione e la procedura di interazione con l'utente. Successivamente, verranno delineati i wireframe di layout di ogni sezione, categoria e componente. Questi layout verranno poi esaminati dal mio mentore. Se necessario, i layout verranno ridisegnati e alcuni componenti verranno aggiunti/rimossi. Dopodiché condurrò una ricerca sugli utenti per determinare l'usabilità e la fattibilità del flusso dell'interfaccia. Successivamente, la Guida allo stile della documentazione verrà implementata (come illustrato nel diagramma di seguito) per sezione. È possibile fare riferimento anche alle guide di stile di altre organizzazioni che utilizzano licenze open source o Creative Commons per aggiungere la nostra guida. Se durante questo periodo si verificano difficoltà di usabilità, le riprogetterò.
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 verranno corretti. Verranno eseguiti test dell'interfaccia utente e del codice e, se necessario, verranno corretti bug ed errori indesiderati. Verrà eseguito un controllo qualità finale della guida di stile completa per lingua, grammatica, ortografia, punteggiatura e così via.
Le attività in attesa a causa di ritardi imprevisti verranno completate nel periodo di buffer. Funzionalità o funzionalità aggiuntive che potrebbero essere ritenute possibili nel corso del progetto possono essere implementate al termine dei test finali. Verrà creato un piano di deployment e verrà inviato il prodotto finito.
Strumenti e metodologie:
La documentazione verrà compilata e modificata su una piattaforma di collaborazione, 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 di 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 ambiguo, Nessuna dichiarazione 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, Maiuscole, Clausola, Discorso diretto/indiretto, Prima/seconda/terza persona, Generi, Glossario, Sostantivi, Prefissi e suffissi, Preposizioni, Pronomi, Riferimenti, Gergo e linguaggio specialistico, Ortografia, Termini tecnici, Tempo, Verbi, Voce
Punteggiatura: apostrofo e virgolette, due punti e punti e virgola, virgole, ellissi, punti esclamativi, trattini e barre, parentesi, punti, punti interrogativi, barre
Formattazione: abstract, introduzione, prefazioni, nomi di brand, nomi di prodotti, didascalie, snippet di codice, blocchi di codice, data e ora, fusi orari, località, valute, nomi file, note a piè di pagina, intestazioni e titoli, evidenziazione (in grassetto, corsivo, sottolineato, barrato, tra virgolette), rientro, indice, link e URL, elenchi, elenchi puntati, numerazione, contenuti multimediali (immagini, video) e illustrazioni, note, avvisi, suggerimenti, numeri e numeri di telefono, poliglotti, traduzione, script di lingua, spaziatura, tabelle, testo, marchi, copyright, brevetti, citazioni, tutorial e procedure, elementi dell'interfaccia utente, unità di misura
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, finestre
Codice: CSS, HTML, JS, Markdown, MySQL, PHP, sintassi, XML
Dizionario/glossario di utilizzo delle parole - dalla A alla Z