Questa pagina contiene i dettagli di un progetto di documentazione tecnica accettato per la stagione della documentazione di Google.
Riepilogo progetto
- Organizzazione open source:
- ESLint
- Redattore tecnico:
- Khawar
- Nome progetto:
- Riorganizzare/riscrivere la documentazione di configurazione
- Durata del progetto:
- Durata standard (3 mesi)
Project description
Abstract
Lo scopo di questo progetto è ristrutturare la documentazione di configurazione di ESLint e creare un'architettura di informazioni efficace. In questo modo, la navigazione sarà più semplice e migliorerà anche l'usabilità e l'utilità della documentazione.
Riepilogo del progetto La documentazione di configurazione di ESLint (https://eslint.org/docs/user-guide/configuring), nello stato attuale, fornisce molte informazioni in un'unica pagina. Nonostante la presenza di intestazioni, sottotitoli e paragrafi appropriati nella pagina, la documentazione può essere scoraggiante. Non è possibile passare a una determinata sezione della pagina, il che può essere frustrante per un utente interessato a una sezione specifica. Le informazioni, a causa di questa mancanza di organizzazione, possono anche andare perse, non soddisfacendo il suo scopo e chiedendo agli utenti di impegnarsi ulteriormente.
Tuttavia, questi problemi possono essere risolti seguendo una serie di passaggi accurati. Propongo un controllo dei contenuti come primo passo di questa riorganizzazione. Un controllo dei contenuti non solo aiuta a identificare i problemi nella presentazione delle informazioni, ma mette in evidenza anche le carenze dei contenuti stessi (ad es. informazioni obsolete o incomplete). Poi ho intenzione di creare l'architettura delle informazioni (IA) per svelare la rete di conoscenze. In questo modo potremo raggruppare le informazioni in base a vari argomenti e trovare collegamenti tra vari argomenti strettamente correlati. Le informazioni acquisite attraverso queste due pratiche verranno quindi utilizzate per suddividere la documentazione di una sola pagina in più pagine. L'intero pacchetto può quindi essere collegato e fatto riferimento incrociato in Markdown. Di conseguenza, sarà disponibile una versione più organizzata della documentazione di configurazione, più facile da navigare e comprendere.
Motivazione Nonostante utilizzi software open source da un po' di tempo, la mia familiarità con il termine è piuttosto recente, così come la mia conoscenza del software di linting. Quando ho iniziato a imparare Python (tramite edX), mi chiedevo quanto piccoli errori possano rovinare l'intero codice. Ho pensato che sarebbe stato bello testare i tuoi codici in qualche modo e identificare gli errori, poi ho scoperto il termine "linting". Non ho ancora utilizzato un software di linting, ma sono sicuro che mi semplificherà la vita nei prossimi giorni.
Grazie alla mia formazione in ingegneria elettrica e a una certa esperienza in programmazione, posso comprendere meglio i problemi di codifica e i requisiti dei programmatori. Inoltre, il mio titolo di laurea in comunicazione tecnica e professionale mi rende un sostenitore degli utenti, cercando di semplificare la vita delle persone. Le mie competenze e la mia esperienza saranno una buona combinazione per questo progetto, aggiungendo valore alla documentazione di ESLint.
Scopi L'obiettivo generale di questo progetto è garantire che la documentazione nella pagina di configurazione di ESLint sia facile da comprendere e non sovraccarichi gli utenti. Per il successo del progetto è importante che la navigazione tra i contenuti sia semplice e priva di complicazioni. Gli obiettivi importanti del progetto sono i seguenti. - Eseguire un audit completo dei contenuti - Creare un'architettura delle informazioni per comprendere il flusso di informazioni - Migliorare l'architettura delle informazioni per riorganizzare la documentazione - Identificare link e riferimenti tra le diverse sezioni dei contenuti - Riscrivere/modificare parti della documentazione, se necessario per soddisfare i requisiti di riconfigurazione
- Assicurati che i contenuti siano flessibili e riutilizzabili
Descrizione del progetto La configurazione di ESLint è una funzionalità importante che lo rende personalizzabile. Gli utenti interessati alla configurazione saranno sicuramente interessati a uno o due aspetti alla volta. È quindi importante che un utente venga indirizzato al suo argomento di interesse specifico, fornendogli così la soluzione in modo efficiente. Lo stato attuale della documentazione di configurazione di ESLint contiene molte informazioni utili, ma è organizzata in un modo che può far sentire gli utenti sopraffatti, frustrati e spaesati. Ad esempio, se qualcuno è interessato a conoscere l'uso di plug-in di terze parti in ESLint, dovrà scorrere verso il basso per leggere la discussione sulla specifica di parser, ambienti e globali. Questa pratica è stanca per gli utenti e può allontanarli dal sito web. Analogamente, se un utente si trova in un punto centrale della pagina e desidera visitare una sezione particolare o semplicemente consultare argomenti simili, non sarà un'attività facile per lui, poiché non fornisce questo tipo di supporto agli utenti. Questi problemi richiedono attenzione immediata in quanto la qualità della documentazione, indipendentemente da quanto sia redatta, dipende dalla sua utilità. Nella discussione che segue propongo soluzioni a questi e ad altri problemi correlati.
Controllo dei contenuti Il primo passaggio della procedura di riorganizzazione della documentazione di configurazione consiste nel condurre un controllo completo dei contenuti. Lo scopo del controllo sarà identificare alcuni problemi chiave, come contenuti obsoleti, duplicati, mancanti e così via. Il foglio di lavoro del controllo dei contenuti creato in seguito verrà condiviso con i team di gestione e documentazione per ricevere il loro feedback. In questo modo, potrai elaborare una nuova strategia per strutturare e presentare la documentazione.
Creazione dell'architettura dell'informazione Per comprendere la rete di conoscenza o il flusso di informazioni nella documentazione di configurazione, può essere utile creare un'architettura dell'informazione (IA). I risultati del controllo dei contenuti costituiranno una buona base per comprendere e sviluppare il flusso di informazioni. Verrà quindi creata una versione migliorata dell'IA per organizzare e presentare la documentazione in modo migliore. Questa IA migliorata non solo ristruttura i contenuti attuali, ma identifica anche i link e le ramificazioni tra le varie sezioni della documentazione, creando così una rete efficiente. Ad esempio, i contenuti relativi a "Configurazione delle regole" possono essere seguiti da un link che rimanda a "Disattivazione delle regole con commenti in linea". È possibile identificare anche altri link di questo tipo, creando così relazioni tra le diverse sezioni della documentazione.
Un sommario Il controllo dei contenuti e l'IA forniranno informazioni adeguate per creare un sommario dettagliato con link a sezioni e sottosezioni specifiche della documentazione. La creazione di file distinti per ogni sezione e l'aggiunta di riferimenti appropriati ad altre sezioni può aggiungere valore all'intero insieme di documenti. È possibile creare un sommario per gli utenti che arrivano alla documentazione di configurazione, facilitando così il loro percorso sul sito web. Il sommario può includere tutte le intestazioni di primo e secondo livello per essere breve ma completo. Una di queste pratiche, ad esempio, è quella utilizzata da Prettier (https://prettier.io/docs/it/index.html) per organizzare la documentazione.
Tutta la documentazione verrà creata utilizzando Markdown per semplificare e organizzare al meglio le cose. Verrà prestata particolare attenzione per garantire che la documentazione sia riutilizzabile, in quanto potrebbe espandersi e modificarsi in futuro.
Strumenti da utilizzare Alcuni strumenti importanti che possono essere utili durante la realizzazione del progetto sono: - Draw.io per creare illustrazioni per l'IA in base alle esigenze - Atom (o un editor simile) per scrivere e modificare i documenti in Markdown
- GitHub per garantire il controllo della versione della documentazione
Traguardi Dall'invio della proposta al completamento del progetto, i seguenti traguardi provvisori garantiranno il completamento del progetto in tempo, mantenendo il flusso corretto della procedura.
10 luglio 2020 - 16 agosto 2020: revisione e selezione delle proposte Esaminerò la documentazione di ESLint e svilupperò le competenze necessarie per completare il progetto (ad esempio scrittura in Markdown, collaborazione su GitHub). Contribuirò anche alla documentazione tramite GitHub e interagirò con altre persone per comprenderla meglio.
17 agosto 2020 - 13 settembre 2020: affiatamento con la community Durante il periodo di affiatamento con la community, perfezionerò la mia proposta in base alle discussioni con i mentor e i team interessati. Se necessario, modificherò anche gli obiettivi e i traguardi. Inoltre, mi assicurerò di stilare una lista degli strumenti che verranno utilizzati per lavorare al progetto.
14 settembre 2020 - 19 settembre 2020: revisione dei contenuti Per iniziare il progetto, condurrò un'analisi completa dei contenuti della documentazione di configurazione. L'obiettivo è quello di mettere in evidenza i problemi relativi ai contenuti e alla loro presentazione.
20 settembre 2020 - 25 settembre 2020: architettura dell'informazione (IA) Dopo l'audit dei contenuti, creerò l'IA della documentazione di configurazione. Mi concentrerò sulla presentazione della rete di conoscenza in modo comprensibile. In questo modo, contribuirai a migliorare il flusso di informazioni.
26 settembre - 30 settembre 2020: link e riferimenti Durante questa fase analizzerò l'IA per mappare i link e i riferimenti tra le varie sezioni della documentazione. Creerò inoltre una gerarchia di tutte le sezioni, migliorando così l'IA nel processo.
1° ottobre 2020 - 3 ottobre 2020: la mappa finale Con l'aiuto delle informazioni acquisite tramite l'audit dei contenuti e l'IA, creerò una mappa finale da implementare nella documentazione di configurazione riorganizzata. Questa mappa completa conterrà un sommario, una gerarchia di argomenti e un elenco di link e riferimenti incrociati tra le sezioni della documentazione.
4 ottobre 2020 - 5 ottobre 2020: discussione A questo punto, ovvero prima di modificare la documentazione, presenterò i miei risultati e il mio piano ai mentor e ai team interessati. Il loro feedback contribuirà a perfezionare il piano e a apportare modifiche, se necessario.
6 ottobre 2020 - 20 ottobre 2020: riscrittura e modifica In questo periodo modificherò e aggiornerò le sezioni dei documenti in cui è necessario lavorare. Alcune sezioni della documentazione di configurazione potrebbero essere riscritte o potrebbero essere aggiunte nuove informazioni. L'obiettivo di questa fase sarà garantire che la documentazione sia accurata, aggiornata, flessibile e riutilizzabile.
21 ottobre 2020 - 25 ottobre 2020: correzioni e link In questa fase, esaminerò il mio lavoro per eliminare gli errori grammaticali e strutturali e anche per verificare la sua accuratezza. Aggiungerò anche link e riferimenti tra le sezioni, come da IA, per assicurarmi che la documentazione segua la mappa della conoscenza ideata in precedenza.
26 ottobre 2020 - 31 ottobre 2020: versione finale da inviare Collegherò tutti i file Markdown, creerò un sommario e condividerò le bozze con i mentor. Questo servirà come invio della prima bozza, sotto forma di pacchetto completo.
1° novembre 2020 - 5 novembre 2020: prima revisione Nel corso di questi cinque giorni, parlerò della prima bozza con i miei mentori. Riceverò il loro feedback e discuterò con loro delle mie idee per creare un elenco delle modifiche da apportare.
6 novembre 2020 - 12 novembre 2020: prime modifiche Con l'aiuto del feedback dei mentor, modificherò la prima bozza della documentazione. Le modifiche effettive dipenderanno dalla natura dei commenti e dei feedback, ma gli obiettivi di riutilizzo, accuratezza e flessibilità fungeranno da sede della fase di editing.
13 novembre 2020 - 15 novembre 2020: seconda revisione Dopo il completamento delle modifiche iniziali, discuterò ancora una volta dell'avanzamento con i miei mentor e i team interessati. Queste discussioni si concentreranno sulle modifiche apportate alla prima versione e metteranno in evidenza eventuali altri problemi che potrebbero essere sorti durante la modifica.
16 novembre 2020 - 19 novembre 2020: seconda revisione Dedicherò poi quattro giorni alla revisione del documento. Le versioni prodotte verranno discusse con i mentor per dare loro una forma definitiva. I documenti, al completamento di questa fase, saranno nella forma finale, pronti per essere caricati sul sito web e nel repository GitHub.
20 novembre 2020 - 23 novembre 2020: caricamento sul sito web Dopo aver apportato tutte le modifiche necessarie, i documenti verranno caricati sul sito web. Eventuali problemi riscontrati durante la procedura verranno gestiti di conseguenza, poiché avremo ancora qualche giorno per lavorare sulla documentazione.
24 novembre 2020 - 28 novembre 2020: report del progetto In questo periodo di cinque giorni verrà creato un report dettagliato del progetto. Gli obiettivi, le difficoltà, i problemi e le soluzioni presentate faranno parte del rapporto del progetto. Il report verrà condiviso con i mentor per il feedback.
29 novembre 2020 - 30 novembre 2020: invio finale Il progetto, insieme a tutti i file e al report del progetto, verrà inviato ai mentor. La revisione dell'intero progetto verrà condotta attraverso un incontro/dibattito con i mentori e i team interessati.
Durante il progetto, continuerò a consultare i mentori per ricevere il loro prezioso feedback. Tutti questi traguardi possono essere modificati in base alle discussioni con i mentor durante i periodi di affiatamento con la community e di revisione delle proposte.
Informazioni su di me Ho una laurea in Ingegneria elettrica e una laurea in Comunicazioni tecniche e professionali presso la North Carolina State University. Ho esperienza nei campi della scrittura e della revisione tecnica e professionale, della comunicazione e della gestione dei contenuti, degli studi di usabilità web e mobile e della progettazione di istruzioni. Ho lavorato come redattore per una pubblicazione online (Global Village Space) e come stagista per le comunicazioni per Duke Forge presso la Duke University. Inoltre, mi interesso di scrittura creativa.