Esta página contiene los detalles de un proyecto de redacción técnica aceptado para la GDOC Season of Docs.
Resumen del proyecto
- Organización de código abierto:
- ScummVM
- Redactor técnico:
- Cadi
- Nombre del proyecto:
- Cómo iniciar 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 de alta calidad a través de la consolidación de grandes cantidades de información de fuentes diversas y la reescritura de la información para mayor claridad, integridad y coherencia.
- La documentación debe ser fácil de entender para los principiantes, sin ser condescendiente con los usuarios expertos en tecnología.
- Para crear un portal de documentación con un generador de sitios estáticos
- Para preparar la documentación del usuario final para el futuro con instrucciones detalladas y plantillas para futuros colaboradores de código abierto.
Situación actual:
- La documentación de ScummVM disponible se encuentra en varias fuentes.
- La información es difícil de encontrar y, a menudo, se duplica; es fácil perderse en páginas desconocidas.
- Es difícil saber qué información está actualizada y qué no.
- 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)
|-- Cómo usar 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, no lo es en una computadora.
La guía de inicio rápido debe incluir lo siguiente:
- Cómo instalar ScummVM en Windows, Mac y Linux
Cómo cargar, agregar y, luego, iniciar un juego
Cómo instalar ScummVM:
En los casos en que la instalación no sea intuitiva o en los que el usuario no tenga una base técnica sólida, este necesita una guía integral para instalar ScummVM en cualquiera de las plataformas compatibles.
Cada página de instalación integral 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ñó el juego
Cómo iniciar ScummVM, agregar un juego y, luego, iniciarlo
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 de programas; cómo se ven cada ventana y pestaña, y cómo funcionan.
- Explicación de los parámetros de configuración disponibles, tanto globales como específicos del juego.
Combinaciones de teclas y 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 partido:
Cualquier información específica del juego que el usuario necesite saber, incluidos, sin limitaciones, los siguientes aspectos: - Particularidades de la instalación - Archivos adicionales necesarios - 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 se controlará la versión de nuestra documentación, tener 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 nuevos compatibles o la información sobre motores nuevos.
Plan de ataque:
Propongo comenzar por crear 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 los encargados de mantenimiento de puertos (especialmente cuando esta información es escasa o no existe). Completaré previamente la información que ya tenga de la documentación existente, que luego se podrá verificar para verificar su integridad, exactitud y vigencia, o se podrá agregar según sea necesario.
A continuación, revisaré la documentación existente: el archivo README, la wiki y el sitio web. A medida que avance, volveré a escribir y agregaré información a cada sección según sea necesario. Además, agregaré toda la información al nuevo portal. También tomaré nota de qué información se extrae de dónde para asegurarme de que, una vez que el portal esté publicado, no haya duplicados, contradicciones ni otras anomalías.
Durante el proceso, me comunicaré con los mentores, los desarrolladores, los encargados de mantener puertos y cualquier otro experto en la materia para obtener la información que falte y para garantizar que cada página esté lo más actualizada y completa posible.
Con el espíritu de colaboración y sujeto a la aprobación de los mentores, me gustaría que la comunidad de ScummVM pueda acceder al portal de trabajo en curso durante el proceso de escritura para recibir comentarios en tiempo real y asegurarse de no pasar por alto nada.
Te sugiero que uses una guía de estilo, como la guía de estilo de la documentación para desarrolladores de Google, para garantizar la coherencia de este cuerpo de trabajo y de toda la documentación en el futuro.
Siempre que sea posible, usaré capturas de pantalla, GIFs y otros elementos visuales para mejorar la comprensión.
Cronograma propuesto:
Vinculación con la comunidad Del 17 de agosto al 13 de septiembre de 2020
Continúa hablando con los mentores y la comunidad en general de ScummVM para perfeccionar la visión del proyecto y ultimar detalles como la estructura y el contenido de los documentos.
Semana 1: del 14 al 20 de septiembre
- Crea una plantilla para las páginas de instalación específicas de la plataforma.
- Completa las plantillas con la información existente y distribúyelas a los desarrolladores o encargados de mantenimiento del puerto 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
Uso de ScummVM: - La interfaz - Configuración global Instalación de ScummVM: - Me devuelven guías de instalación específicas de la plataforma como plantillas completas.
Semana 4 Del 5 al 11 de octubre
Uso de ScummVM: - Configuración del juego - Atajos de teclado Instalación de ScummVM: - Guías de instalación específicas de la plataforma, ya que me devuelven plantillas completas
Semana 5 Del 12 al 18 de octubre
Opciones avanzadas: - Nube y LAN - Asignación de controles Instalación de ScummVM: - Guías de instalación específicas de la plataforma, ya que me devuelven 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, ya que me devuelven plantillas completas
Semana 7: del 26 de octubre al 1 de noviembre
Opciones avanzadas: - Gráficos - Audio Instalación de ScummVM: - Me devuelven guías de instalación específicas de la plataforma como plantillas completadas
Semana 8: del 2 al 8 de noviembre
Ayuda: - Preguntas frecuentes - Contactos - Problemas conocidos
Instalación de ScummVM: - Guías de instalación específicas de la plataforma, ya que me devuelven plantillas completas
Semana 9 Del 9 al 15 de noviembre
Ayuda: - Informar un error - Notas del juego - Notas de la versión
Instalación de ScummVM: - Finaliza las guías de plataformas que aún no hayas completado.
Semana 10 Del 16 al 22 de noviembre
- Edición final, revisión y finalización de las decisiones relacionadas con el portal, como la navegación de la barra lateral, los ajustes de temas 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.