Idee per progetti

Fase attuale:
Il programma per la stagione dei documenti 2019 è terminata il 6 marzo 2020. Consulta la cronologia.

Le idee per progetti sono suggerimenti di un'organizzazione open source per progetti che un Technical Writer può completare in collaborazione con un mentore durante la stagione di Documenti.

Le informazioni in questa pagina sono rivolte agli amministratori e ai mentori di organizzazioni open source che stanno preparando l'elenco delle idee per i progetti. Le informazioni sono utili anche per i Technical Writer come base per la partecipazione delle organizzazioni alla stagione dei documenti.

Progetti di esempio

Di seguito sono riportate alcune idee del tipo di progetto che un Technical Writer può affrontare:

  • Crea un sito di documentazione su una piattaforma a scelta del Technical Writer e del Mentore dell'open source e pubblica un insieme iniziale di documenti di base sul sito. Ecco alcuni esempi di piattaforme:

  • Esegui il refactoring della documentazione esistente del progetto open source per offrire un'esperienza utente migliore o un'architettura delle informazioni più accessibile.

  • Scrivi una panoramica concettuale o un'introduzione a un prodotto o una funzionalità. Spesso un team crea la propria documentazione tecnica dal basso verso l'alto, con il risultato che sono molti i dettagli, ma è difficile comprendere il prodotto nel suo complesso. Un Technical Writer può risolvere il problema.

  • Crea un tutorial per un caso d'uso di alto profilo.

  • Crea una serie di guide illustrative mirate per attività specifiche.

  • Crea una guida per i collaboratori che includa informazioni di base su come iniziare in qualità di collaboratore al progetto open source, nonché tutte le regole relative ai contratti di licenza, le procedure per le richieste di pull e le revisioni, la creazione del progetto e così via.

Le idee di cui sopra variano intenzionalmente in termini di portata e dimensione. Il tempo impiegato da ogni progetto dipende da una serie di fattori, tra cui le dimensioni del set di documentazione, la complessità del prodotto, l'esperienza del Technical Writer e dei Mentori open source, gli strumenti e i processi offerti dal progetto open source e altro ancora.

L'obiettivo dell'elenco riportato sopra è aiutarti a iniziare. Puoi proporre anche altri tipi di progetti.

Pubblica l'elenco di idee per i progetti

Dovresti pubblicare le idee per il tuo progetto su una pagina web pubblica, in un post del blog o in qualche altro documento visibile pubblicamente.

La pagina delle idee per il progetto deve includere:

  • Informazioni sulla tua organizzazione open source:

    • Nome dell'organizzazione.
    • Descrizione dell'organizzazione.
    • Un link al tuo repository open source e/o al tuo sito web.
    • (Facoltativo) Un indirizzo email per contattare la tua organizzazione in merito alla stagione di Documenti. Deve essere uguale all'indirizzo email che includi nel modulo di richiesta della tua organizzazione per la stagione dei documenti.
    • (Facoltativo) Informazioni sull'amministrazione e sui mentori della tua organizzazione, ad esempio i loro nomi visualizzati. Dovrebbero essere uguali ai nomi visualizzati che includi nel modulo di richiesta della tua organizzazione per la Stagione di Documenti.

  • Un annuncio che informa che la tua organizzazione ha richiesto di partecipare alla stagione di Documenti di quest'anno. La pagina relativa a promozione e stampa include loghi e altri contenuti che puoi utilizzare quando si parla della stagione dei documenti.

  • Le idee per il progetto, incluse le informazioni descritte di seguito per ogni idea di progetto.

Quando crei l'applicazione della tua organizzazione per la stagione dei documenti, devi includere un link alla pagina delle idee per il progetto.

Informazioni in ogni idea di progetto

Ogni idea di progetto deve includere almeno le seguenti informazioni:

  • Nome del progetto: scegli un titolo conciso ma descrittivo.
  • Descrizione: una descrizione più lunga del lavoro di documentazione richiesto. Descrivi dettagliatamente la tua idea iniziale. Offri a tutti i tecnici interessati l'opportunità di ampliare o perfezionare l'idea.

  • Materiale correlato:

    • Link al progetto open source che richiede la documentazione.
    • Se intendi proporre un progetto di scrittura tecnica che prevede l'aggiornamento di un set di documentazione esistente, inserisci un link al set di documentazione.
    • Se intendi proporre un tutorial o un insieme di guide illustrative, descrivi le funzionalità o i casi d'uso che richiedono una documentazione.
    • Se intendi proporre una guida per i collaboratori, inserisci un link a un file README esistente o ad altro materiale pertinente, se presente. Se non c'è ancora nulla, va bene dirlo.
    • Includi link a documentazione simile in altri progetti, se pertinente.

L'importanza delle idee per il progetto

Le idee per i tuoi progetti sono importanti in vari modi:

  • Lavorare alle idee aiuta la tua organizzazione a formulare le attività di documentazione necessarie e a prepararsi a lavorare con un Technical Writer.
  • Le idee per il progetto offrono agli amministratori del programma Google un'indicazione del tipo di lavoro che un Technical Writer affronterà quando entrano in una relazione di tutoraggio con la tua organizzazione. Gli amministratori del programma Google utilizzano le idee di progetto per valutare l'impegno dell'organizzazione a partecipare alla stagione di Documenti e fare da mentore a un Technical Writer durante il programma.
  • Le idee per il progetto attirano Technical Writer interessati nella tua organizzazione. Possono utilizzare i progetti che hai suggerito come base per le proprie proposte di progetto.
  • La pagina relativa a promozione e stampa include loghi e altri contenuti che puoi utilizzare quando si parla della stagione dei documenti.
  • Questo video di PyCon Australia 2017 offre suggerimenti su come organizzare la documentazione in modo che le persone la trovino utile: Cosa dice nessuno sulla documentazione di Daniele Procida.