Projet ScummVM

Cette page contient les détails d'un projet de rédaction technique accepté pour Google Season of Docs.

Résumé du projet

Organisation Open Source:

ScummVM

Rédacteur technique:

Cadi

Nom du projet:

Lancer un portail de documentation

Durée du projet:

Durée standard (3 mois)

Project description

Objectifs :

• Rédiger une documentation de haute qualité pour les utilisateurs finaux, avec versions gérées, en consolidant de grandes quantités d'informations provenant de sources disparates et en réécrivant les informations dans un souci de clarté, de cohérence et d'exhaustivité.
• La documentation doit être facile à comprendre pour les débutants, sans être adaptée aux utilisateurs férus de technologie.
• Créer un portail de documentation à l'aide d'un générateur de site statique
• Pérenniser la documentation de l'utilisateur final en créant des modèles et des instructions détaillées pour les futurs contributeurs Open Source

La situation actuelle:

• La documentation disponible sur ScummVM est répartie sur plusieurs sources.
• Les informations sont difficiles à trouver et souvent dupliquées ; il est facile de se perdre dans des pages peu claires.
• Il est difficile de savoir quelles informations sont à jour et lesquelles sont obsolètes.
• Certaines informations sont manquantes ou incomplètes.

Résoudre le problème:

Structure de documentation suggérée:

Page de destination |-- Premiers pas | -- Quick start guide |-- Installing ScummVM | |-- Nintendo 3DS | |-- AmigaOS | |-- Android | |-- (every) | |-- (common) | |-- (supported) |-- (plate-forme) |-- Utiliser ScummVM | |-- Lanceur d'applications | |-- Paramètres généraux | |-- Paramètres du jeu | -- Keyboard shortcuts |-- Advanced options | |-- Cloud and LAN | |-- Control Mapping | |-- Configuration | |-- Command line options | |-- Graphics |-- Musique et son |-- Aide | |-- Questions fréquentes | |-- Contacts | |-- Problèmes connus | -- Reporting a bug |-- Game Notes-- Notes de version

• Premiers pas :

Les nouveaux utilisateurs recherchent souvent un guide de démarrage rapide afin d'être opérationnel le plus rapidement possible. Si l'installation de ScummVM peut être complexe sur certaines plates-formes, son installation sur un ordinateur ne l'est pas.

Ce guide de démarrage rapide couvre les sujets suivants:

• Installer ScummVM sur Windows, Mac et Linux

• Charger, ajouter et lancer un jeu.

• Installer ScummVM:

Si l'installation n'est pas intuitive ou si l'utilisateur ne dispose peut-être pas d'une base technique solide, il a besoin d'un guide complet pour installer ScummVM sur l'une des plates-formes compatibles.

Chaque page d'installation complète doit inclure les éléments suivants:

• Toute configuration système ou prérequis
• Télécharger la version appropriée de ScummVM
• Installer ScummVM
• Comment charger des jeux sur la plate-forme choisie, en particulier lorsqu'il ne s'agit pas de la plate-forme pour laquelle le jeu a été conçu

• Lancer ScummVM, ajouter et lancer un jeu

• Utiliser ScummVM:

Les utilisateurs ont besoin de documents de référence qui expliquent comment utiliser ScummVM.

Les documents de référence doivent traiter des éléments suivants:

• Interface du lanceur d'applications : à quoi ressemblent chaque fenêtre et chaque onglet, ainsi que leur fonctionnement.
• Explication des paramètres disponibles, globaux et spécifiques au jeu.

• Raccourcis clavier.

• Options avancées :

Les utilisateurs avancés ont besoin d'informations supplémentaires et plus techniques sur les options à leur disposition pour modifier le fonctionnement de leurs jeux.

• Notes sur le jeu:

Toute information spécifique au jeu que l'utilisateur doit connaître, y compris, mais sans s'y limiter : - Caractéristiques de l'installation - Tout fichier supplémentaire requis - Commandes inhabituelles ou différentes

• Problèmes connus:

Cette section doit contenir tous les bugs connus spécifiques à la version.

• Notes de version :

Bien que notre documentation soit gérée par versions, la section "Notes de version" peut s'avérer utile pour fournir un résumé des modifications apportées à la dernière version. Il peut s'agir de domaines qui n'entrent pas dans le cadre de cette documentation, comme les nouveaux jeux compatibles ou les informations sur les nouveaux moteurs.

Plan d'attaque:

Je propose de commencer par créer un modèle pour les pages d'installation de ScummVM, car ce sera le moyen le plus simple pour moi d'obtenir les informations dont j'ai besoin auprès des responsables/développeurs de port (en particulier lorsque ces informations sont rares ou inexistantes). Je vais préremplir toutes les informations dont je dispose déjà à partir de documents existants, qui pourront ensuite être vérifiées pour vérifier leur exhaustivité, leur exactitude et leur devise, ou qui peuvent être ajoutées si nécessaire.

Ensuite, je vais parcourir la documentation existante : le fichier README, le wiki et le site Web. Au fur et à mesure, je réécrireai les sections et je les ajouterai si nécessaire, puis j'ajouterai toutes les informations dans le nouveau portail. Je vais également prendre note des informations qui sont extraites d'où, pour m'assurer qu'une fois que le portail sera en ligne, il n'y aura pas de doubles, de contradictions ou d'autres anomalies.

Tout au long de ce processus, je travaillerai avec le ou les mentors, les développeurs, les responsables des ports et tout autre expert en la matière afin de rechercher les informations manquantes, et de m'assurer que chaque page est aussi à jour et complète que possible.

Dans un esprit de collaboration et sous réserve de l'approbation du ou des mentors, j'aimerais que le portail de travail en cours soit accessible à la communauté ScummVM tout au long du processus de rédaction, afin de recevoir des commentaires en temps réel et de m'assurer que rien n'est oublié.

Je vous conseille d'utiliser un guide de style, tel que le guide de style de la documentation pour les développeurs Google, afin d'assurer la cohérence de cet ensemble de travaux et de toute la documentation à l'avenir.

Dans la mesure du possible, j'utiliserai des captures d'écran, des GIF et d'autres supports visuels pour améliorer la compréhension.

Calendrier proposé:

Associations à des communautés Du 17 août au 13 septembre 2020

Continuez à discuter avec le ou les mentors et l'ensemble de la communauté ScummVM pour affiner la vision du projet et finaliser les détails tels que la structure et le contenu du document.

Semaine 1 Du 14 septembre au 20 septembre

• Créez un modèle pour les pages d'installation spécifiques à la plate-forme.
• Pré-remplissez les modèles avec les informations existantes et distribuez-les aux responsables/développeurs de ports appropriés pour en savoir plus.

Semaine 2 Du 21 septembre au 27 septembre

• Configurez le nouveau portail de documentation.

Semaine 3 28 septembre – 4 octobre

Utiliser ScummVM : - L'interface - Paramètres généraux Installation de ScummVM : - Des guides d'installation spécifiques à la plate-forme, car les modèles terminés me sont renvoyés.

Semaine 4 Du 5 au 11 octobre

Avec ScummVM : - Paramètres du jeu - Raccourcis clavier Installation de ScummVM : - Guides d'installation spécifiques à la plate-forme lorsque les modèles terminés me sont renvoyés

Semaine 5 Du 12 octobre au 18 octobre

Options avancées : - Cloud et LAN - Mappage des contrôles Installation de ScummVM : - Guides d'installation spécifiques à la plate-forme, car les modèles terminés me sont renvoyés

Semaine 6 Du 19 octobre au 25 octobre

Options avancées : - Configuration - Options de ligne de commande Installation de ScummVM : - Guides d'installation spécifiques à la plate-forme lorsque les modèles terminés me sont renvoyés

Semaine 7 Du 26 octobre au 1er novembre

Options avancées : - Graphiques - Audio Installation de ScummVM : - Guides d'installation spécifiques à la plate-forme, car les modèles terminés me sont renvoyés

Semaine 8 Du 2 novembre au 8 novembre

Aide : - Questions fréquentes - Contacts - Problèmes connus

Installation de ScummVM : - Des guides d'installation spécifiques à la plate-forme, car les modèles terminés me sont renvoyés

Semaine 9 Du 9 novembre au 15 novembre

Aide : - Signaler un bug - Notes de jeu - Notes de version

Installation de ScummVM : - Finalisez tous les guides de plate-forme pas encore terminés.

Semaine 10 Du 16 novembre au 22 novembre

• Modification, relecture et finalisation de toute décision liée au portail, telle que la navigation dans la barre latérale, les ajustements de thème/CSS, etc.
• Assurez-vous que tous les liens fonctionnent comme prévu.
• Vérifiez que les images/GIF s'affichent correctement.

Semaine 11 Du 23 novembre au 30 novembre

• Finalisez tous les objets en attente et lancez officiellement le portail !
• Une fois le portail lancé, supprimez les informations redondantes d’autres sources en consultation avec le ou les mentors.