Workflow de Contenido

Esta sección detalla el proceso para crear, revisar y publicar contenido en el Wiki de NeoDigital, asegurando un flujo de trabajo eficiente y manteniendo altos estándares de calidad.

Estructura de documentos

Cada documento del Wiki debe seguir la siguiente estructura:

Frontmatter - Metadatos al inicio del archivo:

---
title: Título del documento
description: Breve descripción para SEO y metadatos
---

Contenido principal - Estructura recomendada:

# Título principal (h1)

Introducción y contexto.

## Subtítulo (h2)

Contenido detallado.

### Subsección (h3)

Detalles específicos.

## Otro subtítulo (h2)

Más contenido...

Proceso de creación y publicación

Para añadir o modificar contenido en el Wiki, sigue estos pasos:

1. Desarrollo local (opcional)

Para trabajar localmente y visualizar los cambios en tiempo real:

# Clonar el repositorio (solo la primera vez)
git clone git@github.com:NeoDigital-MX/neodigital-wiki.git
cd neodigital-wiki

# Crear una rama para tus cambios
git checkout -b nombre-feature-o-documento

# Instalar dependencias (solo la primera vez)
npm install

# Iniciar servidor de desarrollo
npm run dev

2. Creación del contenido

Crear un nuevo archivo Markdown en la carpeta adecuada:

# Navegar al directorio de documentos
cd src/content/docs/

# Crear archivo para una página principal
nano nombre-documento.md

# O para una sección con subdocumentos
mkdir -p mi-seccion
nano mi-seccion/index.md
nano mi-seccion/subseccion.md

3. Actualización de la barra lateral

Para que el documento aparezca en la navegación, edita el archivo astro.config.mjs:

sidebar: [
  // Otras secciones...
  {
    label: 'Mi Nueva Sección',
    items: [
      { label: 'Introducción', link: '/mi-seccion' },
      { label: 'Subsección', link: '/mi-seccion/subseccion' }
    ]
  }
]

4. Envío de cambios

Una vez que hayas terminado de editar:

# Asegurarse de estar en la rama dev o crear una rama basada en dev
git checkout dev
# o
git checkout -b feature/nueva-documentacion origin/dev

# Añadir cambios
git add .

# Hacer commit
git commit -m "Añadir documentación sobre [tema]"

# Enviar cambios
git push origin dev
# o
git push origin feature/nueva-documentacion

5. Creación del Pull Request

Ve a GitHub
Selecciona “Pull requests” > “New pull request”
Selecciona como base main y como rama de comparación dev (o tu rama de feature)
Asigna a Gerardo Alpuche (COO) como revisor
Incluye una descripción clara de los cambios realizados
Haz clic en “Create pull request”

6. Proceso de revisión

El COO (Gerardo Alpuche) revisará el contenido y podrá:

Aprobar los cambios
Solicitar modificaciones
Hacer comentarios específicos

Si se solicitan cambios:

Realiza las modificaciones necesarias
Haz commit y push de los cambios a la misma rama
Los nuevos cambios aparecerán automáticamente en el Pull Request

7. Despliegue automático

Una vez que el Pull Request es aprobado y fusionado:

GitHub Actions detecta el cambio en la rama main
El workflow de CI/CD se activa automáticamente
Los cambios se despliegan en el servidor
El contenido se vuelve visible en https://wiki.neodigital.mx/

Mejores prácticas

Organización de contenido

Nombres de archivos: Usa minúsculas-con-guiones (kebab-case)
Rutas semánticas: Las URLs deben ser descriptivas de su contenido
Profundidad adecuada: No crear más de 3 niveles de anidación
Agrupación lógica: Agrupar documentos relacionados en directorios

Formato de documentos

Títulos claros: Descriptivos pero concisos
Descripciones SEO: Incluir descripciones optimizadas para motores de búsqueda
Estructura jerárquica: Usar niveles de encabezados (H1, H2, H3) correctamente
Espaciado apropiado: Separar secciones con líneas en blanco para mejor legibilidad

Uso de recursos multimedia

Imágenes optimizadas: Colocar imágenes en src/assets/ preferentemente
Referencia relativa: Usar rutas relativas para imágenes y otros recursos
Texto alternativo: Siempre incluir atributos alt en las imágenes

Conclusión

Siguiendo este flujo de trabajo, aseguramos un proceso eficiente y ordenado para mantener actualizado el Wiki de NeoDigital, con un alto nivel de calidad y supervisión adecuada.

Con esto completamos el recorrido por todo el proceso de implementación del Wiki, desde su concepción inicial hasta su mantenimiento continuo.