Crear una base de conocimientos

Hospeda tu base de conocimientos interna en Mintlify para consolidar la información de tu equipo, mejorar las búsquedas y reducir la carga de mantenimiento.

​

Introducción

Esta guía te muestra cómo crear una base de conocimientos interna en Mintlify. Configurarás una estructura de navegación, migrarás contenido, configurarás la Autenticación y establecerás un proceso de mantenimiento.

Esta guía da por hecho que estás migrando contenido desde una base de conocimientos existente a Mintlify. Si estás creando una base de conocimientos con contenido completamente nuevo, puedes seguir pasos similares, pero omitir las etapas de auditoría y migración.

Si aún no has creado un proyecto de Mintlify, consulta la sección Inicio rápido para desplegar tu sitio.

​

Requisitos previos

• Un sistema de autenticación (SSO o proveedor OAuth como Okta o Azure AD)
• Control sobre tu dominio para el alojamiento
• Acceso de administrador a tu organización de Mintlify

​

Audita el contenido existente

Cataloga el contenido que tienes actualmente en tu base de conocimiento. Esto te ayuda a entender qué contenido necesitas migrar, planear cómo organizarlo en tu nueva base de conocimiento, identificar cualquier brecha en tu contenido y confirmar que trasladaste todo tu contenido a tu nueva base de conocimiento.

• Número total de artículos: Ayuda a estimar el esfuerzo de migración y a hacer seguimiento del grado de completitud.
• Temas y contenido: Informa la estructura de tu navigation y la organización del contenido.
• Organización actual: Observa cómo está organizado actualmente tu contenido y si coincide con la estructura que deseas.
• Tipos de contenido: Determina cualquier requisito de conversión de contenido para texto, PDF, videos y contenido incrustado.
• Metadata: Identifica cualquier metadata que deba preservarse, como fechas, autores y etiquetas.
• Requisitos de acceso: Determina el mejor enfoque de Autenticación para tu base de conocimiento.

​

Exporta tu contenido existente

La mayoría de las plataformas de base de conocimiento permiten exportar contenido en formatos estándar. El formato que elijas depende de tu plataforma actual y de tus prioridades.

• Exporta en Markdown para lograr la migración más sencilla a Mintlify. (recomendado)
• Exporta en HTML si Markdown no está disponible. Deberás convertir tu contenido a Markdown más adelante.
• Exporta en JSON o CSV si tienes metadata estructurada que necesites conservar.

​

Diseña la estructura de navegación

La estructura de navegación determina cómo las personas encuentran contenido en tu base de conocimientos. Puedes recrear tu estructura actual o rediseñarla para que se adapte mejor a cómo tu equipo concibe el contenido.

La migración es un buen momento para mejorar tu estructura. Plantéate si tu organización actual realmente funciona para tu equipo o si puedes reorganizarla para que la información sea más fácil de encontrar.

Tu archivo docs.json define cómo se organiza tu base de conocimientos. Crea este archivo en la raíz del repositorio de tu proyecto.

{
  "navigation": {
    "groups": [
      {
        "group": "Finanzas",
        "pages": [
            "finance/overview",
            "finance/budgeting-process",
            "finance/expense-reports",
            "finance/cost-allocation"
        ]
      },
      {
        "group": "Recursos Humanos",
        "pages": [
            "hr/overview",
            "hr/onboarding",
            "hr/benefits",
            "hr/time-off-policy"
        ]
      },
      {
        "group": "Ingeniería",
        "pages": [
          "engineering/overview",
          "engineering/dev-setup",
          "engineering/deployment",
          "engineering/code-standards"
        ]
      }
    ]
  }
}

Consulta Navigation para obtener más información sobre cómo estructurar tu base de conocimientos.

​

Configurar la autenticación

Determina quién necesita acceso a qué contenido en tu base de conocimientos.

Si todas las personas deben tener acceso a toda la base de conocimientos, configura solo la autenticación.

Si necesitas restringir el acceso a cierto contenido para usuarios o grupos específicos, configura la autenticación y la personalización.

​

Migra tu contenido

Mueve el contenido exportado a una estructura de carpetas que coincida con la estructura de navegación que diseñaste. Convierte el contenido a Markdown si es necesario, agrega el frontmatter que falte y configura los enlaces internos.

1. Organiza los archivos

   Crea carpetas que coincidan con la estructura de tu docs.json. Por ejemplo, si tu docs.json tiene un grupo Finance, crea una carpeta finance/:

   your-project/
   ├── docs.json
   ├── finance/
   │   ├── overview.mdx
   │   ├── budgeting-process.mdx
   │   ├── expense-reports.mdx
   │   └── cost-allocation.mdx
   ├── hr/
   │   ├── overview.mdx
   │   ├── onboarding.mdx
   │   ├── benefits.mdx
   │   └── time-off-policy.mdx
   └── engineering/
       ├── overview.mdx
       ├── dev-setup.mdx
       ├── deployment.mdx
       └── code-standards.mdx
   

   Coloca cada artículo en su carpeta correspondiente. La ruta del archivo debe coincidir con la ruta en tu docs.json. Por ejemplo, si docs.json hace referencia a "finance/expense-reports", el archivo debería ser finance/expense-reports.mdx en el repositorio de tu proyecto.

2. Agrega frontmatter a cada artículo

   Cada archivo .mdx necesita frontmatter en la parte superior con metadatos. Cada página requiere un título y una descripción. Consulta Pages para más información sobre los metadatos de las páginas.

   ---
   title: "Expense Report Process"
   description: "How to submit and track expense reports"
   ---
   
   Your content here...
   

3. Configura los enlaces internos

   Enlaza entre páginas usando rutas desde la raíz de tu proyecto.

   Consulta la [Guía de incorporación](/hr/onboarding) para la configuración de nuevos empleados.
   
   Si tienes preguntas, contacta al [Equipo de beneficios de RR. HH.](/hr/benefits#common-questions).
   

4. Convierte HTML y otros formatos a Markdown

   Si exportaste tu contenido como HTML, conviértelo a Markdown. Algunas herramientas que pueden ayudar incluyen:

   • Pandoc: Herramienta de línea de comandos que convierte entre muchos formatos.
   • CloudConvert: Conversor en línea que admite HTML, DOCX, PDF y más.
   • Extensiones de VS Code: Busca “HTML to Markdown” en las extensiones.
5. Gestiona múltiples formatos de contenido

   Si tienes archivos PDF, videos u otros elementos multimedia, decide cómo incluirlos en tu base de conocimientos.

   • Incorpora videos: Incorpora videos o enlaza a videos alojados.
   • Enlaza a archivos PDF: Agrega los PDF al repositorio de tu proyecto y enlázalos desde las páginas relevantes.
   • Convierte archivos PDF a Markdown: Si quieres que el contenido de un PDF sea una página, convierte los PDF a Markdown.

​

Optimizar el descubrimiento

​

Configurar el Asistente de IA

El assistant se habilita automáticamente para los planes Pro y Custom. Puedes personalizar el assistant desde tu dashboard.

• Buscar en sitios: Selecciona sitios adicionales, además de tu base de conocimientos, en los que el assistant pueda buscar al responder preguntas.
• Establecer preguntas de ejemplo: Define las preguntas predeterminadas que aparecen cuando alguien abre el panel del assistant. Si las personas tienen preguntas frecuentes como “¿Cómo envío un informe de gastos?” o “¿Cuál es la política de vacaciones de la empresa?”, añádelas aquí para ahorrarles tiempo.

​

Integración con Slack

Si tu equipo utiliza Slack, puedes añadir la aplicación de Slack a tu espacio de trabajo. Esto permite que tu equipo realice búsquedas en tu base de conocimientos sin salir de Slack.

​

Establece flujos de trabajo de mantenimiento

Una base de conocimientos puede deteriorarse rápidamente sin mantenimiento. Configura sistemas para mantener el contenido actualizado y ayudar a tu equipo a contribuir a la base de conocimientos.

1. Asignar responsables del contenido

   Designa un responsable o un pequeño equipo para cada sección. No tienen que escribir todo el contenido, pero sí son responsables de:

   • Revisar el contenido con regularidad.
   • Señalar la información desactualizada.
   • Aprobar nuevas páginas en su sección.
   • Responder cuando las personas reporten errores.
2. Configurar ciclos de revisión y verificación de contenido

   El contenido se vuelve obsoleto con el tiempo. Establece un calendario de revisión.

   • Contenido crítico: Revisar cada 30 días
   • Contenido estándar: Revisar cada 90 días
   • Contenido atemporal (evergreen): Revisar anualmente

   Al revisar, comprueba:

   • ¿Los enlaces siguen siendo válidos?
   • ¿Han cambiado los sistemas o procesos?
   • ¿Los ejemplos están actualizados?
   • ¿Hay información nueva que debería añadirse?
3. Crear directrices de contribución

   Facilita que cualquier persona mejore la base de conocimientos. Tus directrices deberían cubrir:

   • Formato: ¿Tienes plantillas específicas o requisitos de formato?
   • Proceso: ¿Cómo debería alguien proponer y enviar cambios?
   • Revisión: ¿Quién revisa las propuestas? ¿Cuál es el tiempo de respuesta?
   • Alcance: ¿Qué tipos de contenido entran en el alcance?
4. Supervisar métricas de uso

   Revisa cómo tu equipo utiliza la base de conocimientos para priorizar contenido e identificar áreas de mejora. Establece un ritmo regular para revisar las métricas de uso: mensual o trimestral son buenos intervalos.

   • ¿Qué artículos reciben más visitas? Invierte en mantenerlos precisos y fáciles de leer.
   • ¿Qué artículos no reciben visitas? Considera eliminarlos o mejorar la facilidad para encontrarlos.
   • ¿Cuál es la tasa de rebote? Si las personas se van de inmediato, es posible que el contenido no sea útil o que la navegación pueda mejorarse.

​

Próximos pasos

Tu base de conocimientos está lista para el lanzamiento. Después de desplegarla:

1. Anuncia la base de conocimientos a tu equipo.
2. Supervisa el uso y los patrones de búsqueda en tus Analytics.
3. Fomenta las contribuciones cuando la gente detecte carencias.
4. Revisa y actualiza el contenido con regularidad.

Las bases de conocimientos más exitosas evolucionan en función de cómo los equipos las usan en la práctica.