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:
- gRPC-Gateway
- Redattore tecnico:
- iamrajiv
- Nome del progetto:
- Refactoring del sito di documentazione esistente di gRPC-Gateway
- Durata del progetto:
- Durata standard (3 mesi)
Project description
RIASSUNTO:
Il sito della documentazione per gli utenti è progettato per aiutare gli utenti finali a utilizzare un prodotto o un servizio. Un sito di documentazione per gli utenti è molto importante perché offre agli utenti un modo per imparare a utilizzare il software, le sue funzionalità, suggerimenti e trucchi e anche per risolvere i problemi comuni riscontrati durante l'utilizzo del software. Inoltre, riduce i costi di assistenza e fa parte dell'identità aziendale del prodotto. Un buon sito di documenti utente è un segno dello stato di salute del prodotto, il team degli sviluppatori. Senza un buon sito di documentazione per gli utenti, un utente potrebbe non sapere come eseguire le operazioni precedenti in modo efficace ed efficiente. Il sito della documentazione per gli utenti può svolgere un ruolo fondamentale per garantire il successo di un prodotto perché una comunicazione efficace è e sarà sempre al centro di qualsiasi attività o prodotto e una documentazione efficace prende questa comunicazione e la inserisce in un framework gestibile a cui tutti possono accedere per ottenere risultati.
Al momento della stesura di questo documento, è stato eseguito il fork del repository gRPC-Gateway di circa 1200 volte e 184 persone hanno contribuito a questo repository. Ciò dimostra che molte persone in tutto il mondo utilizzano gRPC-Gateway e potrebbero voler leggere la relativa documentazione utente per ottenere indicazioni su come utilizzare gRPC-Gateway. Tuttavia, la documentazione utente e il sito di documentazione di gRPC-Gateway sono attualmente obsoleti e incompleti e la community di gRPC-Gateway vuole utilizzare questo progetto per eseguire il refactoring del sito di documentazione esistente e migliorarlo in modo che gli utenti finali possano avere un'esperienza senza interruzioni quando utilizzano gRPC-Gateway.
STATO ATTUALE:
Attualmente, il sito dei documenti di gRPC-Gateway presenta due problemi principali:
• Il primo problema è un sito web di documentazione scadente e obsoleto, ovvero lo stile e la struttura del sito e del tema utilizzati sono obsoleti, incompleti, difficili da navigare o trovare informazioni e non coprono molte funzionalità di un buon sito web di documentazione. Il refactoring del sito Docs esistente di gRPC-Gateway includerà lo stile del sito web, l'aggiunta di funzionalità come la ricerca di documenti e così via, 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 mediante la progettazione di un nuovo diagramma e così via. Questo sarà il mio obiettivo principale e il mio lavoro si baserà maggiormente sullo stile e sulla ristrutturazione del sito Docs esistente.
• Il secondo problema è che è necessario eseguire il refactoring della documentazione, dei tutorial, degli esempi e così via esistenti di gRPC-Gateway, il che può essere fatto rimuovendo gli errori ortografici e grammaticali nei file, allineando correttamente gli snippet Go e eseguendo il refactoring degli snippet Go in base ai formati Gofmt. Inoltre, se necessario, possiamo aggiungere documentazione, tutorial ed esempi aggiuntivi, se necessario, oppure riutilizzare i file esistenti dopo il refactoring. Questo è il mio obiettivo secondario e lo farò dopo aver completato il mio obiettivo principale, ovvero lo stile e la ristrutturazione del sito Documenti esistente.
PERCHÉ IL SITO DI DOCUMENTI CHE PROPONGO È UN MIGLIORAMENTO RISPETTO A QUELLO ATTUALE?
Il sito web proposto per la documentazione utente sarà strutturato per migliorare e garantire efficienza, coerenza e tranquillità per un utente finale. Offrirà un aspetto e un'interfaccia utente migliori con sezioni e funzionalità ben stilizzate che contengono guide scritte, nonché diagrammi di flusso e immagini associati.
La documentazione di gRPC-Gateway fornisce una buona descrizione del metodo e dell'esempio. Tuttavia, utilizza ancora il vecchio tema Jekyll e oggi abbiamo temi Jekyll SSG (Static Site Generator) migliori. Inoltre, è necessario ristrutturare le pagine e renderle più utili per gli utenti aggiungendo nuovi esempi e tutorial, nonché aggiornare e riscrivere i contenuti precedenti.
STRUTTURA E ROADMAP DEGLI OBIETTIVI E DELLE IDEE PROPOSTE:
SCOPO PRINCIPALE DI QUESTO PROGETTO:
Gli obiettivi e le idee sopra indicati possono essere implementati nei seguenti modi:
Passaggio dal tema Jekyll attuale a un tema migliore e più solido. Il motivo per usare di nuovo i temi Jekyll è che per i manutentori sarà facile contribuire e comprendere il flusso di lavoro del progetto, dato che sono già a conoscenza del framework e del tema Jekyll esistente, che è simile al nuovo tema Jekyll.
Dopo aver esaminato diversi temi Jekyll su internet, ho trovato questa suite di temi https://idratherbewriting.com/documentation-theme-jekyll/ più adatta al sito di documentazione di gRPC-Gateway per la seguente funzionalità:
• Markdown:- in modo che i redattori tecnici non debbano preoccuparsi dell'installazione. Possono scrivere semplicemente nel file .md. Chiunque può fare clic sul pulsante di modifica mostrato sul sito web (nuova funzionalità) e contribuire (modificare/suggerire modifiche alla pagina su GitHub) per migliorarla. In questo modo, gli utenti potranno aggiungere nuovi contenuti o modificarli per migliorarli.
• Ricerca nella documentazione: gli utenti devono avere una casella di ricerca per trovare facilmente e rapidamente i contenuti pertinenti.
• Sezione dei commenti: l'utente potrebbe avere la possibilità di commentare e condividere le sue opinioni su post e tutorial. Possono leggere le opinioni di altre persone sulla documentazione del progetto.
• Nuove note di rilascio e blog: il sito web deve essere aggiornato con nuovi post del blog e notizie sullo sviluppo e sulla roadmap attuali. Pertanto, nella pagina di destinazione deve essere presente un tipo di blog.
• Sviluppo rapido: la maggior parte dei framework SSG (Static Site Generator) viene eseguita sul server e le modifiche al file vengono applicate immediatamente all'interfaccia utente. Inoltre, il processo di deployment e compilazione deve essere semplice. In futuro, se vogliamo cambiare il framework, utilizzeremo. Dovrebbe essere facile. La maggior parte dei framework supporta la scrittura in Markdown, quindi dovrebbe essere sufficiente spostare i file .md e apportare alcune modifiche.
Qui divido 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 che utilizza gRPC-Gateway
L'idea di base è che, anziché scrivere una descrizione lunga, mostri i punti principali nella pagina di destinazione e fornisca il link per visualizzare i dettagli.
• Pagina della guida dell'utente di gRPC-Gateway:
- Guida all'installazione.
- Guida rapida all'utilizzo di gRPC-Gateway.
• Pagina della guida per gli sviluppatori di gRPC-Gateway:
Guida allo sviluppo, Guida ai contributi, Configurazione di Git, Codice di condotta, Configurazione della documentazione, Flusso di lavoro di sviluppo e così via rimandano a pagine simili all'interno. Di conseguenza, è necessario eseguire il refactoring e riorganizzare tutti i file. La pagina Sviluppo principale deve contenere tutte queste pagine e in ogni passaggio verrà creato il link ipertestuale.
• Pagina Informazioni su gRPC-Gateway:
L'elenco di tutti i collaboratori deve essere presente nelle sezioni del team. I link rapidi e le note di rilascio, gli ultimi blog verranno aggiunti per coinvolgere l'utente e fargli leggere le ultime notizie su gRPC-Gateway.
• Pagina Blog, note di rilascio e tutorial:-
Ritengo che il sito web dovrebbe avere un'opzione di blogging. In questo modo, notizie e release possono essere comunicate facilmente. La pagina del tutorial conterrà alcuni talk e articoli popolari che chiariscono i concetti e le API 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 nel ramo v2 e apporta le modifiche anche con il ramo master di gRPC-Gateway.
SCOPO SECONDARIO DI QUESTO PROGETTO:
Per rendere la documentazione di gRPC-Gateway più solida e leggibile, sono necessarie altre modifiche:
• Correzione di errori grammaticali e tipografici, nonché organizzazione e allineamento di link e 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à ha una documentazione molto breve, ad esempio nella sezione Documentazione del sito su AWS, Informazioni generali e Utilizzo e così via.
• Rifacimento degli snippet Go gRPC-Gateway in base ai formati Gofmt
Dopo aver completato l'attività precedente, aggiorna le stesse modifiche nel ramo v2 e apportale anche al 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 utilizzare qualsiasi sistema di controllo della versione, quindi l'esecuzione di comandi su GitHub non sarà un problema. • Inoltre, ciò che mi spinge è lavorare a progetti che creano valore per le persone. Credo che se vuoi che qualcuno faccia qualcosa nel modo più efficiente possibile, devi documentarlo. Documentando i processi, garantisci efficienza, coerenza e tranquillità a tutte le persone coinvolte. • Conosco il flusso di lavoro e la base di codice di gRPC-Gateway perché contribuisco a questo progetto da due mesi e ho unito 11 PR.