Crear documentación para desarrolladores

La documentación para desarrolladores ayuda a las personas a entender e integrarse con tu producto. Una buena documentación permite que las personas hagan más con tu producto, reduce la carga de soporte, acelera la adopción y mejora la experiencia del desarrollador.

Mintlify proporciona infraestructura diseñada para la documentación para desarrolladores.

• Generación de referencias de API: Genera referencias de API interactivas a partir de especificaciones OpenAPI que permiten a los desarrolladores probar endpoints en tu documentación.
• Bloques de código con explicaciones: El assistant explica ejemplos de código en contexto, ayudando a los desarrolladores a entender los detalles de implementación.
• Sincronización con Git: Mantén la documentación sincronizada con tu base de código usando GitHub o GitLab.
• Control de versiones: Mantén la documentación para múltiples versiones, de modo que los desarrolladores en versiones anteriores aún puedan encontrar información precisa.

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

• La especificación de tu API en formato OpenAPI (si estás documentando una API)
• Un repositorio Git para tu documentación
• Acceso de administrador a tu organización de Mintlify

Si estás creando la documentación desde cero, pasa a Planifica la estructura de la documentación.

Revisa tu documentación actual para entender qué tienes y qué necesitas migrar.

• Referencia de API: ¿Se genera a partir de una especificación o está escrita a mano? ¿Qué endpoints documentas?
• Guías y tutoriales: ¿Qué guías de integración tienes? ¿Están actualizadas?
• Ejemplos de código: ¿Qué lenguajes y frameworks utilizas?
• Documentación de SDK: ¿Tienes documentación independiente para cada SDK?
• Cambios: ¿Mantienes un registro de cambios o notas de lanzamiento?
• Metadata: ¿Tienes metadata para tu contenido, como fechas, autores y etiquetas?

• Exporta a Markdown para la migración más sencilla a Mintlify.
• Exporta las especificaciones OpenAPI para el contenido de referencia de API.
• Exporta a HTML si Markdown no está disponible y luego conviértelo a Markdown.

La documentación para desarrolladores suele incluir varios tipos de contenido. Estructura la navegación en función de cómo tus usuarios entienden tu producto.

{
  "navigation": {
    "groups": [
      {
        "group": "Get Started",
        "pages": [
          "introduction",
          "quickstart",
          "authentication"
        ]
      },
      {
        "group": "Guides",
        "pages": [
          "guides/webhooks",
          "guides/error-handling",
          "guides/rate-limits",
          "guides/pagination"
        ]
      },
      {
        "group": "Referencia de API",
        "pages": [
          "api-reference/overview",
          "api-reference/users",
          "api-reference/orders",
          "api-reference/products"
        ]
      },
      {
        "group": "SDKs",
        "pages": [
          "sdks/javascript",
          "sdks/python",
          "sdks/go"
        ]
      }
    ]
  }
}

Consulta Navigation para obtener más opciones de configuración.

Si tienes una API, genera una referencia interactiva a partir de tu especificación OpenAPI.

your-project/
├── docs.json
├── openapi.yaml
└── api-reference/
    └── overview.mdx

{
  "openapi": "openapi.yaml"
}

{
  "group": "API Reference",
  "pages": [
    "api-reference/overview",
    "api-reference/users/list-users",
    "api-reference/users/get-user",
    "api-reference/users/create-user"
  ]
}

El assistant ayuda a los desarrolladores a encontrar respuestas y comprender ejemplos de código. Configúralo desde tu dashboard.

• Preguntas de ejemplo: Añade preguntas dirigidas a desarrolladores como “¿Cómo autentico solicitudes a la API?” o “Muéstrame cómo manejar webhooks”.
• Explicaciones de código: El assistant puede explicar bloques de código en contexto cuando los desarrolladores hacen preguntas sobre ejemplos específicos.

Si mantienes varias versiones de tu API, configura el versionado para que los desarrolladores puedan encontrar la documentación de su versión.

{
  "versions": ["v2", "v1"],
  "navigation": {
    "groups": [
      {
        "group": "Referencia de API",
        "version": "v2",
        "pages": ["v2/api-reference/users"]
      },
      {
        "group": "Referencia de API",
        "version": "v1",
        "pages": ["v1/api-reference/users"]
      }
    ]
  }
}

Para obtener más información, consulta Versiones.

Instala la Aplicación de GitHub de Mintlify para mantener la documentación sincronizada con tu base de código y permitir contribuciones.

La documentación para desarrolladores necesita actualizaciones periódicas para que la información sea precisa y útil.

La documentación para desarrolladores está lista para publicarse. Después de desplegarla:

1. Anuncia la documentación a tu comunidad de desarrolladores.
2. Supervisa los patrones de búsqueda y las conversaciones en el assistant para identificar brechas.
3. Configura un proceso para actualizar la documentación con cada nueva versión de la API.
4. Recopila comentarios de los desarrolladores para mejorar el contenido a lo largo del tiempo.