Progetto ScummVM

Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per Google Season of Docs.

Riepilogo del progetto

Organizzazione open source:
ScummVM
Technical writer:
Cadi
Nome progetto:
Lancia un portale di documentazione
Durata del progetto:
Durata standard (3 mesi)

Project description

Obiettivi.

  • produrre documentazione per l'utente finale di alta qualità con controllo delle versioni, consolidando grandi quantità di informazioni provenienti da fonti diverse e riscrivendole per garantire chiarezza, coerenza e completezza.
  • La documentazione deve essere di facile comprensione per i principianti, senza essere confidenziale per gli utenti esperti di tecnologia.
  • Per creare un portale di documentazione utilizzando un generatore di siti statici.
  • Rendere a prova di futuro la documentazione dell'utente finale creando modelli e istruzioni dettagliate per i futuri collaboratori open source.

Situazione attuale:

  • La documentazione di ScummVM disponibile è distribuita tra più fonti.
  • Le informazioni sono difficili da trovare e spesso duplicate; è facile perdersi in pagine poco chiare.
  • È difficile sapere quali informazioni sono aggiornate e quali non sono aggiornate.
  • Alcune informazioni mancano o sono incomplete.

Come risolvere il problema:

Struttura della documentazione suggerita:

Pagina di destinazione |-- Guida introduttiva | -- Quick start guide |-- Installing ScummVM | |-- Nintendo 3DS | |-- AmigaOS | |-- Android | |-- (every) | |-- (common) | |-- (supported) |-- (piattaforma) |-- Utilizzo di ScummVM | |-- Avvio app | |-- Impostazioni globali | |-- Impostazioni del gioco | -- Keyboard shortcuts |-- Advanced options | |-- Cloud and LAN | |-- Control Mapping | |-- Configuration | |-- Command line options | |-- Graphics |-- Musica e audio |-- Guida | |-- Domande frequenti | |-- Contatti | |-- Problemi noti | -- Reporting a bug |-- Game Notes-- Note di rilascio

  • Guida introduttiva:

I nuovi utenti spesso cercano una guida rapida per iniziare a lavorare il più velocemente possibile. Sebbene l’installazione di ScummVM possa essere complessa su alcune piattaforme, l’installazione su un computer non lo è.

La guida rapida dovrebbe trattare i seguenti argomenti:

  • Come installare ScummVM su Windows, Mac e Linux

  • Come caricare, aggiungere e avviare un gioco.

  • Installazione di ScummVM:

Nei casi in cui l'installazione non sia intuitiva o in cui l'utente potrebbe non avere una base tecnica solida, l'utente ha bisogno di una guida completa per l'installazione di ScummVM su una qualsiasi delle piattaforme supportate.

Ogni pagina di installazione completa deve comprendere quanto segue:

  • Eventuali requisiti/prerequisiti di sistema.
  • Come scaricare la versione appropriata di ScummVM.
  • Come installare ScummVM.
  • Come caricare i giochi sulla piattaforma scelta, specialmente se non si tratta della piattaforma per cui il gioco è stato progettato.

  • Come avviare ScummVM, aggiungere e lanciare un gioco.

  • Utilizzo di ScummVM:

Gli utenti hanno bisogno di documenti di riferimento che spieghino come utilizzare ScummVM.

I documenti di riferimento devono riguardare quanto segue:

  • L'interfaccia di Avvio app; l'aspetto di ogni finestra e scheda e il loro funzionamento.
  • Una spiegazione delle impostazioni disponibili, sia globali che specifiche del gioco.

  • Scorciatoie da tastiera/tasti di scelta rapida.

  • Opzioni avanzate:

Gli utenti esperti hanno bisogno di informazioni aggiuntive e più tecniche sulle opzioni a loro disposizione per modificare le modalità di esecuzione dei giochi.

  • Note sul gioco:

Qualsiasi informazione specifica del gioco che l'utente deve conoscere; inclusi, a titolo esemplificativo: - Caratteristiche dell'installazione - Eventuali file aggiuntivi richiesti - Controlli insoliti o diversi

  • Problemi noti:

Questa sezione deve contenere eventuali bug noti specifici della release.

  • Note di rilascio:

Anche se la nostra documentazione passerà al controllo delle versioni, potrebbe essere utile inserire una sezione per le note di rilascio per fornire un riepilogo delle modifiche apportate nell'ultima release. Potrebbero essere incluse alcune aree che attualmente non rientrano nell'ambito di questa documentazione, come i giochi appena supportati o le informazioni sui nuovi motori.

Piano di attacco:

Propongo di iniziare creando un modello per le pagine di installazione di ScummVM, poiché sarà il modo più semplice per ottenere le informazioni di cui ho bisogno dai gestori/sviluppatori delle porte (soprattutto nei casi in cui queste informazioni sono scarse o non esistono). Precompilano tutte le informazioni già in mio possesso estratte dalla documentazione esistente, che potranno poi essere verificate per verificarne la completezza, l'accuratezza e la valuta o eventualmente aggiunte.

Quindi, esaminerò la documentazione esistente: README, wiki e sito web. Mentre procedo, riscriverò le informazioni e le aggiungerò a ogni sezione come richiesto, poi inserirò tutte le informazioni nel nuovo portale. Prenderò inoltre nota di quali informazioni vengono estratte da dove, per garantire che una volta attivato il portale non vi siano duplicati, contraddizioni o altre anomalie.

Durante tutto il corso, collaborerò con i mentori, gli sviluppatori, i gestori del porto e qualsiasi altro esperto in materia per reperire le informazioni mancanti, oltre a garantire che ogni pagina sia il più aggiornata e completa possibile.

Nello spirito di collaborazione e con l'approvazione del mentore o dei mentori, vorrei che il portale dei lavori in corso fosse accessibile alla comunità ScummVM durante l'intero processo di scrittura, per ricevere feedback in tempo reale e garantire che non perda nulla durante il processo.

Suggerisco di utilizzare una guida di stile, ad esempio la guida di stile della documentazione per gli sviluppatori di Google, per garantire la coerenza di questo corpus e di tutta la documentazione in futuro.

Dove possibile, utilizzerò screenshot, GIF e altri elementi visivi per migliorare la comprensione.

Tempistica proposta:

Community bonding 17 agosto - 13 settembre 2020

Continua a parlare con i mentori e con l'ampia community di ScummVM per perfezionare la visione del progetto e finalizzare i dettagli come la struttura e i contenuti dei documenti.

Settimana 1 14 settembre - 20 settembre

  • Crea un modello per le pagine di installazione specifiche per la piattaforma.
  • Precompila i modelli con eventuali informazioni esistenti e distribuiscili agli sviluppatori/gestori della porta appropriati per ulteriori informazioni.

Settimana 2 21 settembre - 27 settembre

  • Configura il nuovo portale di documentazione.

Settimana 3 28 settembre - 4 ottobre

Utilizzo di ScummVM: - L'interfaccia - Impostazioni globali Installazione di ScummVM: - Guide all'installazione specifiche per la piattaforma man mano che vengono restituiti i modelli completati.

Settimana 4 5 ottobre - 11 ottobre

Utilizzo di ScummVM: - Impostazioni del gioco - Scorciatoie da tastiera Installazione di ScummVM: - Guide di installazione specifiche per la piattaforma man mano che vengono restituiti i modelli completati

Settimana 5 12 ottobre - 18 ottobre

Opzioni avanzate: - Cloud e LAN - Mapping di controllo Installazione di ScummVM: - Guide all'installazione specifiche per la piattaforma man mano che vengono restituiti i modelli completati

Settimana 6 19 ottobre - 25 ottobre

Opzioni avanzate: - Configurazione - Opzioni della riga di comando Installazione di ScummVM: - Guide all'installazione specifiche per la piattaforma quando vengono restituiti i modelli completati

Settimana 7 26 ottobre - 1° novembre

Opzioni avanzate: - Grafica - Audio Installazione di ScummVM: - Guide di installazione specifiche per la piattaforma man mano che mi vengono restituiti i modelli completati

Settimana 8 2 novembre - 8 novembre

Guida: - Domande frequenti - Contatti - Problemi noti

Installazione di ScummVM: - Guide all'installazione specifiche per la piattaforma, man mano che mi vengono restituiti i modelli completati

Settimana 9 9 novembre - 15 novembre

Guida: - Segnalazione di un bug - Note sul gioco - Note di rilascio

Installazione di ScummVM: - Finalizza le guide alla piattaforma non ancora completate.

Settimana 10 16 novembre - 22 novembre

  • Modifiche finali, correzioni di bozze e finalizzazione di qualsiasi decisione relativa al portale, ad esempio la navigazione nella barra laterale, modifiche a tema/CSS e così via.
  • Assicurati che tutti i link funzionino come previsto.
  • Controlla che le immagini e le GIF vengano visualizzate correttamente.

Settimana 11 23 novembre - 30 novembre

  • Finalizza gli elementi in sospeso e lancia ufficialmente il portale.
  • Una volta avviato il portale, rimuovi le informazioni ridondanti da altre fonti consultando il mentore o i mentori.