Progetto ScummVM

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:
ScummVM
Redattore tecnico:
Cadi
Nome del progetto:
Lanciare un portale di documentazione
Durata del progetto:
Durata standard (3 mesi)

Project description

Obiettivi:

  • Produrre una documentazione per l'utente finale di alta qualità e sottoposta al controllo delle versioni mediante il consolidamento di grandi quantità di informazioni provenienti da fonti diverse e la riscrittura di informazioni in modo da garantire chiarezza, coerenza e completezza.
  • La documentazione deve essere facile da capire per i principianti, senza essere paternalistica nei confronti degli utenti esperti di tecnologia.
  • Per creare un portale di documentazione utilizzando un generatore di siti statici.
  • Per garantire la compatibilità futura della documentazione per gli utenti finali creando modelli e istruzioni dettagliate per i futuri collaboratori open source.

La situazione attuale:

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

Per risolvere il problema:

Struttura della documentazione suggerita:

Pagina di destinazione |-- Iniziare | -- Quick start guide |-- Installing ScummVM | |-- Nintendo 3DS | |-- AmigaOS | |-- Android | |-- (every) | |-- (common) | |-- (supported) |-- (piattaforma) |-- Utilizzo di ScummVM | |-- Avvio | |-- Impostazioni globali | |-- Impostazioni di 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 utilizzare il più rapidamente possibile. Sebbene l'installazione di ScummVM possa essere complessa su alcune piattaforme, non lo è su un computer.

La guida rapida deve includere quanto segue:

  • 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 non abbia una solida base tecnica, l'utente ha bisogno di una guida completa per installare ScummVM su una delle piattaforme supportate.

Ogni pagina di installazione completa deve includere quanto segue:

  • Eventuali requisiti/prerequisiti di sistema.
  • Come scaricare la versione appropriata di ScummVM.
  • Come installare ScummVM.
  • Come caricare i giochi sulla piattaforma scelta, in particolare se non è quella per cui sono stati progettati.

  • Come avviare ScummVM, aggiungere e avviare un gioco.

  • Utilizzo di ScummVM:

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

I documenti di riferimento devono trattare i seguenti argomenti:

  • L'interfaccia di Avvio: l'aspetto di ogni finestra e scheda, nonché il loro funzionamento.
  • Una spiegazione delle impostazioni disponibili, sia globali che specifiche per il gioco.

  • Scorciatoie da tastiera/tasti di scelta rapida.

  • Opzioni avanzate:

Gli utenti avanzati hanno bisogno di informazioni aggiuntive e più tecniche sulle opzioni a loro disposizione per modificare il funzionamento dei giochi.

  • Note sulla partita:

Eventuali informazioni specifiche del gioco che un utente deve conoscere, inclusi, a titolo esemplificativo: - Aspetti insoliti 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 sarà sottoposta al controllo delle versioni, potrebbe essere utile avere una sezione per le note di rilascio per fornire un riepilogo delle modifiche apportate nell'ultima release. Potrebbero essere incluse alcune aree che al momento non rientrano nell'ambito di questa documentazione, ad esempio i giochi di nuova introduzione o le informazioni sui nuovi motori.

Piano di attacco:

Propongo di iniziare creando un modello per le pagine Installazione di ScummVM, che sarà il modo più semplice per me di ottenere le informazioni di cui ho bisogno dai gestori/sviluppatori delle porte (soprattutto se queste informazioni sono scarse o inesistenti). Precompilerò tutte le informazioni che ho già dalla documentazione esistente, che possono poi essere controllate per verificarne la completezza, l'accuratezza e l'aggiornamento oppure essere integrate, se necessario.

Successivamente, esaminerò la documentazione esistente: README, wiki e sito web. Man mano che procedo, riscriverò e aggiungerò informazioni a ogni sezione in base alle esigenze e trasferirò tutte le informazioni nel nuovo portale. Prenderò anche nota di quali informazioni vengono estratte da dove, per assicurarmi che, una volta pubblicato il portale, non ci siano duplicati, contraddizioni o altre anomalie.

Durante tutto il processo, manterrò i contatti con i mentor, gli sviluppatori, i manutentori delle porte e qualsiasi altro esperto in materia per reperire le informazioni mancanti, nonché per garantire che ogni pagina sia il più aggiornata e completa possibile.

Nello spirito di collaborazione e soggetta all'approvazione dei mentori, vorrei che il portale sui lavori in corso sia accessibile alla community di ScummVM durante tutto il processo di scrittura, per ricevere feedback in tempo reale e assicurarmi che non perda nulla durante il processo.

Ti consiglio di utilizzare una guida di stile, come la guida di stile della documentazione per gli sviluppatori Google, per garantire la coerenza di questo corpus di lavoro e di tutta la documentazione futura.

Ove possibile, utilizzerò screenshot, GIF e altri ausili visivi per facilitare la comprensione.

Tempistiche proposte:

Legame con la comunità 17 agosto - 13 settembre 2020

Continua a dedicare del tempo a parlare con i mentor e con la community più ampia di ScummVM per perfezionare la visione del progetto e finalizzare dettagli come la struttura e i contenuti del documento.

Settimana 1 14 settembre - 20 settembre

  • Crea un modello per le pagine di installazione specifiche della piattaforma.
  • Precompila i modelli con le informazioni esistenti e distribuiscili agli sviluppatori/maintainer delle porte appropriati per ulteriori informazioni.

Settimana 2 21 settembre - 27 settembre

  • Configura il nuovo portale della documentazione.

Settimana 3 28 settembre - 4 ottobre

Utilizzo di ScummVM: - L'interfaccia - Impostazioni globali Installazione di ScummVM: - Guide all'installazione specifiche della piattaforma come modelli completati che mi vengono restituiti.

Settimana 4 5-11 ottobre

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

Settimana 5 12 ottobre - 18 ottobre

Opzioni avanzate: - Cloud e LAN - Mappatura del controllo Installazione di ScummVM: - Guide di installazione specifiche della piattaforma quando mi 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 della piattaforma, che mi vengono restituite come modelli completati

Settimana 7 26 ottobre - 1° novembre

Opzioni avanzate: - Grafica - Audio Installazione di ScummVM: - Guide all'installazione specifiche della piattaforma quando mi vengono restituiti i modelli completati

Settimana 8 2 - 8 novembre

Guida: - Domande frequenti - Contatti - Problemi noti

Installazione di ScummVM: - Guide all'installazione specifiche della piattaforma, che mi vengono restituite come modelli completati

Settimana 9 9 - 15 novembre

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

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

Settimana 10 16 - 22 novembre

  • Modifica finale, correzione bozza e finalizzazione di qualsiasi decisione relativa al portale, come la navigazione nella barra laterale, le modifiche al tema/CSS e così via.
  • Assicurati che tutti i link funzionino come previsto.
  • Controlla che le immagini/le GIF vengano visualizzate correttamente.

Settimana 11 23 - 30 novembre

  • Completa gli elementi in sospeso e lancia ufficialmente il portale.
  • Una volta lanciato il portale, rimuovi le informazioni ridondanti da altre fonti in collaborazione con i mentor.