Progetto ESLint

Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per la stagione dei documenti Google.

Riepilogo del progetto

Organizzazione open source:

ESLint

Technical writer:

Khawar

Nome progetto:

Riorganizza/riscrivi la documentazione sulla configurazione

Durata del progetto:

Durata standard (3 mesi)

Project description

Abstract

Lo scopo di questo progetto è ristrutturare la documentazione di configurazione per ESLint e creare un'architettura delle informazioni efficace. Ciò semplificherà la navigazione 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 titoli, sottotitoli e paragrafi appropriati nella pagina, la documentazione può diventare difficoltosa. Non esiste un modo per accedere 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 potendo servire al loro scopo e chiedendo agli utenti di impegnarsi ulteriormente.

Questi problemi, tuttavia, possono essere risolti con una serie di passaggi accurati. Come primo passo in questa riorganizzazione propongo un controllo dei contenuti. Un controllo dei contenuti non solo consente di identificare i problemi nella presentazione delle informazioni, ma mette anche in evidenza le carenze dei contenuti stessi (ad es. informazioni obsolete o incomplete). In seguito ho intenzione di creare l'Information Architecture (IA) per rivelare la rete di conoscenza. Questo ci consentirà di raggruppare le informazioni in base a vari argomenti e di trovare collegamenti tra vari argomenti strettamente correlati. Le informazioni acquisite nell'ambito di queste due pratiche verranno quindi utilizzate per suddividere la documentazione di una sola pagina in più pagine. È quindi possibile collegare l'intero pacchetto e eseguire controlli incrociati in Markdown. Di conseguenza, la versione della documentazione di configurazione sarà più organizzata e sarà più semplice da consultare e comprendere.

Motivazione Nonostante utilizzi software open source da un po' di tempo, la mia familiarità con questo termine è abbastanza nuova, in linea con le mie conoscenze del software Linting. Quando ho iniziato a imparare Python (tramite edX), mi sono chiesto quanto piccoli errori possano rovinare l'intero codice. Ho pensato che sarebbe stato bello testare i codici e far identificare gli errori. Poi ho scoperto il termine "linting". Non ho ancora usato opportunamente software di lint, ma sono sicura che mi semplificheranno la vita nei prossimi giorni.

Con la mia formazione in ingegneria elettrica e una certa esperienza nella programmazione, riesco a capire meglio i problemi della programmazione e i requisiti dei programmatori. Inoltre, la mia laurea in comunicazione tecnica e professionale mi rende un sostenitore degli utenti, cercando di semplificarne la vita. Le mie competenze e competenze saranno una buona combinazione per questo progetto, aggiungendo valore alla documentazione di ESLint.

Obiettivi 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. - Esecuzione di un controllo completo dei contenuti - Creare un'architettura delle informazioni per comprendere il flusso delle 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

- Verificare che i contenuti siano flessibili e riutilizzabili

Descrizione del progetto La configurazione di ESLint è una funzionalità importante, che rende ESLint personalizzabile. Gli utenti interessati alla configurazione sarebbero sicuramente interessati a uno o due aspetti in un determinato momento. È quindi importante che l'utente venga guidato verso il suo particolare argomento di interesse, fornendogli così la soluzione in modo efficiente. L'attuale stato della documentazione di configurazione per ESLint contiene molte informazioni utili, ma è organizzata in modo da far sentire gli utenti sopraffatti, frustrati e persi. Ad esempio, se qualcuno è interessato a saperne di più sull'uso di plug-in di terze parti in ESLint, dovrà scorrere verso il basso per consultare la discussione sulla specifica di parser, ambienti e globali. L'intera pratica è stanca per gli utenti e può allontanarli dal sito web. Analogamente, se un utente si trova al centro della pagina e desidera visitare una determinata sezione o semplicemente guardare argomenti simili, non sarà un compito facile per lui, dal momento che questi aiuti non vengono forniti agli utenti. Questi problemi richiedono attenzione immediata poiché la qualità di qualsiasi documentazione, indipendentemente dalla sua efficacia, dipende dalla sua utilità. Nella discussione che segue propongo soluzioni a questi e ad altri problemi correlati.

Controllo dei contenuti La prima fase del processo di riorganizzazione della documentazione di configurazione consiste nell'eseguire un controllo completo dei contenuti. Il controllo cercherà di identificare alcuni problemi chiave come contenuti obsoleti, duplicati, contenuti mancanti e così via. Un foglio di lavoro per il controllo dei contenuti creato a seguito verrà condiviso con i team di gestione e documentazione per il loro feedback. Questo ti aiuterà a elaborare una nuova strategia per strutturare e presentare la documentazione.

Creazione dell'architettura delle informazioni Per comprendere la rete di conoscenza o il flusso di informazioni nella documentazione di configurazione, la creazione di un'architettura delle informazioni (IA) può essere utile. I risultati del controllo dei contenuti saranno una buona base per comprendere e sviluppare il flusso di informazioni. Verrà quindi creata una versione migliorata dell'IA per organizzare e presentare al meglio la documentazione. Questo miglioramento dell'IA non solo ristruttura i contenuti attuali, ma identifica anche link e fork tra le varie sezioni della documentazione, creando così una rete efficiente. Ad esempio, i contenuti della sezione "Configurazione delle regole" possono essere seguiti da un link che rimanda a "Regole di disattivazione con commenti in linea". Anche altri link di questo tipo possono essere identificati, creando così relazioni tra le diverse sezioni della documentazione.

Il controllo dei contenuti e l'IA forniranno informazioni adeguate per creare un sommario dettagliato con link che rimandano a sezioni e sottosezioni specifiche della documentazione. La creazione di file separati per ogni sezione e l'aggiunta di riferimenti appropriati ad altre sezioni possono aggiungere valore all'intero insieme di documenti. È possibile creare un sommario per gli utenti che accedono alla documentazione di configurazione, agevolando il loro percorso sul sito web. Il sommario può includere tutti i titoli di primo e secondo livello per essere brevi ma esaustivi. Una di queste prassi, ad esempio, è quella utilizzata da Prettier (https://prettier.io/docs/en/index.html) per organizzare la documentazione.

Tutta la documentazione verrà creata con Markdown per semplificare e organizzare al meglio le cose. Verrà prestata particolare attenzione per garantire che la documentazione sia riutilizzabile poiché potrebbe crescere e subire modifiche in futuro.

Strumenti da usare Alcuni strumenti importanti che possono tornare utili mentre lavori al progetto sono - Draw.io per creare illustrazioni per IA in base alle esigenze - Atom (o un editor simile) per scrivere e modificare documenti in Markdown

- GitHub per garantire il controllo della versione della documentazione

Traguardi Dall'invio della proposta al completamento del progetto, i seguenti obiettivi provvisori assicureranno che il progetto venga completato in tempo, mantenendo il corretto flusso nel processo.

10 luglio 2020 - 16 agosto 2020: revisione e selezione delle proposte Analizzerò la documentazione di ESLint e svilupperò le competenze necessarie per completare il progetto (come la scrittura di Markdown, la collaborazione su GitHub). Inoltre, darò il mio contributo alla documentazione tramite GitHub e interagirò con altre persone per comprendere meglio la documentazione.

17 agosto 2020 - 13 settembre 2020: legami con la comunità Durante il periodo dei legami con la comunità, perfezionirò la mia proposta in base alle discussioni con i mentori e i team interessati. Se necessario, modificherò anche gli obiettivi e i traguardi. Inoltre, mi assicurerò di selezionare gli strumenti che verranno utilizzati per lavorare al progetto.

14 settembre 2020 - 19 settembre 2020: controllo dei contenuti Per iniziare con il progetto, effettuerò un controllo completo dei contenuti della documentazione di configurazione. L'obiettivo è evidenziare i problemi legati ai contenuti e alla presentazione.

20 settembre 2020 - 25 settembre 2020: architettura delle informazioni (IA) Dopo il controllo dei contenuti, creerò l'IA della documentazione di configurazione. Mi occuperò di presentare la rete di conoscenze in un modo comprensibile. Ciò contribuirà ad apportare miglioramenti al flusso di informazioni.

26 settembre 2020-30 settembre 2020: link e riferimenti Analizzerò l'IA durante questa fase per delineare collegamenti e riferimenti tra le varie sezioni della documentazione. Creerò anche una gerarchia di tutte le sezioni, migliorando così l'IA durante il processo.

1° ottobre 2020 - 3 ottobre 2020: la mappa finale Con l'aiuto degli insight acquisiti tramite il controllo dei contenuti e l'IA, creerò una mappa finale da implementare nella documentazione riorganizzata della configurazione. 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, prima di modificare la documentazione, presenterò i risultati e il programma ai mentori e ai team interessati. Il loro feedback aiuterà a perfezionare il piano e ad 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 aggiunti nuovi elementi. In questa fase ci concentreremo su come 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 errori grammaticali e strutturali e per verificare l'accuratezza del mio lavoro. Aggiungerò anche link e riferimenti tra le sezioni, come previsto dall'IA, per assicurarmi che la documentazione segua la mappa delle conoscenze elaborata in precedenza.

26 ottobre 2020-31 ottobre 2020: versione finale per la presentazione Collegherò tutti i file Markdown, creerò un sommario e condividerò le bozze con i mentori. che servirà da invio della prima bozza, sotto forma di pacchetto completo.

1° novembre 2020 - 5 novembre 2020: prima revisione In questi cinque giorni parlerò della prima bozza con i miei mentori. Riceverò il loro feedback e parlerò delle mie idee con loro per creare un elenco delle modifiche da apportare.

06 novembre 2020 - 12 novembre 2020: prime modifiche Con l'aiuto del feedback dei mentori, 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à saranno il punto di riferimento della fase di modifica.

13 novembre 2020 - 15 novembre 2020: seconda revisione Dopo aver completato le modifiche iniziali, parlerò ancora una volta dei progressi con i miei mentori e i team interessati. Queste discussioni si concentreranno sulle modifiche apportate alla prima versione e evidenziano anche eventuali altri problemi che potrebbero essere emersi durante il processo di modifica.

16 novembre 2020 - 19 novembre 2020: seconda modifica Dederò un periodo di quattro giorni alla modifica del documento. Le versioni prodotte in seguito verranno discusse con i mentori per dare loro una forma definitiva. Al termine di questa fase, i documenti saranno nella loro 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 vengono caricati sul sito web. Eventuali problemi riscontrati durante la procedura verranno risolti di conseguenza poiché avremo ancora qualche giorno per lavorare alla documentazione.

24 novembre 2020 - 28 novembre 2020: report sul progetto In questo periodo di cinque giorni verrà creato un report dettagliato del progetto. Gli obiettivi, le difficoltà, i problemi e le soluzioni presentati faranno parte del report del progetto. Il report verrà condiviso con i mentori per fornire il loro feedback.

29 novembre 2020 - 30 novembre 2020: presentazione finale Il progetto verrà inviato ai mentori insieme a tutti i file e alla relazione sul progetto. Verrà condotta una revisione dell'intero progetto attraverso un incontro o una discussione con i mentori e i team interessati.

Durante il progetto, continuerò a consultare i mentori per ricevere il loro prezioso feedback. Tutte queste tappe possono essere modificate in base alle discussioni con i mentori nei periodi di legame con la comunità e di revisione delle proposte.

Informazioni su di me Ho conseguito una laurea in Ingegneria elettrica e una laurea in comunicazione tecnica e professionale presso la North Carolina State University. Ho esperienza nei campi della scrittura e dell'editing tecnico e professionale, della comunicazione e della gestione dei contenuti, degli studi sull'usabilità web e mobile e nella progettazione di istruzioni. Ho lavorato come sub-editor per una pubblicazione online (Global Village Space) e come Communications Intern per Duke Forge presso la Duke University. Oltre a questo, mi interessa anche la scrittura creativa.