Esta página contiene los detalles de un proyecto de redacción técnica aceptado para la temporada de Documentos de Google.
Resumen del proyecto
- Organización de código abierto:
- ScummVM
- Escritor técnico:
- Cadi
- Nombre del proyecto:
- Abre un portal de documentación
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
Objetivos:
- Para producir documentación de usuario final con control de versiones y de alta calidad mediante la consolidación de grandes cantidades de información de distintas fuentes y la reescritura de la información para mayor claridad, coherencia y exhaustividad.
- La documentación debe ser fácil de entender para los principiantes, sin frecuentar a los usuarios expertos en tecnología.
- Crear un portal de documentación con un generador de sitios estáticos
- Preparar la documentación para el usuario final en el futuro mediante la creación de plantillas e instrucciones detalladas para los futuros colaboradores de código abierto.
Situación actual:
- La documentación de ScummVM disponible se extiende a través de múltiples fuentes.
- La información es difícil de encontrar y, a menudo, se duplica; es fácil perderse en páginas oscuras.
- Es difícil saber qué información está actualizada y qué está desactualizada.
- Falta información o está incompleta.
Cómo solucionar el problema:
Estructura de documentación sugerida:
Página de destino
|-- Primeros pasos
| -- Quick start guide
|-- Installing ScummVM
| |-- Nintendo 3DS
| |-- AmigaOS
| |-- Android
| |-- (every)
| |-- (common)
| |-- (supported)
|-- (plataforma)
|-- Usando ScummVM
| |-- El Selector
| |-- Configuración global
| |-- Configuración del juego
| -- Keyboard shortcuts
|-- Advanced options
| |-- Cloud and LAN
| |-- Control Mapping
| |-- Configuration
| |-- Command line options
| |-- Graphics
|-- Música y sonido
|-- Ayuda
| |-- Preguntas frecuentes
| |-- Contactos
| |-- Problemas conocidos
| -- Reporting a bug
|-- Game Notes-- Notas de la versión
- Primeros pasos:
Los usuarios nuevos suelen buscar una guía de inicio rápido para comenzar lo más rápido posible. Si bien la instalación de ScummVM puede ser compleja en algunas plataformas, la instalación en una computadora no lo es.
La guía de inicio rápido debe abarcar lo siguiente:
- Cómo instalar ScummVM en Windows, Mac y Linux
Cómo cargar, agregar e iniciar un juego
Instalación de ScummVM:
En los casos en que la instalación no sea intuitiva, o cuando el usuario no tenga una base técnica sólida, el usuario necesita una guía completa para la instalación de ScummVM en cualquiera de las plataformas compatibles.
Cada página de instalación completa debe abarcar lo siguiente:
- Cualquier requisito o requisito previo del sistema
- Cómo descargar la versión adecuada de ScummVM
- Cómo instalar ScummVM
- Cómo cargar juegos en la plataforma elegida, especialmente cuando no es la plataforma para la que se diseñó el juego
Cómo iniciar ScummVM, agregar un juego o iniciar uno
Con ScummVM:
Los usuarios necesitan documentos de referencia que expliquen cómo usar ScummVM.
Los documentos de referencia deben abarcar lo siguiente:
- La interfaz del Launcher; el aspecto de cada ventana y pestaña, y su funcionamiento
- Una explicación de las opciones de configuración disponibles, tanto globales como específicas del juego.
Combinaciones de teclas/teclas de acceso rápido
Opciones avanzadas:
Los usuarios avanzados necesitan información adicional y más técnica sobre las opciones disponibles para modificar la forma en que se ejecutan sus juegos.
- Notas del juego:
Toda la información específica del juego que el usuario necesite saber, incluida, sin limitaciones, la siguiente: - las peculiaridades de la instalación - los archivos adicionales requeridos - controles inusuales o diferentes
- Problemas conocidos:
Esta sección debe contener los errores conocidos específicos de la versión.
- Notas de la versión
Si bien nuestra documentación tendrá versiones, puede ser útil tener una sección de notas de la versión para proporcionar un resumen de los cambios en la versión más reciente. Esto puede incluir algunas áreas que actualmente están fuera del alcance de esta documentación, como los juegos recientemente compatibles o la información sobre motores nuevos.
Plan de ataque:
Te propongo comenzar creando una plantilla para las páginas de instalación de ScummVM, ya que esa será la forma más fácil de obtener la información que solicito a los encargados de mantenimiento o desarrolladores de puertos (especialmente si esta información es escasa o no existe). Completaré previamente toda la información que ya tengo de la documentación existente, con la que se puede verificar su integridad, precisión y moneda, o agregarse a ella según sea necesario.
A continuación, analizaré la documentación existente: README, wiki y sitio web. A medida que avance, volveré a escribir y agregaré contenido a cada sección según sea necesario y, luego, incorporaré toda la información al portal nuevo. También tomaré nota de qué información se extrae de dónde, para garantizar que una vez que esté activo el portal no haya duplicaciones, contradicciones ni otras anomalías.
Mientras tanto, trabajaré con los mentores, desarrolladores, encargados del mantenimiento de puertos y cualquier otro experto en la materia para obtener la información faltante. Además, me aseguraré de que cada página esté lo más actualizada y completa posible.
Con el fin de colaborar y con la aprobación de los mentores, me gustaría que la comunidad de ScummVM acceda al portal de trabajo en curso durante todo el proceso de redacción para recibir comentarios en tiempo real y garantizar que no se pierda nada durante el proceso.
Sugerimos utilizar una guía de estilo, como la de la documentación para desarrolladores de Google, a fin de garantizar la coherencia en este trabajo y en toda la documentación en el futuro.
Siempre que sea posible, usaré capturas de pantalla, GIFs y otros recursos visuales para mejorar la comprensión.
Cronograma propuesto:
Vinculación con la comunidad Del 17 de agosto al 13 de septiembre de 2020
Sigue dedicando tiempo a hablar con los mentores y la comunidad ScummVM en general para afinar la visión del proyecto y ultimar detalles como la estructura del documento y el contenido.
Semana 1 Del 14 al 20 de septiembre
- Crea una plantilla para las páginas de instalación específicas de la plataforma.
- Completa previamente las plantillas con cualquier información existente y distribúyela a los encargados de mantenimiento o desarrolladores de puertos correspondientes para obtener más información.
Semana 2 Del 21 al 27 de septiembre
- Configura el nuevo portal de documentación.
Semana 3 Del 28 de septiembre al 4 de octubre
Con ScummVM: - La interfaz - Configuración global Instalación de ScummVM: - Se muestran las guías de instalación específicas de la plataforma a medida que se completan las plantillas.
Semana 4 Del 5 al 11 de octubre
Con ScummVM: - Configuración de juegos - Combinaciones de teclas Instalación de ScummVM: - Guías de instalación específicas de la plataforma a medida que se devuelven las plantillas completadas
Semana 5 Del 12 al 18 de octubre
Opciones avanzadas: - Nube y LAN - Asignación de control Instalación de ScummVM: - Guías de instalación específicas de la plataforma a medida que se devuelven las plantillas completas
Semana 6 Del 19 al 25 de octubre
Opciones avanzadas: - Configuración - Opciones de línea de comandos Instalación de ScummVM: - Guías de instalación específicas de la plataforma como plantillas completadas
Semana 7 Del 26 de octubre al 1 de noviembre
Opciones avanzadas: - Gráficos - Audio Instalación de ScummVM: - Guías de instalación específicas de la plataforma a medida que se devuelven las plantillas completas
Semana 8 Del 2 de noviembre al 8 de noviembre
Ayuda: - Preguntas frecuentes - Contactos - Problemas conocidos
Instalación de ScummVM: - Guías de instalación específicas de la plataforma; se me devuelven las plantillas completas
Semana 9 Del 9 al 15 de noviembre
Ayuda: - Cómo informar un error - Notas del juego - Notas de la versión
Instalación de ScummVM: - Finaliza las guías de plataforma que aún no hayas completado.
Semana 10 Del 16 al 22 de noviembre
- Edición final, revisión y finalización de cualquier decisión relacionada con el portal, como la navegación en la barra lateral, los ajustes de tema o CSS, etcétera
- Asegúrate de que todos los vínculos funcionen como se espera.
- Verifica que las imágenes o los GIF se muestren correctamente.
Semana 11 Del 23 al 30 de noviembre
- Finaliza los elementos pendientes y lanza oficialmente el portal.
- Una vez que se lance el portal, quita la información redundante de otras fuentes en consulta con los mentores.