Cette page contient les détails d'un projet de rédaction technique accepté pour la Google Season of Docs.
Résumé du projet
- Organisation Open Source:
- ScummVM
- Rédacteur technique:
- Cadi
- Nom du projet:
- Créer un portail de documentation
- Durée du projet:
- Durée standard (3 mois)
Project description
Objectifs :
- Produire une documentation utilisateur finale de haute qualité et versionnée en consolidant de grandes quantités d'informations provenant de sources disparates et en réécrivant les informations pour plus de clarté, de cohérence et d'exhaustivité.
- La documentation doit être facile à comprendre pour les débutants, sans être condescendante envers les utilisateurs avertis.
- Créer un portail de documentation à l'aide d'un générateur de site statique
- Pour pérenniser la documentation destinée aux utilisateurs finaux en créant des modèles et des instructions détaillées pour les futurs contributeurs Open Source.
Situation actuelle:
- La documentation ScummVM disponible est répartie sur plusieurs sources.
- Les informations sont difficiles à trouver et souvent dupliquées. Il est facile de se perdre dans des pages obscures.
- Il est difficile de savoir quelles informations sont à jour et lesquelles ne le sont pas.
- Certaines informations sont manquantes ou incomplètes.
Pour 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
| |-- Le lanceur de jeu
| |-- Paramètres globaux
| |-- 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
- Mise en route :
Les nouveaux utilisateurs recherchent souvent un guide de démarrage rapide pour démarrer le plus rapidement possible. Bien que l'installation de ScummVM puisse être complexe sur certaines plates-formes, elle ne l'est pas sur un ordinateur.
Le guide de démarrage rapide doit couvrir les points suivants:
- Comment installer ScummVM sur Windows, Mac et Linux
Chargement, ajout et lancement d'un jeu
Installer ScummVM:
Si l'installation n'est pas intuitive ou si l'utilisateur ne dispose pas d'une base technique solide, l'utilisateur a besoin d'un guide complet pour installer ScummVM sur l'une des plates-formes compatibles.
Chaque page d'installation complète doit couvrir les éléments suivants:
- La configuration système requise.
- Télécharger la version appropriée de ScummVM
- Installer ScummVM
- Comment charger des jeux sur la plate-forme choisie, en particulier si ce n'est pas celle pour laquelle le jeu a été conçu.
Lancer ScummVM, ajouter et lancer un jeu
Avec ScummVM:
Les utilisateurs ont besoin de documents de référence qui expliquent comment utiliser ScummVM.
Les documents de référence doivent couvrir les éléments suivants:
- L'interface du lanceur : apparence de chaque fenêtre et onglet, ainsi que leur fonctionnement.
- Explication des paramètres disponibles, à la fois globaux et spécifiques au jeu.
Raccourcis clavier/touches de raccourci
Options avancées :
Les utilisateurs avancés ont besoin d'informations techniques supplémentaires sur les options à leur disposition pour ajuster le fonctionnement de leurs jeux.
- Remarques sur le jeu:
Toutes les informations spécifiques au jeu qu'un utilisateur doit connaître, y compris, mais sans s'y limiter : - Particularités de l'installation - Fichiers supplémentaires requis - Commandes inhabituelles ou différentes
- Problèmes connus:
Cette section doit contenir tous les bugs connus spécifiques à cette version.
- Notes de version :
Bien que notre documentation soit gérée par version, une section "Notes de version" peut être utile pour fournir un résumé des modifications apportées à la dernière version. Cela peut inclure des domaines qui ne relèvent pas actuellement du champ d'application 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 c'est le moyen le plus simple pour moi d'obtenir les informations dont j'ai besoin auprès des responsables/développeurs de ports (en particulier lorsque ces informations sont peu nombreuses ou n'existent pas). Je préremplirai toutes les informations que je possède déjà à partir de la documentation existante. Je pourrai ensuite vérifier leur exhaustivité, leur exactitude et leur actualité, ou les compléter si nécessaire.
Je vais ensuite examiner la documentation existante : le fichier README, le wiki et le site Web. Au fur et à mesure, je réécrirai et ajouterai des informations à chaque section si nécessaire, et je transfèrerai toutes les informations dans le nouveau portail. Je noterai également d'où proviennent les informations afin de m'assurer qu'une fois le portail mis en ligne, il n'y aura pas de doublons, de contradictions ni d'autres anomalies.
Tout au long de ce processus, je serai en contact avec le ou les mentors, les développeurs, les responsables de ports et tout autre expert pour obtenir les informations manquantes, et 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, je souhaite que la communauté ScummVM puisse accéder au portail en cours de développement tout au long du processus d'écriture, afin de recevoir des commentaires en temps réel et de s'assurer que rien n'est oublié.
Je vous suggère d'utiliser un guide de style, comme le guide de style de la documentation pour les développeurs Google, pour assurer la cohérence de cet ensemble de travaux et de toute la documentation à venir.
Dans la mesure du possible, j'utiliserai des captures d'écran, des GIF et d'autres aides visuelles pour améliorer la compréhension.
Calendrier proposé:
Renforcement des liens au sein de la communauté 17 août - 13 septembre 2020
Continuez à passer du temps à discuter avec votre ou vos mentors et avec la communauté ScummVM plus large pour affiner la vision du projet et finaliser des détails tels que la structure et le contenu des documents.
Semaine 1 : 14 septembre - 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 port appropriés pour en savoir plus.
Semaine 2 21 septembre – 27 septembre
- Configurez le nouveau portail de documentation.
Semaine 3 28 septembre – 4 octobre
Utilisation de ScummVM : - L'interface - Les paramètres globaux Installation de ScummVM : - Les guides d'installation spécifiques à la plate-forme, car les modèles terminés me sont renvoyés.
Semaine 4 (5-11 octobre)
Utilisation de ScummVM : - Paramètres du jeu - Raccourcis clavier Installation de ScummVM : - Guides d'installation spécifiques à la plate-forme, car les modèles terminés me sont renvoyés
Semaine 5 : du 12 au 18 octobre
Options avancées : - Cloud et LAN - Contrôle du mappage Installation de ScummVM : - Guides d'installation spécifiques à la plate-forme, car les modèles finalisés me sont renvoyés
Semaine 6 : du 19 au 25 octobre
Options avancées : - Configuration - Options de ligne de commande Installation de ScummVM : - Guides d'installation spécifiques à la plate-forme, car les modèles complétés me sont renvoyés
Semaine 7 26 octobre – 1er novembre
Options avancées : - Graphismes - Audio Installation de ScummVM : - Guides d'installation spécifiques à la plate-forme à mesure que des modèles complétés me sont renvoyés
Semaine 8 2 au 8 novembre
Aide : - Questions fréquentes - Contacts - Problèmes connus
Installation de ScummVM : - Guides d'installation spécifiques à la plate-forme, car les modèles terminés me sont renvoyés
Semaine 9 9 novembre – 15 novembre
Aide : - Signaler un bug - Notes de jeu - Notes de version
Installation de ScummVM : - Finalisez les guides de plate-forme qui ne sont pas encore terminés.
Semaine 10 16 novembre - 22 novembre
- Révision finale, relecture et finalisation de toutes les décisions liées au portail, telles que la navigation dans la barre latérale, les modifications du thème/du CSS, etc.
- Assurez-vous que tous les liens fonctionnent comme prévu.
- Vérifiez que les images/gifs s'affichent correctement.
Semaine 11 23 novembre – 30 novembre
- Finalisez les éléments en attente et lancez officiellement le portail.
- Une fois le portail lancé, supprimez les informations redondantes d'autres sources en consultation avec votre ou vos mentors.