Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per la stagione dei documenti Google.
Riepilogo del progetto
- Organizzazione open source:
- Gateway gRPC
- Technical writer:
- iamrajiv
- Nome progetto:
- Refactoring del sito Documenti esistente di gRPC-Gateway
- Durata del progetto:
- Durata standard (3 mesi)
Project description
SINTESI:
Il sito dei documenti per gli utenti è progettato per aiutare gli utenti finali a utilizzare un prodotto o un servizio. Un buon sito di documenti per gli utenti è molto importante perché fornisce agli utenti un mezzo per imparare a utilizzare il software, le sue funzioni, suggerimenti, trucchi e anche risolvere problemi comuni che si verificano durante l'utilizzo del software. Inoltre, riduce i costi di assistenza ed è parte dell'identità aziendale del prodotto. Un buon sito di documenti per gli utenti è indice di integrità del prodotto, del team di sviluppatori. Senza un buon sito di documenti per gli utenti, un utente potrebbe non sapere come svolgere le operazioni sopra descritte in modo efficace ed efficiente. Il sito di documenti per gli utenti può svolgere un ruolo fondamentale nel garantire il successo di un prodotto perché un'ottima comunicazione è e sarà sempre al centro di qualsiasi attività o prodotto e un'ottima documentazione prende quella comunicazione e la colloca in un framework gestibile a cui tutti possono accedere per il successo.
Al momento della stesura di questo documento, il repository gRPC-Gateway è stato creato con un fork di circa 1200 volte e 184 persone hanno contribuito a questo repository, a dimostrazione del fatto che molte persone in tutto il mondo utilizzano il gateway gRPC e potrebbero voler leggere la relativa documentazione per gli utenti per indicazioni su come utilizzare il gateway gRPC. Tuttavia, il sito di documentazione e per gli utenti di gRPC-Gateway è attualmente obsoleto e incompleto e la community di gRPC-Gateway vuole utilizzare questo progetto per eseguire il refactoring del sito di documenti esistente migliorare il proprio sito di documenti per consentire agli utenti finali di avere un'esperienza senza interruzioni quando utilizzano il gateway gRPC.
STATO ATTUALE:
Attualmente, il sito della documentazione di gRPC-Gateway presenta due problemi principali:
• Il primo problema è rappresentato dal sito web di documenti non valido e obsoleto: lo stile e la struttura del sito e del tema utilizzati sono obsoleto, incompleti, difficili da navigare o da trovare informazioni. Non copre molte delle funzionalità del sito web per documenti di qualità. Il refactoring del sito Documenti esistente di gRPC-Gateway includerà lo stile del sito web, l'aggiunta di funzionalità come la ricerca dei documenti ecc., il miglioramento dell'interfaccia utente del sito web, l'organizzazione di tutorial ed esempi in una barra laterale adeguata e l'aggiornamento dei diagrammi di flusso e delle immagini esistenti progettandone uno nuovo e così via. Questo sarà il mio obiettivo principale e il mio lavoro si baserà maggiormente sullo stile e sulla ristrutturazione del sito di Documenti esistente.
• Il secondo problema è il refactoring della documentazione, dei tutorial e degli esempi esistenti di gRPC-Gateway, che può essere eseguito rimuovendo gli errori tipografici e grammaticali nei file, allineando correttamente gli snippet Go e refactoring degli snippet Go in base ai formati Gofmt. Inoltre, in questo caso possiamo aggiungere ulteriore documentazione, tutorial ed esempi, se necessario, oppure possiamo riutilizzare i file esistenti dopo il refactoring. Questo è il mio obiettivo secondario e lo farò una volta completato il mio obiettivo principale, ovvero lo stile e la ristrutturazione del sito di Documenti esistente.
PERCHÉ IL MIO SITO DI DOCUMENTI PROPOSTO È UN MIGLIORAMENTO DI QUELLO ATTUALE?
Il sito web proposto per i documenti per gli utenti sarà strutturato in modo da migliorare e garantire efficienza, coerenza e tranquillità per l'utente finale. L'interfaccia utente e le sezioni ben stilizzate daranno un aspetto migliore all'interfaccia e conterrà guide scritte e immagini e diagrammi di flusso associati.
La documentazione di gRPC-Gateway fornisce una buona descrizione del metodo e dell'esempio. Ma è ancora in uso il vecchio tema Jekyll e ai giorni nostri abbiamo temi Jekyll SSG (Static Site Generator) migliori. Inoltre, occorre ristrutturare le pagine e renderle più utili per gli utenti, aggiungendo nuovi esempi e tutorial, nonché aggiornando e riscrivendo i contenuti precedenti.
STRUTTURA E ROADMAP DEGLI OBIETTIVI E DELLE IDEE PROPOSTI:
OBIETTIVO PRINCIPALE DI QUESTO PROGETTO:
Gli obiettivi e le idee di cui sopra possono essere attuati nei seguenti modi:-
Il tema Jekyll attuale è stato spostato in un tema migliore e più solido. Il motivo per cui utilizzare di nuovo i temi Jekyll è che sarà facile per i manutentori contribuire e comprendere il flusso di lavoro del progetto poiché sono già a conoscenza del framework e del tema Jekyll esistenti, che è simile al nuovo tema Jekyll.
Dopo aver esaminato diversi temi Jekyll su Internet, ho trovato questa https://idratherbewriting.com/documentation-theme-jekyll/ suite di temi ideale per il sito di documenti gRPC-Gateway grazie alla seguente funzionalità:
• Markdown:- In questo modo i tecnici non devono preoccuparsi dell'installazione. Possono scrivere semplicemente nel file .md. Chiunque può fare clic sul pulsante di modifica visualizzato sul sito web (nuova funzionalità) e contribuire (modificare/suggerire modifiche alla pagina in GitHub) per migliorarla. In questo modo, gli utenti potranno aggiungere nuovi contenuti o modificarli per migliorarli.
• Ricerca nella documentazione:- L'utente deve disporre di una casella di ricerca per trovare facilmente e rapidamente i contenuti pertinenti.
• Sezione Commenti:- L'utente potrebbe avere la possibilità di commentare e condividere le proprie opinioni su post e tutorial. Possono leggere le visualizzazioni di altre persone sulla documentazione del progetto.
• Nuove note di rilascio e nuovi blog:- Il sito web dovrebbe essere aggiornato con nuovi post del blog e notizie sullo sviluppo e sulla roadmap attuali. Quindi dovrebbe essere presente un tipo di blog nella pagina di destinazione.
• Sviluppo veloce:- La maggior parte dei framework SSG (Static Site Generator) è in esecuzione sul server e le modifiche apportate ai file vengono immediatamente applicate all'interfaccia utente. Anche il processo di deployment e compilazione dovrebbe essere facile. Se in futuro vogliamo cambiare il framework, utilizziamo. Allora dovrebbe essere facile. La maggior parte dei framework supporta la scrittura Markdown, quindi è sufficiente spostare i file .md e apportare poche modifiche.
A questo punto, suddivido le pagine del sito web esistenti in nuove sezioni e pagine del sito web :
• Pagina di destinazione:-
La pagina di destinazione deve evidenziare le funzionalità principali di gRPC-Gateway.
- Introduzione a gRPC-Gateway (reindirizzamento alla guida dell'utente)
- Istruzioni di installazione semplici (breve comandi)
- Perché utilizzare gRPC-Gateway
- Progetto con gateway gRPC
Quindi l'idea di base è piuttosto che scrivere una descrizione lunga, mostrare i punti principali nella pagina di destinazione e fornire il link per andare per i dettagli.
• Pagina della guida dell'utente di gRPC-Gateway:-
- Guida all'installazione.
- Guida rapida con gRPC-Gateway.
• Pagina della guida per gli sviluppatori di gRPC-Gateway:-
Guida per lo sviluppo, guida per i contributi, configurazione di Git, codice di condotta, configurazione della documentazione, flusso di lavoro di sviluppo ecc. rimandano a pagine simili all'interno. Di conseguenza, è necessario eseguire il refactoring e la disposizione di tutti i file. La pagina di sviluppo principale deve contenere tutte queste pagine e a ogni passaggio verrà creato il link ipertestuale.
• Informazioni sulla pagina gRPC-Gateway:-
L'elenco di tutti i collaboratori deve essere presente nelle sezioni del team Link rapidi e note di rilascio; verranno aggiunti i blog più recenti per coinvolgere l'utente e fargli leggere le novità attuali di gRPC-Gateway.
• Pagina Blog, note di rilascio ed esercitazioni:-
Ritengo che sul sito web dovrebbe essere disponibile un'opzione di blog. In questo modo, le notizie e le uscite possono essere comunicate facilmente. La pagina del tutorial conterrà alcuni interventi e articoli popolari che chiariscono le API e i concetti di gRPC-Gateway. I collaboratori possono aggiungere i link ai propri tutorial nella pagina del tutorial.
Dopo aver completato l'attività precedente, aggiorna le stesse modifiche al ramo v2 e apporta le stesse modifiche anche con il ramo master di gRPC-Gateway.
OBIETTIVO SECONDARIO DI QUESTO PROGETTO:
Sono necessarie altre modifiche per rendere la documentazione di gRPC-Gateway più solida e leggibile:
• Correggere gli errori grammaticali e tipografici e organizzare e allineare i link e i post nel sito in tutti i file esistenti di gRPC-Gateway.
• Aggiunta di ulteriore documentazione e contenuti, se necessario, in gRPC-Gateway poiché la maggior parte delle funzionalità dispone di una documentazione molto breve, come nella sezione Documentazione del sito su AWS, background, utilizzo e così via.
• Refactoring degli snippet Go su gRPC-Gateway in base ai formati Gofmt
Dopo aver completato l'attività precedente, aggiorna le stesse modifiche al ramo v2 e apporta le stesse modifiche anche con il ramo master di gRPC-Gateway.
PERCHÉ SONO LA PERSONA GIUSTA PER QUESTO PROGETTO:
Credo di essere la persona giusta per questo progetto perché:
• Ho esperienza nel miglioramento della documentazione delle organizzazioni e posso usare qualsiasi sistema di controllo della versione, quindi l'esecuzione di comandi su GitHub non sarà un problema. • Inoltre, ciò che mi spinge è lavorare su progetti che creano valore per le persone. Credo che se vuoi che qualcuno faccia qualcosa nel modo più efficiente possibile, la documenti. Documentando i tuoi processi, garantisci efficienza, coerenza e tranquillità per tutte le persone coinvolte. • Conosco il flusso di lavoro e il codebase di gRPC-Gateway poiché sto contribuendo a gRPC-Gateway negli ultimi due mesi e ho unito 11 PR.