Esta página contiene los detalles de un proyecto de redacción técnico aceptado para Google Season of Docs.
Resumen del proyecto
- Organización de código abierto:
- ScummVM
- Redactor técnico:
- Cadi
- Nombre del proyecto:
- Inicia un portal de documentación
- Duración del proyecto:
- Duración estándar (3 meses)
Project description
Objetivos:
- Para producir documentación de usuarios finales 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 que sea clara, completa y coherente.
- La documentación debe ser fácil de entender para los principiantes, sin frecuentar a los usuarios expertos en tecnología.
- Para crear un portal de documentación con un generador de sitios estáticos
- Preparar la documentación para los usuarios finales en el futuro mediante la creación de plantillas y las instrucciones detalladas para los futuros colaboradores de código abierto.
La situación actual:
- La documentación de ScummVM disponible se distribuye en 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 es actual y qué está desactualizada.
- Falta parte de la 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, instalarla en una computadora no lo es.
En la guía de inicio rápido, se deben cubrir los siguientes temas:
- Cómo instalar ScummVM en Windows, Mac y Linux
Cómo cargar, agregar e iniciar un juego
Instala ScummVM:
En los casos en que la instalación no sea intuitiva o cuando el usuario no tenga una base técnica sólida, necesitará una guía completa para instalar ScummVM en cualquiera de las plataformas compatibles.
Cada página de instalación completa debe incluir 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ñó
Cómo iniciar ScummVM, agregar un juego o iniciar uno
Usa ScummVM:
Los usuarios necesitan documentos de referencia que expliquen cómo usar ScummVM.
Los documentos de referencia deben abarcar lo siguiente:
- La interfaz del Selector; 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 o 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 deba conocer, incluida, sin limitaciones, la siguiente: - Las peculiaridades de la instalación - Cualquier archivo adicional requerido - 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á control de versiones, contar con una sección de notas de la versión puede ser útil 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 compatibles recientemente o la información sobre motores nuevos.
Plan de ataque:
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 necesito de los desarrolladores o encargados de mantener los 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, que luego se puede agregar para verificar su integridad, precisión y vigencia, o que se pueda agregar según sea necesario.
A continuación, examinaré la documentación existente: README, wiki y sitio web. A medida que avance, volveré a escribir y agregaré a cada sección según sea necesario y extraeré toda la información al nuevo portal. También tomaré nota de qué información se extrae de dónde, para garantizar que una vez que el portal esté activo no haya duplicados, contradicciones ni otras anomalías.
Durante el proceso, trabajaré con mentores, desarrolladores, encargados de mantenimiento de puertos y cualquier otro experto en la materia para obtener la información que falte. Además, me aseguraré de que cada página esté lo más actualizada y completa posible.
Con el fin de colaborar y estar sujeto a la aprobación de los mentores, me gustaría que la comunidad de ScummVM tenga acceso 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 en 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 para este trabajo y 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:
Vínculos con la comunidad Del 17 de agosto al 13 de septiembre de 2020
Sigue pasando tiempo hablando con los mentores y la comunidad ScummVM en general para perfeccionar 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 desarrolladores o encargados de mantenimiento de puertos adecuados 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
Usa ScummVM: - La interfaz - Configuración global Instala ScummVM: - Se me devuelven 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
Uso de ScummVM: - Configuración del juego - Combinaciones de teclas Instalación de ScummVM: - Se me devuelven las guías de instalación específicas de la plataforma a medida que se completan las plantillas
Semana 5 Del 12 al 18 de octubre
Opciones avanzadas: - Nube y LAN - Control de asignación Instala ScummVM: - Recibe guías de instalación específicas para cada plataforma a medida que se reciben las plantillas completadas
Semana 6 Del 19 al 25 de octubre
Opciones avanzadas: - Configuración - Opciones de línea de comandos Instalación de ScummVM: - Se muestran guías de instalación específicas de la plataforma a medida que se completan las plantillas
Semana 7 Del 26 de octubre al 1 de noviembre
Opciones avanzadas: - Gráficos - Audio Instalación de ScummVM: - Se me muestran guías de instalación específicas para cada plataforma a medida que se completan las plantillas
Semana 8 Del 2 al 8 de noviembre
Ayuda: - Preguntas frecuentes - Contactos - Problemas conocidos
Instalación de ScummVM: - Me devuelven las guías de instalación específicas de la plataforma a medida que se completan las plantillas.
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 la plataforma que aún no se hayan completado.
Semana 10 Del 16 al 22 de noviembre
- Edición final, revisión de texto 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 GIFs se muestren correctamente.
Semana 11 Del 23 al 30 de noviembre
- Finaliza los elementos pendientes y lanza el portal oficialmente.
- Una vez que se lance el portal, quita la información redundante de otras fuentes en consulta con los mentores.