Introducción

Hay distintas maneras de acceder a la información :

  1. (crono)lógica, como leer página por página, línea por línea, hasta llegar al final de la publicación,
  2. temática, como ir al índice de contenidos y saltar directamente a la parte que te interesa, siempre que el contenido esté dividido en unidades de contenido significativas,
  3. transversal, como seguir una sección de “publicaciones relacionadas” basada en la similitud de contenido (definida manualmente, con etiquetas y palabras clave, o aprendida por análisis temático mediante IA), o referencias cruzadas explícitas. Por ejemplo, la mayoría de los sitios web tienen archivos que listan todas las páginas que tienen una etiqueta/palabra clave determinada, los libros tienen glosarios.
  4. basada en pistas, como presentar una bibliografía de publicaciones más detalladas o una sección de “más información” al final del contenido, o anticipar contenido posterior,
  5. basada en fuentes, siguiendo referencias (normalmente notas al pie o notas al margen) a las publicaciones de donde se extrae la información, principalmente con fines de verificación,
  6. recuperación de información, es decir, un motor de búsqueda.

Tienes que dar soporte a todas ellas a la vez porque son complementarias y la mejor en cada contexto depende del conocimiento inicial y de las necesidades del lector. Ninguna de esas maneras es superior a las demás. Esto significa que hay una buena cantidad de “relleno de palabras clave” que hacer al escribir, para asegurar que el análisis de contenido basado en palabras clave y la recuperación de información por palabras clave funcionen como se espera.

Un manual/documentación no es un curso, pero limitarse a una lista árida de funciones/controles de la GUI y su definición es… demasiado árido. Necesitas crear enlaces entre el contenido (que no son meros enlaces HTML). En Ansel, los flujos de trabajo empiezan con un objetivo y despliegan las herramientas para alcanzarlo. La documentación empieza con las herramientas y presenta cómo y dónde se pueden usar. Pero esos son los dos extremos del espectro, y la realidad siempre está un poco en medio.

De todos modos, el conocimiento es un grafo de red . Solo tienes que prestar atención a los enlaces entre los nodos. Son al menos tan importantes como el contenido.

Implementación práctica en Ansel

Ansel usa Hugo  como su CMS, tanto para la documentación como para el resto del sitio web. La implementación práctica de los principios enunciados arriba tendrá que lidiar con las funciones básicas de Hugo.

Acceso (crono)lógico y temático

El contenido de Hugo se organiza en secciones  que son esencialmente subcarpetas de la carpeta principal /content. Las subcarpetas se pueden anidar infinitamente. El tema del sitio web presenta la vista en árbol de todas las secciones en la barra lateral izquierda, en pantallas anchas (escritorio). Las secciones y los niveles superiores de subsección se pueden expandir/contraer a petición del usuario. Esta vista en árbol proporciona el índice de contenidos de nivel superior que actúa como acceso temático.

Dentro de las secciones, el orden relativo de las páginas se puede definir manualmente usando el parámetro weight  en las cabeceras de Markdown, así :

1---
2title: Documenting Ansel
3date: 2025-10-13
4weight: 9
5---
6
7My content here

El parámetro weight es opcional. Si no se usa, los listados de páginas normalmente usarán la date para ordenar el contenido, pero también podrían usar el orden alfabético del título de la página. Este orden proporciona el acceso (crono)lógico.

Dentro de las páginas, si hay más de dos secciones en el contenido (definidas por títulos de segundo nivel, p. ej. <h2> en HTML o ## en Markdown), Hugo añadirá automáticamente un índice de contenidos interno en la barra lateral derecha, en pantallas anchas (escritorio).

Acceso transversal

Se pueden definir etiquetas en el sitio web usando el parámetro tags en la cabecera de Markdown, así :

1---
2title: This page title
3date: 2022-12-04
4tags:
5    - color science
6    - pipeline
7---
8
9Your content

Las etiquetas son opcionales y se muestran como enlaces en los que se puede hacer clic en varios lugares del tema del sitio web. Al hacer clic en una etiqueta se abre su archivo, que lista todas las páginas que tienen esa etiqueta. Esto proporciona el acceso transversal.

También se anima a los redactores a añadir enlaces cruzados en su contenido, de páginas del sitio web a otras páginas del sitio web, para fomentar el acceso transversal. Los conceptos que tienen una entrada en el sitio web deberían convertirse en enlaces a la página que describe cada concepto.

Basado en pistas

Los redactores son libres de añadir una sección de Bibliografía o Más información al final de sus páginas, con una lista de publicaciones y enlaces. Esas publicaciones pueden ser internas o externas al proyecto Ansel. Pueden ser periféricas al tema tratado en el contenido.

También es posible terminar las páginas con una apertura hacia el siguiente paso lógico, al escribir sobre flujos de trabajo o módulos.

Basado en fuentes

Hugo admite Markdown extendido, que admite notas al pie . Estas se recomiendan para referenciar fuentes, así :

1The typical observer has Just Noticeable Difference (Delta E) of 2.3[^1]
2
3[^1]: Some Author, Some Publisher, _A real-world, large-sampled, study of vision parameters for white, rich, educated, American students of the Rochester Institute of Technology_, (some year). [URL](https://doi.org/xxxxx)

Ansel no se ha decidido por ningún formato académico particular para las citas de fuentes en este punto, aunque el estilo de citación IEEE  parece el más adecuado para el enfoque de notas al pie con índice numérico.

Asegúrate de incluir el DOI  de la publicación, o al menos alguna URL a largo plazo en la que se pueda recuperar ahora y en el futuro.

Recuperación de información

Por ahora, Chantal  se encarga de esa parte. El índice web se actualiza manual y periódicamente.

Directrices

Escribir, incluso de forma técnica, es un arte difícil de reducir a un conjunto de directrices o buenas prácticas definidas, porque esto varía según el contexto. Debes tener cuidado de no ser más papista que el Papa. Una buena regla general es escribir para resolver problemas, lo que significa empezar preguntándote por qué y desde dónde llegó el lector a la página que estás escribiendo :

  1. ¿qué tipo de conocimiento se supone/asume que el lector ya tiene ?
    • lo ideal es que el lector sea consciente de esos prerrequisitos, así que quizá empieza con una lista de enlaces,
    • todo lo que no esté en esta lista debería definirse y explicarse en tu página,
  2. ¿qué tipo de tarea está intentando completar el lector que lo llevó a esta página ?
    • ¿quiere una chuleta rápida, un tutorial detallado o una base teórica ? Puede que tengas que elegir una de forma arbitraria.
    • esto decidirá qué pistas puedes añadir en el texto para mejorar la red de conocimiento,
    • esto probablemente debería sesgar todo el punto de vista de tu contenido y su longitud/profundidad.

Una buena manera de evaluar la calidad de la documentación es fijarse en las preguntas frecuentes (o los temas menos comprendidos) en los foros. Si el tema ya está cubierto pero siguen surgiendo preguntas, puede ser porque la documentación no es clara o las páginas relevantes están enterradas en la red y no son lo bastante descubribles.

Translated from English by : ChatGPT, Claude. In case of conflict, inconsistency or error, the English version shall prevail.