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.

Una base de conocimientos interna ayuda a tu equipo a encontrar respuestas y mantener una fuente de verdad. Si tu equipo tiene información distribuida en diferentes canales y plataformas, es posible que las personas encuentren información incorrecta o ninguna información cuando busquen respuestas. Una base de conocimientos centralizada resuelve esto al colocar las respuestas donde todos puedan encontrarlas y darle a tu equipo un lugar específico para registrar el conocimiento compartido.

Mintlify proporciona la infraestructura para bases de conocimientos a las que todo tu equipo puede contribuir.

• Búsqueda con IA: El assistant responde preguntas utilizando el contenido de tu base de conocimientos, para que las personas encuentren respuestas sin saber exactamente dónde buscar.
• Integración con Slack: Añade el assistant a Slack para que tu equipo pueda hacer preguntas sin salir de su flujo de trabajo.
• Contribuciones con baja barrera de entrada: El web editor y el agent permiten que cualquier miembro de tu equipo actualice el contenido sin aprender Git o Markdown.
• Autenticación integrada: Controla el acceso con SSO u OAuth y usa la personalización para mostrar contenido diferente a distintos grupos.

​

Requisitos previos

Si aún no has creado un proyecto de Mintlify, consulta la Guía rápida para publicar tu sitio.

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

​

Migra el contenido existente

Si estás creando una base de conocimientos desde cero, salta a Diseña la estructura de navegación.

​

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 se deba preservar, 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 la estructura de navegación de tu base de conocimientos. Crea este archivo en la raíz del repositorio de tu proyecto.

{
  "navigation": {
    "groups": [
      {
        "group": "Finance",
        "pages": [
            "finance/overview",
            "finance/budgeting-process",
            "finance/expense-reports",
            "finance/cost-allocation"
        ]
      },
      {
        "group": "HR",
        "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.

​

Configura el assistant

El assistant se habilita automáticamente para los planes Pro y Custom. El assistant permite que tu equipo haga preguntas y obtenga respuestas con fuentes citadas de tu base de conocimientos.

Configura el assistant desde tu dashboard:

• Preguntas de ejemplo: Añade preguntas comunes como “¿cómo envío un informe de gastos?” o “¿cuál es la política de vacaciones?” para que las personas puedan obtener respuestas con un solo clic.
• Sitios de búsqueda: Incluye sitios adicionales que el assistant puede buscar al responder preguntas.
• Correo de derivación: Configura un correo de soporte para las preguntas que el assistant no pueda responder.

​

Agrega el assistant a Slack

El bot de Slack permite que tu equipo le haga preguntas al assistant sin salir de Slack. Crea un canal donde el bot responda a cada mensaje o deja que las personas mencionen al bot con @ en cualquier canal.

​

Permitir contribuciones del equipo

Una base de conocimientos se mantiene precisa cuando todos pueden actualizarla, no solo las personas que la configuraron. Mintlify ofrece tres formas para que los miembros del equipo contribuyan rápidamente a tu base de conocimientos.

​

Editor web

El editor web permite que cualquier persona cree y edite páginas directamente en su navegador. Los colaboradores pueden:

• Editar páginas de forma visual o en Markdown.
• Arrastrar y soltar para reorganizar la navegación.
• Cargar imágenes y contenido multimedia.
• Crear branches y solicitudes de extracción para revisión.

Es ideal para expertos en la materia que conocen el contenido pero no se sienten cómodos con flujos de trabajo basados en código.

​

Agente

El agent en tu dashboard crea actualizaciones de la documentación a partir de instrucciones en lenguaje natural. Describe lo que quieres cambiar y el agente creará una solicitud de extracción con las actualizaciones.

Por ejemplo, un miembro del equipo podría indicar: “agrega una sección a la página de la política de gastos que explique cómo enviar recibos de comidas de más de $50” y copiar la página de la política de gastos existente en el prompt. El agente redactaría el contenido y abriría una solicitud de extracción para revisión.

​

Localmente

Cualquier persona con acceso al repositorio de tu base de conocimientos puede trabajar localmente en su editor preferido y enviar cambios al repositorio.

​

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.