Progetto ScummVM

Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per la stagione dei documenti Google.

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 di alta qualità per gli utenti finali sottoposti al controllo delle versioni consolidando grandi quantità di informazioni provenienti da fonti diverse e riscrivendole per chiarezza, coerenza e completezza.
  • La documentazione deve essere facilmente comprensibile per i principianti, senza essere conciliata per gli utenti esperti di tecnologia.
  • Per creare un portale di documentazione utilizzando un generatore di siti statici.
  • Per preparare una documentazione per l'utente finale a prova di futuro, creando modelli e istruzioni dettagliate per i futuri collaboratori open source.

Situazione attuale:

  • La documentazione di ScummVM disponibile è distribuita su più origini.
  • Le informazioni sono difficili da trovare e spesso duplicate; si perde facilmente in pagine poco chiare.
  • È difficile capire quali informazioni sono aggiornate e quali non lo sono.
  • Alcune informazioni sono mancanti o 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, la sua installazione su un computer non lo è.

La guida rapida deve 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 trattare i seguenti argomenti:

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

  • Come avviare ScummVM, aggiungere e lanciare un gioco.

  • Utilizzo di ScummVM:

Gli utenti devono avere documenti di riferimento che spieghino come utilizzare ScummVM.

I documenti di riferimento devono riguardare i seguenti argomenti:

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

  • 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 sul gioco:

Qualsiasi informazione specifica sul gioco che l'utente deve conoscere, inclusi, a titolo esemplificativo: - Aspetti particolari 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 verrà sottoposta al controllo delle versioni, avere una sezione Note di rilascio può essere utile per fornire un riepilogo delle modifiche nell'ultima release. Potrebbero essere incluse alcune aree che al momento 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 sull'installazione di ScummVM, poiché sarà il modo più semplice per ottenere le informazioni di cui ho bisogno dai gestori/sviluppatori delle porte (soprattutto se queste informazioni sono scarse o non esistono). Precompilarò tutte le informazioni di cui già possiedo la documentazione esistente, che potranno poi essere verificate per verificarne la completezza, l'accuratezza e la valuta oppure, se necessario, aggiunte.

Poi esaminerò la documentazione esistente: README, wiki e sito web. Man mano che procedo, lo riscriverò e aggiungerò a ogni sezione come richiesto e inserirò tutte le informazioni nel nuovo portale. Inoltre, prenderò nota di quali informazioni vengono estratte da dove, per garantire che una volta che il portale sia attivo, non si verifichino doppioni, contraddizioni o altre anomalie.

Durante tutto il corso, collaborerò con mentori, sviluppatori, addetti alla manutenzione dei porti e qualsiasi altro esperto in materia per reperire le informazioni mancanti, nonché garantire che ogni pagina sia il più aggiornata e completa possibile.

Nello spirito della collaborazione e soggetta all'approvazione dello o dei mentori, vorrei che il portale dei lavori in corso fosse accessibile alla community di ScummVM durante l'intero processo di scrittura, per ricevere un feedback in tempo reale e assicurarsi che non manchi nulla durante il processo.

Suggerisco di utilizzare una guida di stile, come la guida di stile della documentazione per gli sviluppatori di Google, per garantire coerenza in questa serie di lavori e in tutta la documentazione in futuro.

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

Sequenza temporale proposta:

Legami comunitari 17 agosto - 13 settembre 2020

Continua a parlare con i mentori e con l'intera community di ScummVM per perfezionare la vision del progetto e finalizzare i 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 tutte le informazioni esistenti e distribuiscili agli sviluppatori/gestori delle porte appropriati per avere 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: - Vengono restituite guide all'installazione specifiche per la piattaforma quando i modelli completati.

Settimana 4 5 ottobre - 11 ottobre

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

Settimana 5 12 ottobre - 18 ottobre

Opzioni avanzate: - Cloud e LAN - Mappatura di controllo Installazione di ScummVM: - Guide di installazione specifiche per la piattaforma quando i modelli completati vengono restituiti

Settimana 6 19 ottobre - 25 ottobre

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

Settimana 7 26 ottobre - 1° novembre

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

Settimana 8 2 novembre - 8 novembre

Guida: - Domande frequenti - Contatti - Problemi noti

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

Settimana 9 9 novembre - 15 novembre

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

Installazione di ScummVM: - Finalizza le guide della 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 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 oggetti in sospeso e lancia ufficialmente il portale.
  • Una volta lanciato il portale, rimuovi le informazioni ridondanti da altre fonti consultando il tutor o i mentori.