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:
- Django
- Redattore tecnico:
- Gabbyprecious
- Nome del progetto:
- Riscrivere la guida ai contributi per renderla più facile da usare e da navigare
- Durata del progetto:
- Durata standard (3 mesi)
Project description
ABSTRACT
Lo scopo della guida ai contributi di Django, come di ogni altra documentazione, è guidare gli utenti, in questo caso i collaboratori open source, su come e dove possono contribuire a rendere Django migliore e sostenibile.
C'è sempre bisogno di creare documentazione, soprattutto se interessa molto la community e Django stesso.
L'obiettivo di Django per il Google Summer of Docs di quest'anno è rendere la guida per i collaboratori meno complessa, più accessibile e più accattivante. Questo è un obiettivo essenziale perché incoraggia i collaboratori, tra cui mi annovero, a iniziare a contribuire a questo fantastico framework.
Stato attuale
Lo stato attuale della documentazione, che puoi trovare qui, non è molto utile come guida perché è troppo complessa e non ben strutturata, inoltre non aiuta a comprendere meglio il contributo in Django e non è ben accolta dai nuovi collaboratori.
Obiettivi del progetto
Ho discusso i miei suggerimenti per la documentazione con il mio mentore, Carlton Gibson, nel forum e mi ha confermato che aiuteranno a risolvere il problema con la documentazione attuale. Ecco gli obiettivi che intendo raggiungere con la ristrutturazione del documento: Ristrutturazione del documento Aggiunta di indicazioni su cosa fare e cosa non fare per ogni sezione Creazione di singole pagine per sezioni banali come Richiesta e creazione di funzionalità Documentazione ridotta e diretta al punto Glossario di parole Indice interno creato per seguire la nuova guida Scrivere una documentazione più facile da comprendere Segmentazione dei contenuti in due parti principali (sezione per principianti e collaboratori avanzati) Creare una guida e uno stile per i nuovi autori/collaboratori tecnici, per mantenere aggiornata la documentazione e rispettare gli standard.
La documentazione attuale è già rivolta a collaboratori esperti e non offre opportunità ai collaboratori nuovi e principianti sia di open source che di Django. Ecco alcuni contenuti aggiuntivi per i principianti: Sezione che guida diversi set di collaboratori(redattori tecnici, designer e sviluppatori) Una pagina che documenta i problemi dei primi utenti e i problemi semplici che possono essere risolti. Segui qualche sezione nella documentazione attuale, riscrivila e aggiungila alla sezione per principianti. Sezioni che spiegano i punti chiave o le parole utilizzate nella sezione avanzata.
Cronologia
Di seguito è riportata una suddivisione di come voglio lavorare all'obiettivo del progetto elencato sopra con il calendario fornito da Google.
Settimana di affiatamento con la community( 17 agosto - 13 settembre) Interagire di più con la community Continuare a contribuire alla documentazione Ricevere più suggerimenti dai collaboratori Ulteriori studi sulla documentazione attuale e sugli strumenti previsti Settimana 1 - settimana 4 Iniziare a suddividere la documentazione in base ai livelli Creare la sezione della documentazione per principianti Settimana 4 - 6 Selezionare i "da fare" e i "da non fare" Scrivere i "da fare" e i "da non fare" per le sezioni Pagine aggiuntive per le sezioni Settimana 7 - 9 Riscrivere e spostare la documentazione attuale nella guida per i collaboratori avanzati Documentazione ridotta Settimana 10 - 12 Preparare il glossario Aggiornare l'indice interno alla nuova documentazione Creare una guida e uno stile per i nuovi autori/collaboratori tecnici
Strumenti
Sphinx: strumento attuale per la documentazione attuale. Leggi la documentazione.
Perché questo progetto?
Credo fermamente nella documentazione e negli articoli ben scritti che riguardano chiunque al mondo. A parte questo, sono anche un appassionato di Django e Open Source nel suo complesso. Ho intenzione di contribuire a Django come principiante e penso che questo sia un modo perfetto per dare il mio contributo al mio strumento preferito, oltre a familiarizzare con la base di codice per offrire un maggiore contributo come sviluppatore(e scrittore tecnico). Sarà bello e piacevole lavorare con un'organizzazione che sia in linea con le mie opinioni ed è stato un ottimo strumento per tutta la mia carriera.
Perché sono la persona giusta per questo progetto?
Credo di essere la persona giusta in base ai seguenti aspetti: contribuisco a Django scrivendo articoli per aiutare i principianti a comprendere meglio il concetto di Django. Essendo uno sviluppatore e non vedo l'ora di contribuire a Django, capisco la necessità di collaborare con altri sviluppatori e di come documentarli bene per loro. Sono un giocatore di squadra e lavorerò bene con una supervisione più o meno stretta del mio mentore Carlton Gibson.