Códigos y convenciones

Este documento describe las convenciones de nombres que usamos en los libros, en los frontmatters y en los _book.json. La idea es que el contenido sea portable y anónimo respecto a la institución de origen, sin perder el contexto cultural y geográfico que hace los ejemplos auténticos.

1. Códigos de universidades (apócrifos)

Los libros referencian universidades con siglas codificadas. Cada sigla mapea a una institución real, pero el corpus público no menciona nombres concretos. La motivación es triple:

1. Reusabilidad. Una materia común a varias carreras del país puede aprovechar el mismo libro sin convertirse en propiedad de una institución.
2. Privacidad. Profesores y alumnos pueden contribuir o validar contenido sin asociarlo a su empleador.
3. Generalidad. Si el libro vale para cualquier estudiante salvadoreño con preparación de bachillerato, mejor no atarlo a un único pénsum.

Tabla de códigos

Las siglas son literarias — no corresponden uno-a-uno a entidades reales registradas. Si tu universidad no aparece, podés mapearla a la más cercana geográficamente para los ejemplos. La materia es la misma; el campus es ambiental.

Cómo aparecen en el frontmatter

---
universidad: UNIMO
carrera: Ingenieria en Sistemas
materia: Programacion I
codigo_materia: PRO115
ciclo: 1
---

El campo universidad es uno de los códigos de la tabla anterior. Si una materia es común a varias instituciones, en el _book.json se listan todas:

"universities": [
  { "code": "UNIMO", "career": "Ingeniería en Sistemas", "courseCode": "MAT115", "cycle": 1 },
  { "code": "UNICAP", "career": "Ingeniería Civil",    "courseCode": "MAT115", "cycle": 1 }
]

2. Códigos de materia

Las materias usan el código del pénsum local. La convención común en el país es:

[ÁREA][NIVEL][SECUENCIA]

Ejemplos:

• MAT105 — Matemática I (nivel 1, primera).
• MAT115 — Cálculo Diferencial (nivel 1, segunda — la primera matemática "fuerte").
• PRO215 — Programación II (nivel 2).
• BDD315 — Bases de Datos (nivel 3).

El código es referencial. Si el pénsum de tu institución usa otro número, podés ajustar el frontmatter local sin cambiar el contenido.

3. Convenciones culturales

El proyecto está pensado para estudiantes salvadoreños, así que mantenemos referencias culturales locales:

• Moneda: dólares estadounidenses ($), porque es la moneda oficial.
• Productos cotidianos: pupusas, curtido, refrescos de tamarindo, microbús, alcaldía, mercado.
• Geografía: San Miguel, Panamericana, La Unión, San Salvador, El Salvador (país).
• IVA: 13%.
• Sistema métrico decimal en física e ingeniería.
• Idioma: español de El Salvador, tuteo en el cuerpo del libro.

Si tu lectura es desde otro país, los ejemplos siguen siendo entendibles — solo cambia el detalle ambiental.

4. Códigos de carrera

Estos códigos aparecen en las rutas de aprendizaje (capítulo aparte) para indicar a qué carrera apunta cada secuencia recomendada.

5. Niveles de dificultad

En el frontmatter cada capítulo lleva una etiqueta:

6. Estructura de archivos (resumen)

sistemas/
├── codigos.md                     # Este archivo
├── indice/                         # Índices y rutas
│   ├── indice-tematico.md
│   ├── indice-por-materia.md
│   └── rutas-aprendizaje.md
├── books/
│   ├── matematica-i/
│   ├── calculo-diferencial/
│   ├── programacion-i/
│   └── ...                         # cada uno con _book.json + capítulos
├── ciclo-01/                       # vista por ciclo (mismos archivos, agrupados)
├── ciclo-05/                       # ...
└── ...

7. Por qué dos vistas (books/ y ciclo-NN/)

• books/ es el almacén canónico. Cada libro tiene un único origen.
• ciclo-NN/ agrupa por ciclo, útil para estudiantes que cursan en orden cronológico. Los archivos pueden ser enlaces simbólicos o copias del libro maestro.

Si modificás un capítulo, hacelo en books/ y luego sincronizá ciclo-NN/. La idea es que el libro vive una vez y se "exhibe" en varios sitios.

Si hay un código que no entendés o falta, abrí un issue: este documento es vivo.