Fase attuale:
Il programma per la stagione dei documenti 2020 è terminato il 15 marzo 2021. Consulta la cronologia.
Questa pagina contiene le linee guida per i tecnici su come creare un report di progetto al termine del lavoro per la stagione dei documenti di quest'anno.
Inviare il report sul progetto
Quando si apre la fase di finalizzazione del progetto, potrai inviare la relazione sul progetto compilando un modulo che sarà disponibile nella sezione di finalizzazione del progetto della guida per il Technical Writer.
Informazioni da includere nel report sul progetto
Questa sezione descrive il tipo di informazioni che puoi fornire nel report del progetto. Il report sul progetto includerà campi a testo libero e domande a scelta multipla.
Link al tuo lavoro
Fornisci un link che rimandi a una descrizione del lavoro svolto.
Il link dovrebbe indirizzare a un documento che contiene una breve descrizione del lavoro svolto, la documentazione che il progetto open source ha unito nel proprio repository, un riepilogo dello stato attuale del progetto e un elenco di difficoltà e conoscenze.
Il link verrà visualizzato nei risultati relativi alla stagione dei documenti pubblicati sul sito web. I risultati pubblicati dimostrano il lavoro che hai completato durante il programma. I risultati pubblicati sono anche un ottimo modo per fare riferimento al tuo lavoro come parte del curriculum.
Dovresti condividere il link con il tuo mentore e chiedere una revisione prima di inviare il report sul progetto.
Requisiti per il report di progetto
Tieni presente i seguenti requisiti:
- I contenuti a cui rimanda il link devono consentire di identificare facilmente il lavoro completato durante la stagione dei documenti, ovvero le modifiche apportate o la nuova documentazione scritta.
- L'opera deve trovarsi in una posizione stabile. Non puoi modificare l'URL dopo l'invio.
Qualcun altro dovrebbe essere in grado di utilizzare i contenuti nella destinazione del link (o a cui si fa riferimento) per sviluppare a partire dal tuo lavoro.
- Se hai completato al 100% il tuo lavoro, altre persone dovrebbero essere in grado di utilizzarlo.
- Se il tuo lavoro non è completo al 100%, dovrebbe essere chiaro cosa è rimasto da fare.
Esempi corretti di come descrivere il tuo lavoro
Non devi eseguire tutte queste operazioni o nessuna di queste operazioni, ma puoi soddisfare i requisiti indicati di seguito.
Crea un post del blog, una pagina web o un gist pubblico GitHub che descriva il tuo lavoro e che rimandi ai commit che hai eseguito e ai repository su cui hai lavorato. Se c'è ancora del lavoro da fare sul progetto, includi una descrizione di tale lavoro. Puoi anche condividere i momenti salienti o i pezzi stimolanti.
Questa è l'opzione migliore, perché ti consente di includere facilmente molte informazioni. Questa è un'ottima cosa, perché mostra chiaramente il lavoro che hai svolto e permette agli altri di utilizzarlo e capire facilmente il tuo contributo.
Se utilizzi GitHub e tutto il tuo lavoro è coperto da una singola richiesta di pull, puoi utilizzare il link.
- Assicurati che la descrizione della richiesta di pull sia dettagliata.
- Assicurati che la descrizione indichi chiaramente che l'opera si riferisce alla stagione dei documenti.
- Se la richiesta di pull richiede più operazioni al termine della stagione di Documenti, assicurati che l'impegno dell'ultima stagione di Documenti lo rilevi.
- Questo metodo di presentazione di un report sul progetto offre il vantaggio di avere il log delle modifiche, un elenco di commit e i commenti della revisione in un unico posto.
Se il tuo repository GitHub è destinato esclusivamente a Season of Docs, aggiungi un file README contenente i dettagli del tuo lavoro.
Crea una cartella pubblica su Google Drive e includi tutte le patch che hai creato.
Crea un foglio di lavoro pubblico con Fogli Google ed elenca tutti i tuoi commit.
Inserisci un link a un singolo problema in un Issue Tracker pubblico, che contiene riferimenti chiari al tuo lavoro e qualsiasi altra informazione appropriata. Il problema dovrebbe tenere traccia di tutto il lavoro che hai svolto. Assicurati che il problema elenchi tutti i commit oppure che sia facile trovarli in un altro modo.
Inserisci un link a una differenza unificata o di contesto delle modifiche. Assicurati di includere un'intestazione che includa il nome del tuo progetto di scrittura tecnica e chi sei, in modo che sia utile per gli altri.
Esempi sbagliati di come descrivere il tuo lavoro
Non eseguire queste operazioni:
- Link a un file tarball o ZIP contenente il codice sorgente dell'intero progetto o la directory di lavoro.
- Link all'inizio del repository di codice sorgente principale del progetto. Ad esempio, se stai lavorando su cpython, questo link non è utile: https://github.com/python/cpython.
- Link al clone del repository di codice sorgente del progetto. Questo rende difficile capire quali sono le modifiche che hai apportato, perché il tuo lavoro è misto a quello degli altri.
- Link alla descrizione del progetto sul sito web Season of Docs (Stagione dei documenti).
Per i mentori
Aiuta il tuo Technical Writer a creare un report di progetto adeguato. È importante farlo prima di creare la tua valutazione del lavoro del Technical Writer.
Controlla quanto segue:
- I contenuti inviati devono soddisfare i requisiti descritti sopra.
- La presentazione deve includere una descrizione del lavoro svolto, i requisiti soddisfatti e i motivi di eventuali decisioni specifiche prese.
L'idea di Season of Docs non è che i tecnici sviluppano molti documenti. È importante che il lavoro sia potenzialmente utile per il progetto open source di hosting.