Cómo documentar una lengua construida: manual, corpus y versiones

Una lengua construida puede comenzar en un cuaderno, pero deja de ser manejable cuando las definiciones, reglas y ejemplos se reparten entre archivos sin una fuente común. Si el diccionario afirma una cosa, la gramática otra y el traductor utiliza una tercera versión, el usuario encuentra contradicciones aunque cada página parezca correcta por separado.

Esta guía explica cómo documentar una lengua construida mediante un manual, un léxico estructurado, un corpus de ejemplos y un sistema de versiones. El objetivo es que Avuneki pueda crecer sin perder coherencia, y que cada cambio se refleje en la web, el teclado y el traductor.

Documentar es diseñar

La documentación no es una tarea final. Al intentar explicar una regla aparecen huecos, excepciones y ambigüedades que permanecían invisibles en la intuición del creador.

Escribir obliga a decidir. Una lengua se vuelve compartible cuando otra persona puede aplicar sus reglas sin depender de conversaciones privadas con el autor.

Una fuente única de verdad

Todos los productos deben partir de datos maestros comunes. El diccionario, el manual, el teclado y el traductor no deberían mantener copias independientes de la misma definición.

Una corrección en la raíz de memoria debe propagarse a ejemplos, búsquedas y traducción. La fuente única reduce contradicciones y facilita comprobar qué está publicado.

Separar datos y presentación

La definición de una raíz no debe quedar atrapada dentro del diseño de una tarjeta web. Conviene almacenarla como datos estructurados y mostrarla después en distintos formatos.

La misma entrada puede alimentar una página, una ficha imprimible, el teclado o una respuesta del traductor. El contenido se mantiene; cambia su presentación.

El inventario de unidades

El inventario reúne raíces, operadores, conectores, marcas de orientación y signos auxiliares. Cada unidad recibe un identificador permanente y una categoría.

También registra estado: propuesta, experimental, estable, desaconsejada u obsoleta. Así el sistema distingue lo normativo de las ideas todavía en evaluación.

La ficha léxica completa

Una ficha debe incluir grafismo, transliteración, pronunciación, definición nuclear, extensiones, contrastes, restricciones, ejemplos y fecha de revisión.

Las equivalencias españolas se organizan por sentidos. Una lista plana de sinónimos oculta cuándo cada traducción es válida.

Definición nuclear y extensiones

La definición nuclear expresa la operación común a todos los usos. Las extensiones describen aplicaciones físicas, emocionales, temporales o metafóricas.

Separarlas impide que una raíz termine significando cualquier cosa. También permite al traductor seleccionar una palabra natural sin borrar la unidad conceptual.

Contrastes obligatorios

Cada entrada debería compararse con las raíces más próximas. La documentación responde no solo «qué significa», sino «por qué no es la otra».

Los contrastes son especialmente importantes en Avuneki para presencia y ausencia, potencial y apertura, interioridad y contención, memoria y permanencia.

Registrar restricciones

Una unidad puede no admitir determinadas posiciones, combinaciones u orientaciones. Estas restricciones forman parte de su definición operativa.

El teclado puede utilizarlas para prevenir construcciones inválidas y el traductor para explicar por qué una propuesta no se analiza.

El manual de gramática

El manual explica cómo se combinan las unidades: núcleo, modificador, relación, dirección, contención, alcance, negación, tiempo, aspecto y color.

Debe avanzar desde construcciones mínimas hasta casos complejos. Cada regla necesita ejemplos positivos, pares contrastados y al menos un error comentado.

Reglas con identificador

Asignar un código a cada regla permite citarla desde el diccionario, los ejercicios y los mensajes de error. «GR-REL-03» es más preciso que «como se explicó antes».

El identificador permanece aunque cambie el texto explicativo. Las revisiones pueden indicar qué versión modificó su alcance.

Ejemplos positivos y negativos

Un ejemplo válido muestra el funcionamiento. Un ejemplo inválido revela el límite y explica qué debería cambiar.

Documentar únicamente formas correctas obliga al estudiante a adivinar por qué su composición falla. Los errores comentados convierten la guía en una herramienta práctica.

El corpus de Avuneki

El corpus reúne expresiones reales o diseñadas para representar distintos fenómenos. Cada ejemplo conserva grafismos, transliteración, glosa, traducción natural y análisis.

No es una colección decorativa. Sirve para comprobar reglas, entrenar búsquedas, evaluar el traductor y observar qué construcciones se utilizan de verdad.

Equilibrar el corpus

Un corpus lleno de expresiones sobre memoria no demuestra que el idioma cubra relaciones, materia, tiempo o acción. Conviene medir familias y estructuras representadas.

También debe incluir formas simples, complejas, ambiguas, negativas y cromáticas. La variedad evita optimizar el sistema para unos pocos ejemplos favoritos.

Anotar cada ejemplo

La anotación separa núcleo, modificadores, participantes, operadores y alcance. También registra la fuente y el estado de revisión.

Estas etiquetas permiten filtrar el corpus y construir pruebas automáticas. Si cambia una regla, se localizan los ejemplos afectados.

Traducción literal y natural

La glosa literal muestra la arquitectura de Avuneki. La traducción natural comunica el sentido en español sin imitar necesariamente el orden.

Guardar ambas evita tratar una paráfrasis como análisis exacto. El usuario puede entender el resultado y verificar sus componentes.

Documentar la ambigüedad

Cuando una forma admite más de una lectura, el corpus registra todas y explica qué contexto favorece cada una. No conviene ocultar la ambigüedad.

También se indica si es deliberada, tolerada o producida por una regla incompleta. Esta clasificación guía futuras revisiones.

El sistema de versiones

Cada publicación recibe un número de versión. Los cambios importantes en grafismos, definiciones o gramática requieren una revisión identificable.

La versión permite reconstruir por qué una traducción antigua difiere de la actual. Sin ella, todo cambio parece un error imprevisible.

Cambios mayores, menores y correcciones

Una versión mayor rompe compatibilidad: redefine una raíz o cambia una estructura. Una versión menor añade unidades o reglas compatibles. Una corrección resuelve erratas sin alterar el análisis.

Esta distinción ayuda a decidir qué materiales deben regenerarse y qué usuarios necesitan aviso.

El registro de cambios

El registro resume qué se añadió, modificó, desaconsejó o retiró. Debe mencionar identificadores afectados y consecuencias prácticas.

«Mejoras generales» no es suficiente. Una nota útil explica que una raíz cambió de grafismo para evitar colisión y señala su sustitución.

Migraciones y compatibilidad

Cuando cambia un grafismo, los textos existentes no deberían quedar ilegibles. Una tabla de migración relaciona forma anterior, identificador y representación nueva.

El traductor puede reconocer versiones antiguas y advertir al usuario. El teclado solo debería insertar la versión vigente.

Estados de estabilidad

No toda propuesta merece incorporarse inmediatamente. Marcar experimental permite probarla en el corpus sin presentarla como norma.

Una unidad estable ha superado contraste visual, definición, composición y traducción. Una unidad obsoleta se conserva para interpretar documentos históricos.

Flujo de aprobación

Una propuesta incluye necesidad, definición, forma, contrastes y ejemplos. Después pasa por revisión lingüística, visual y técnica.

Solo al aprobarse se publica en diccionario, manual, teclado y traductor. Este flujo evita actualizaciones parciales.

Pruebas vinculadas a reglas

Cada regla importante necesita casos que deban funcionar y casos que deban fallar. Las pruebas se ejecutan cuando cambia el léxico o la gramática.

Si una revisión rompe un ejemplo estable, el sistema obliga a decidir si la regla o el ejemplo deben cambiar. La contradicción deja de pasar inadvertida.

Validación automática de datos

El inventario puede detectar identificadores duplicados, grafismos ausentes, traducciones vacías, referencias rotas y ejemplos sin análisis.

También comprueba que todas las unidades estables estén disponibles en teclado y diccionario. Automatizar estas revisiones libera tiempo para decisiones lingüísticas.

Publicación en la web

La web debería generar sus secciones desde la fuente maestra. Los filtros del diccionario utilizan categorías y rasgos, no etiquetas escritas manualmente en cada tarjeta.

La fecha y versión visibles ayudan al lector a saber si consulta información vigente. Las páginas internas pueden enlazar directamente a la regla citada.

Documentación accesible

Todo grafismo necesita nombre textual y descripción. Los colores deben disponer de etiquetas y alternativas perceptibles.

Encabezados jerárquicos, tablas legibles y ejemplos copiables permiten utilizar el manual con lectores de pantalla y dispositivos móviles.

Copias de seguridad y formatos abiertos

La fuente maestra debe guardarse en formatos estructurados y exportables. Depender únicamente de una interfaz o plugin dificulta recuperar el idioma.

Las copias incluyen datos, imágenes, fuentes, reglas, corpus y registro de versiones. Se verifica periódicamente que puedan restaurarse.

Cómo evitar divergencias

Ninguna sección debería editar definiciones directamente si esas definiciones proceden del maestro. Las propuestas vuelven al origen y después se regeneran las vistas.

Un informe puede comparar versión del diccionario, teclado y traductor. Si no coinciden, la publicación se detiene.

Auditoría periódica

Cada cierto número de cambios se revisan colisiones gráficas, duplicados semánticos, ejemplos contradictorios y reglas sin pruebas.

La auditoría también pregunta qué partes están poco documentadas. La ausencia de errores registrados no significa que el sistema esté completo.

Una plantilla para proponer cambios

Cada propuesta debería responder cinco preguntas: qué problema resuelve, qué unidades afecta, cómo se representa, qué ejemplos la demuestran y qué materiales necesitan actualización. También debe indicar alternativas consideradas y el motivo de descartarlas.

Esta plantilla evita debates basados solo en gusto. Una nueva raíz no se aprueba porque suena bien, sino porque cubre una necesidad que no puede expresarse de forma productiva con los recursos existentes.

Responsables y revisión cruzada

Aunque el proyecto tenga un autor principal, conviene separar revisión lingüística, visual y técnica. Una regla puede ser semánticamente sólida y fallar en el teclado; un grafismo elegante puede colisionar con otro en móvil.

La revisión cruzada registra quién comprobó cada dimensión y qué dudas permanecen abiertas. No es burocracia: crea una memoria de decisiones que evita repetir discusiones meses después.

Publicar una edición estable

Una edición estable congela un conjunto coherente de léxico, gramática, corpus y recursos. Antes de publicarla se ejecutan validaciones, se regeneran páginas, se prueban traducciones en ambos sentidos y se comprueba el teclado en móvil y escritorio.

Después se conserva una copia completa con su número de versión. Las mejoras continúan en una rama experimental para no alterar silenciosamente el material que ya utilizan los estudiantes.

Documentación para personas y máquinas

Las explicaciones narrativas ayudan a aprender; los campos estructurados permiten validar y traducir. Ambas capas deben coexistir. Una regla puede incluir una descripción clara para lectores y una representación formal para el motor.

Si solo existe texto libre, la automatización necesita adivinar. Si solo existen códigos, la lengua se vuelve inaccesible. La documentación completa conecta precisión técnica y comprensión humana.

Lista de comprobación editorial

1. Todos los elementos tienen identificador.
2. Las definiciones separan núcleo y extensiones.
3. Las raíces próximas incluyen contrastes.
4. Las reglas contienen ejemplos y errores.
5. El corpus conserva glosa y traducción.
6. Los cambios tienen versión y registro.
7. Teclado, diccionario y traductor comparten datos.
8. La publicación supera validaciones automáticas.
9. Existen copias restaurables.

Errores frecuentes

• Guardar definiciones solo dentro de páginas web.
• Modificar una traducción sin revisar ejemplos.
• Publicar propuestas experimentales como definitivas.
• No conservar formas antiguas para compatibilidad.
• Crear un corpus formado solo por ejemplos fáciles.
• Versionar archivos, pero no reglas ni datos.
• Permitir ediciones paralelas sin sincronización.

Una arquitectura documental mínima

El núcleo puede dividirse en inventario léxico, reglas gramaticales, corpus anotado, recursos visuales y registro de cambios. Cada bloque utiliza identificadores compartidos.

Desde esa base se generan el diccionario público, la guía, el teclado, el traductor y los materiales de aprendizaje. La arquitectura sigue siendo comprensible aunque el idioma crezca.

El proyecto puede añadir después buscadores, ejercicios, exportaciones o herramientas comunitarias sin cambiar el principio central. Todos esos productos consultan los mismos identificadores y reglas. Si una función necesita mantener su propia copia del idioma, la arquitectura debe revisarse antes de publicarla.

También conviene conservar un conjunto pequeño de ejemplos de referencia que cubra los mecanismos fundamentales. Antes de una nueva edición, esos ejemplos se revisan manualmente y se comparan con el resultado automático. Funcionan como una prueba de lectura humana capaz de detectar cambios correctos técnicamente, pero incoherentes con la intención lingüística.

Conclusión

La coherencia publicada debe poder comprobarse siempre de forma independiente.

Documentar una lengua construida significa convertir intuiciones en decisiones verificables. El léxico define unidades; la gramática establece operaciones; el corpus demuestra usos; y las versiones explican la evolución.

Cuando Avuneki utiliza una fuente única de verdad, cada cambio puede propagarse sin contradicciones. La documentación deja de ser un apéndice y se convierte en la infraestructura que permite aprender, traducir y ampliar el idioma con confianza.