KyMAN bf4fc47d1c #wip(ecma): Segunda fase casi hecha.

2025-09-03 15:49:40 +02:00

16 KiB

Raw Permalink Blame History

OpoQuizTiny

Cada participante debe crear su propio archivo HTML siguiendo el formato:
OpoQuizTiny.NICK_PARTICIPANTE.html
Por ejemplo: OpoQuizTiny.KyMAN.html o OpoQuizTiny.Copilot.html.

OpoQuizTiny no es más que un pequeño proyecto Free OpenSource que funcionará a modo de Jam para desarrollar en un OnePage OneFile un proyecto completo, funcional, mantenible y escalable, altamente reducido, que a parte de una serie de archivos JSON con una información la cual será usada como base informativa para crear los Quiz.

El proyecto se puede basar en más de una sesión Jam pero éstas han de cumplirse. Si quieres participar, la idea es que para representar los tiempos se haga una marca en el fichero, se Comitee y se Pushee para tener un registro de inicio, y como quede y/o se termine, se Comitee y se Pushee de nuevo para tener dicho registro de tiempos. Un ejemplo de lo dicho puede ser crear el fichero si éste no existe y ponerle el Doctype, o si ya existe, poner un comentario y guardar, luego Comitear y Pushear y empezar la Jam, y finalmente, cuando se termine, Comitear y Pushear de nuevo.

Para no pisarse los unos a los otros, quizás lo ideal sea que cada usuario esté con un Branch propio aunque al final se Mergee.

La valoración se hará en una tabla y serán una serie de puntuaciones que vayan de 0 a 10. La media decimal será la que determine la diferencia.

Finalidad de la Jam

El objetivo de esta Jam es fomentar el aprendizaje, la creatividad y la mejora continua a través de la sana competición y la colaboración. Se busca que cada participante aporte su visión y habilidades, valorando tanto la funcionalidad como la calidad del código y la experiencia de usuario.

Por otro lado, también se intentará con esto ayudar a estudiantes con Tests que puedan ser funcionales y reales cara sus actividades.

Formato y ubicación de los archivos JSON

Antes de comenzar, se definirá un formato estándar para los archivos JSON que contendrán el temario o la información base. Estos archivos se ubicarán en el directorio /Public/json dentro del proyecto para mantener la organización. Los archivos de usuario también se ubicarán en /Public.

Nota: Las preguntas del quiz no deben estar definidas estáticamente ni en los archivos JSON ni en el código. El sistema debe generar las preguntas dinámicamente a partir del temario estructurado en los archivos JSON.

Ejemplo de mensajes de commit para marcar tiempos

Inicio de Jam:
Jam 1 - Inicio: Preparación de estructura base
Fin de Jam:
Jam 1 - Fin: Versión funcional lista para valoración

Normas y estructura de la Jam Copilot vs Usuario

A continuación se detallan las normas y fases acordadas para la Jam competitiva entre Copilot y el usuario, aplicables también a cualquier Jam colaborativa basada en este sistema:

Objetivo

Desarrollar un sistema de Preguntas y Respuestas (Quiz) a partir de los temarios definidos en archivos JSON, siguiendo el estándar de este proyecto, en un único archivo HTML (OnePage OneFile) que integre todo el código (HTML, CSS, JS) sin recursos externos salvo imágenes, fuentes o iconos.

Fases del desarrollo

Creación y estructuración del fichero base:
Preparar el archivo HTML único que contendrá toda la aplicación.
Crear la base del GUI:
Diseñar la interfaz de usuario, asegurando claridad, funcionalidad y mantenibilidad.
Carga de los archivos JSON y gestión de la información:
Permitir la carga dinámica de los archivos de temario, gestionando la información según los criterios definidos en el README.
Generación del sistema de preguntas aleatorias:
Crear preguntas y respuestas de forma totalmente aleatoria a partir del temario, sin preprogramar ninguna pregunta.
Testeo:
Comprobar el correcto funcionamiento de la aplicación y la generación de preguntas.
Estilos finales:
Aplicar los estilos CSS definitivos para una buena experiencia de usuario.

Reglas y criterios técnicos

Fichero único: Todo el código debe estar en un solo archivo HTML.
Sin frameworks/librerías externas: Solo se permite el uso de JS, HTML y CSS estándar compatibles con Firefox, Chrome, Edge, etc.
Configuración previa: El usuario podrá seleccionar el número de preguntas, tipos de preguntas, número de respuestas y los archivos/contenidos JSON a usar mediante un formulario previo al cuestionario.
Tipos de preguntas soportados:
1. Verdadero o Falso (Radio button)
2. Múltiples respuestas con una opción correcta (Radio button)
3. Multiselección para seleccionar 0, 1 o más respuestas posibles (Checkbox)
Formulación de preguntas:
Las preguntas pueden ser afirmativas ("¿Qué tiene...?") o negativas ("¿Qué no tiene...?").
Aleatorización:
Las preguntas y respuestas deben generarse de forma aleatoria a partir del temario, nunca estar preprogramadas.
Compatibilidad:
El sistema debe funcionar correctamente en los principales navegadores modernos.

Organización y tiempos

Desarrollo por fases:
La Jam se divide en varias fases (ver arriba), que pueden realizarse en días distintos según la disponibilidad de los participantes.
Tiempo real:
Cada fase se realiza en tiempo real, midiendo el tiempo invertido en cada una.
Valoración:
Al finalizar cada fase, se valoran los avances según la tabla de valoración del README.
Feedback:
Tras cada fase, se pueden comentar los puntos fuertes y débiles de cada propuesta.

Valoración

Se utilizará la tabla de valoración ya definida en este README, puntuando:
Funcionalidad, Mantenibilidad, Escalabilidad, UX/UI, Creatividad y Tiempo.

Normas del proyecto

El proyecto ha de ser una Aplicación Web OnePage OneFile, es decir, pese a tener distintas vistas, éste ha de estar compacto en un único archivo y las vistas han de estar compactadas en un OnePage pese a que éstas cambien.
El archivo ha de ser un HTML para que sea ejecutable en un navegador contra un entorno de protocolo HTTP o FILE independientemente para su funcionalidad básica.
No se pueden usar recursos externos salvo elementos como imágenes, fuentes de texto o iconos, pero lo que son Scripts, CSS, HTML, etc. Ha de estar todo integrado en el mismo. Cuantos menos recursos externos mejor, siendo lo ideal 0 recursos externos.
Los Scripts han de estar estructurados, funcionales, mantenibles y escalables. Si es excesivamente complejo, excesivamente simplificado, etc. Todo restará.
Si se hace uso de SASS, éste ha de estar integrado y programado internamente dentro del fichero.
Las preguntas no pueden crearse estáticamente, es decir, han de generarse a partir del temario estructurado en los archivos JSON, y éste podría cambiar, por lo que la computación de preguntas y respuestas ha de estar programada en base a dichos contenidos JSON.

Tabla de valoración

Cada subjam que se vaya haciendo irá numerada por lo que el participante irá acompañado de un número que indica en que Subjam se encuentra.

Participante	Funcionalidad	Mantenibilidad	Escalabilidad	UX/UI	Creatividad	Tiempo (min)	Media
Ejemplo - 1	8	9	8	7	8	45 - 10	8.333
...	...	...	...	...	...	...	...

Criterios de valoración:

Funcionalidad: Cumple todos los requisitos y funciona correctamente.
Mantenibilidad: Código claro, bien estructurado y documentado.
Escalabilidad: Fácil de ampliar o modificar.
UX/UI: Experiencia y diseño de usuario.
Creatividad: Soluciones originales o innovadoras.
Tiempo: Tiempo invertido (solo informativo, no puntúa).

Comentarios

Cada subjam ha de tener los consiguientes comentarios de los que valoran dicha actividad.

Sugerencias de mejora

Añadir ejemplos de cómo marcar los tiempos de inicio y fin en los commits.
Definir un formato estándar para los archivos JSON de preguntas.
Incluir una sección de "Preguntas frecuentes" o "Consejos" para nuevos participantes.
Considerar una ronda de feedback entre participantes tras la valoración.

Estructura y sintaxis de los archivos JSON de temario

Los archivos JSON que definen el temario siguen una estructura flexible y compacta para facilitar su legibilidad y escalabilidad. A continuación se describen los campos permitidos y su sintaxis:

Campos permitidos

id (opcional):
Es un String único en snake_case (minúsculas y guiones bajos) que identifica el nodo y permite ser referenciado por otros nodos, incluso desde otros archivos.
Ejemplo:
```
"id": "articulo_1"
```
name:
Puede ser un String (nombre principal) o un Array de String (nombre y sinónimos).
Ejemplo:
```
"name": "Artículo 1"
```
o
```
"name": ["Artículo 1", "Art. 1", "Primer artículo"]
```
patterns (opcional):
Es un Array de strings con expresiones regulares o patrones de búsqueda para localizar el nodo de forma flexible.
Cada patrón debe ir encapsulado entre barras inclinadas / y puede incluir modificadores al final, como en JavaScript o SED.
Ejemplo:
```
"patterns": ["/^Art(ículo)?\\s*1$/i", "/primer\\s+art(ículo)?/i"]
```

description (opcional):
Puede ser un String (una sola línea) o un Array de String (varias líneas o párrafos).
Ejemplo:

"description": "La capital del Estado es la villa de Madrid."

"description": [
    "Primera línea de la descripción.",
    "Segunda línea o párrafo adicional."
]

legends (opcional):
Es un Diccionario, donde cada clave es una sigla y el valor su significado. Permite alternativas o sinónimos.
Ejemplo:
```
"legends": {
    "CE": "Constitución Española", 
    "TC": "Tribunal Constitucional" 
}
```
parent (opcional):
Puede ser un String (un solo padre) o un Array de String (múltiples padres), para establecer relaciones fuera del árbol principal o entre bloques.
Ejemplo:
```
"parent": "Título Preliminar"
```
o
```
"parent": ["Título Preliminar", "Bloque Adicional"]
```
parents (opcional):
Es un Array de id de otros nodos a los que este nodo hace referencia como padres externos. Los IDs deben estar en snake_case. Si alguno de los IDs no se encuentra cargado, se considerará que ese vínculo no existe y el nodo se tratará como temario independiente.
Ejemplo:
```
"parents": ["titulo_preliminar", "bloque_adicional"]
```
children (opcional):
Es un Array de nodos hijos, cada uno con la misma estructura. Solo se incluye si existen hijos.

Ejemplo de nodo completo

{
    "id": "articulo_1",
    "name": ["Artículo 1", "Art. 1"],
    "patterns": ["/^Art(ículo)?\\s*1$/i", "/primer\\s+art(ículo)?/i"],
    "description": [
        "España se constituye en un Estado social y democrático de Derecho.",
        "La soberanía nacional reside en el pueblo español."
    ],
    "legends": {
        "CE": "Constitución Española"
    },
    "parent": "Título Preliminar",
    "parents": ["bloque_general"],
    "children": [{
        "name": "Apartado 1",
        "description": "España se constituye en un Estado social y democrático de Derecho."
    }]
}

Convenciones de estilo y sintaxis para los archivos JSON

Para mantener la legibilidad y coherencia en los archivos JSON del proyecto, se seguirán estas normas de estilo:

Tabulación: 4 espacios por nivel de indentación.
Arrays de diccionarios: Los corchetes [ y las llaves { deben ir en la misma línea, sin salto de línea entre ellos.
Separación entre elementos: Las llaves y corchetes se separan por coma y espacio, sin salto de línea.
Campos opcionales: Omitir los campos vacíos.
Ejemplo de formato correcto:

[{
    "id": "articulo_1",
    "name": ["Artículo 1", "Art. 1"],
    "description": [
        "España se constituye en un Estado social y democrático de Derecho.",
        "La soberanía nacional reside en el pueblo español."
    ],
    "legends": {
        "CE": "Constitución Española", 
        "TC": "Tribunal Constitucional"
    },
    "parent": "Título Preliminar",
    "children": [{
        "name": "Apartado 1",
        "description": "España se constituye en un Estado social y democrático de Derecho."
    }]
}]

Nota: Estas convenciones son principalmente visuales y no afectan la validez del JSON, pero ayudan a mantener el proyecto ordenado y fácil de revisar.

¡Ánimo y a disfrutar aprendiendo y mejorando juntos!

Patrones de formato

"use strict"

/** @type {Array.<[RegExp, string]>} */
const patrones = [
    [/("(?:name|patterns)" *: *\[)(?:[\r\n]+|\s+)+((?:(?!(\],))(?:.|[\r\n]))+)(?:[\r\n]+|\s+)+(\],)/, "$1$2$4"]
    [/("(?:name|patterns)" *: *\[[^\r\n\]]+)[\n\r]+\s*(\]|[^\r\n]+)/, "$1 $2"], 
    [/\[("[^"]+")\]/, "$1"]
];

Propuesta de fases para la Jam (2 horas por fase)

Para facilitar la organización y el avance, se propone dividir la Jam en fases independientes, cada una con un objetivo claro y un tiempo estimado de 2 horas. Cada fase puede realizarse en días distintos según disponibilidad.

Nota: El tiempo por fase es orientativo y flexible. Dependiendo de la experiencia del participante o la complejidad de la fase, puede que alguna requiera algo menos o más tiempo. Si algún participante termina antes o necesita un poco más, puede adaptarse según el ritmo del grupo.

Fases sugeridas (versión revisada)

Fase 1: Estructura base y carga de archivos
- Crear el archivo HTML único.
- Implementar la estructura básica del documento (HTML, head, body, etc.).
- Añadir el formulario para cargar uno o varios archivos JSON de temario.
- Objetivo: Al final de la fase, debe poder cargarse y visualizarse el contenido básico de los archivos JSON seleccionados.
Fase 2: Configuración y selección de parámetros
- Implementar el formulario de configuración previa: número de preguntas, tipos de preguntas, número de respuestas, selección de contenidos/temas.
- Validar la selección y preparar la estructura interna para la generación del quiz.
- Objetivo: Al final de la fase, el usuario puede configurar el quiz y ver un resumen de la configuración seleccionada.
Fase 3: Generación y presentación de preguntas
- Programar la lógica para generar preguntas y respuestas aleatorias según la configuración y los datos cargados.
- Implementar la presentación de preguntas en la interfaz, con los tipos requeridos (Verdadero/Falso, opción única, multiselección).
- Objetivo: Al final de la fase, el usuario puede ver y responder preguntas generadas dinámicamente, pero sin corrección automática ni resultados.
Fase 4: Corrección, resultados y mejoras de UX/UI
- Implementar la corrección automática de respuestas y mostrar resultados al usuario.
- Mejorar los estilos y la experiencia de usuario.
- Objetivo: Al final de la fase, el usuario puede ver su puntuación/resultados y disfrutar de una mejor presentación visual.

Nota: Los estilos, correcciones y mejoras de experiencia de usuario se pueden ir aplicando progresivamente en cada fase según se avance en el desarrollo. Si alguna fase resulta especialmente sencilla o compleja, se puede ajustar el tiempo dedicado a la misma.

16 KiB Raw Permalink Blame History