Header Ads Widget

Ticker

6/recent/ticker-posts

Tres formas de organizar los documentos para desarrolladores de API


 Diseñar y escribir una buena documentación de API puede ser una tarea abrumadora, pero es fundamental para cualquier empresa impulsada por API o B2D (Business 2 Developer) para garantizar el éxito del desarrollador. Su documentación también es un activo de marketing de su empresa y pueden ser las primeras páginas que visita un nuevo cliente potencial para evaluar qué tan difícil es su integración y cómo funciona el producto.

Para ayudar a mejorar la forma en que se presenta la documentación de su API, en esta publicación, analizaremos diferentes formas de mejorar la estructura de su centro de desarrolladores para que se adapte bien a sus visitantes específicos. Una faceta importante de esto es elegir el mejor tipo de arquitectura de sitio para su portal de desarrollador de API.

Organización de alto nivel

Antes de discutir las características específicas de la documentación , vale la pena discutir la organización de alto nivel de la documentación. Cada empresa tendrá requisitos específicos para los documentos, pero entre las empresas que utilizan primero las API, la documentación suele clasificarse en una de estas tres categorías:

  1. Documentos centralizados con referencia de API separada
  2. Documentos centralizados combinados con referencia de API
  3. Documentos descentralizados

1. Documentos centralizados con referencia de API independiente

Las empresas que pertenecen a esta categoría tienen al menos dos niveles de documentación: Documentos para desarrolladores y Referencia de API . Las empresas con referencias de documentos y API dividen a los visitantes de documentos en dos grupos:

  • Desarrolladores interesados ​​en integraciones de nivel superior o SDK
  • Desarrolladores interesados ​​en la API REST sin formato o las bibliotecas de envoltura de API

El centro de desarrollo principal o el centro de documentación no discute la API REST en absoluto, ni discute las bibliotecas de envoltura de API. En cambio, hay enlaces de navegación desde los documentos a un sitio web de referencia de API separado e independiente. Muchas veces, la referencia de API utiliza un diseño o diseño diferente en comparación con el resto de la documentación, como un diseño de 3 o 2 columnas . Con este enfoque, la página de inicio de la documentación proporciona guías de introducción e información sobre cómo utilizar o integrar cada función del producto.

Las empresas que siguen este enfoque pueden estar muy centradas en las API o en los desarrolladores, pero ya tienen integraciones de mayor nivel, por lo que no todos los visitantes requieren trabajar con la API directamente. Estas empresas incluyen Stripe y Moesif . Stripe, por ejemplo, muestra sus SDK de Stripe.js y Android / iOS al frente y al centro en comparación con su ubicación de API REST.

El centro de desarrolladores de Moesif proporciona enlaces de navegación y una referencia de API separada

Muchos desarrolladores no necesitarán trabajar con su API REST directamente, ya que existen integraciones de nivel superior para comenzar. Por lo tanto, un desarrollador de NodeJS que visite los documentos del desarrollador por primera vez probablemente estará más interesado en un SDK de nivel superior en lugar de leer sobre la biblioteca de envoltura de API de NodeJS sin procesar. Recuerde, aunque probablemente sea muy íntimo con su propia API y sus SDK, es posible que un desarrollador recién llegado no lo sea.

Beneficios

  • Puede llevar a nuevas personas a la guía de inicio adecuada y evitar confusiones en torno a demasiadas integraciones.
  • El diseño de navegación se puede diseñar específicamente para el tipo de documentación. Por ejemplo, la referencia de la API puede ser una sola página larga, mientras que los documentos generales se dividen en muchas páginas web más pequeñas.
  • La referencia de API separada es útil para documentar las API REST que son muy similares a CRUD.
  • Ofrece a los usuarios avanzados una excelente URL de referencia de API optimizada para SEO y con capacidad de marcadores para cosas como esquemas de entidad sin tener que buscar en guías detalladas de introducción.
  • El sitio de referencia de API puede usar una cadena de herramientas separada y aprovechar las soluciones de generación de documentos de terceros como SwaggerHub.
  • Puede ser ideal para empresas que tienen una clara división de responsabilidades entre quién posee la referencia de API y los documentos y guías para desarrolladores.

Desventajas

  • No es ideal para empresas que tienen un solo nivel de integraciones.
  • Puede forzar artificialmente que la referencia de la API pase al backstage, lo que puede no ser su requisito comercial.
  • Es posible que la navegación centralizada no se adapte bien a empresas con muchas líneas de productos distintas.
  • La breve documentación de la API puede asustar a los no desarrolladores.
  • Puede descentralizar elementos de navegación críticos como la búsqueda.
Lea también: 7 ingredientes que conforman un excelente centro para desarrolladores

2. Documentos centralizados combinados con referencia de API

Las empresas que pertenecen a esta categoría combinan su referencia de API HTTP con el resto de sus documentos de desarrollador y no tienen un sitio web de referencia de API independiente. En esta situación, aunque la referencia de la API se combina con el resto de los documentos para desarrolladores, a menudo hay un área de ayuda para no desarrolladores separada. Las empresas con documentos de desarrollador combinados tienden a dividir a los visitantes en una de las siguientes cohortes:

  • Desarrolladores que pueden usar un SDK, integración o posiblemente la API REST sin procesar.
  • Opcionalmente, no desarrolladores que solo necesitan comprender cómo usar el panel o el producto.

Mixpanel y Amplitude siguen este enfoque bastante de cerca. Square también sigue esto con Square Docs .

Mixpanel documenta su referencia de API HTTP junto con bibliotecas y SDK específicos del idioma

Estas empresas comercializan tanto a desarrolladores como a no desarrolladores. Para Mixpanel y Amplitude, el usuario principal no es necesariamente el desarrollador que integró el producto. Por el contrario, Mixpanel y Amplitude están comercializando su producto entre los especialistas en marketing y los gerentes de productos que buscan datos. Square comercializa su producto entre comerciantes y minoristas. Estas empresas suelen comercializar la flexibilidad del producto en lugar de la flexibilidad de la API.

Este tipo de empresas pueden requerir documentación tanto para desarrolladores como para no desarrolladores. Una referencia de API separada crearía tres niveles de documentación: ayuda para no desarrolladores , documentos para desarrolladores y referencia de API . Agregar un tercer nivel para referencia de API puede causar una navegación confusa o asustar al usuario principal.

Los documentos combinados también se pueden usar cuando no hay una distinción clara entre los SDK de integración y la API REST y los contenedores de API. Si todas sus integraciones están centradas en API y no puede agrupar limpiamente sus integraciones en categorías centradas en API y no centradas en API  , entonces posiblemente puede crear una pesadilla de navegación en la que sea difícil ver y buscar todas las integraciones en un solo lugar si utilizó documentación API separada. La combinación de la referencia de API HTTP con otras guías le permite tener fácilmente guías prácticas, todas centralizadas y con capacidad de búsqueda en un sitio.

Si observa los documentos de Algolia , aunque separan un poco su API REST sin procesar, todas las demás integraciones están al mismo nivel. En su mayor parte, Algolia es una mezcla entre el primer enfoque y este.

Beneficios

  • Evita tener demasiados sitios de documentos, como ayuda para no desarrolladores, documentos para desarrolladores, referencias de API, etc.
  • Garantiza que la API HTTP esté al mismo nivel que otras integraciones y no entre bastidores.
  • Diseño más sencillo al escribir nuevos documentos para un nuevo producto con contenido mínimo.
  • La búsqueda de documentación se puede centralizar, lo que resulta útil si algunas funciones requieren su API mientras que otras requieren un SDK.
  • Evita asustar a los que no son desarrolladores al tener documentos concisos y demasiado "centrados en el desarrollador o en la API".

Desventajas

  • Puede causar confusión por sobrecarga de integración si tiene integraciones de nivel inferior y superior.
  • Es difícil escalar los equipos internos, especialmente si el responsable de mantenimiento de la API es diferente a los documentos generales del desarrollador.
  • Debe comprometer el diseño de la navegación, ya que ciertos elementos pueden ser más adecuados para navegar por la referencia de la API que para navegar por documentos generales.
Relacionado: Guía definitiva para más de 30 soluciones de documentación de API

3. Documentos descentralizados

La documentación descentralizada es bastante diferente de las otras dos categorías. En lugar de centralizar tipos de documentación en el mismo sitio, eligen otros pilares en torno a los cuales organizar su documentación, como las líneas de productos . Estas empresas dividen a los visitantes de documentos en cohortes específicas según el producto o servicio que le interesa al visitante.

Como ejemplo, los productos de Twilio incluyen no solo mensajes SMS, sino también autenticación y video, por lo tanto, agrupan los documentos de Twilio en líneas de productos en lugar de documentos frente a referencias de API. Muchos de los usuarios de Twilio que desean integrar el producto SMS de Twilio pueden no preocuparse por su producto de autenticación Authy .

En lugar de abarrotar un sitio de documentos centralizado, estas empresas se descentralizan de tal manera que al ver la referencia de la API de Twilio, solo está viendo la documentación relacionada con usted . Si está interesado en Authy, solo navegue por la documentación de Authy. Los documentos descentralizados pueden ayudar a las grandes empresas que no tienen equipos de documentación centralizados, donde cada producto posee su respectiva documentación.

Con un enfoque descentralizado, la documentación está dirigida a productos y grupos de visitantes específicos.

Beneficios

  • Ordena líneas de productos complejas, puede ser útil para productos de grandes empresas.
  • Permite a la empresa escalar la documentación por equipos de producto. Solo se necesita un pequeño equipo central para mantener el diseño y la infraestructura transversales.

Desventajas

  • Puede silo artificialmente productos que deben estar interconectados. Para Twilio, SMS y Authy son productos realmente no relacionados. Sin embargo, usted no querrá silo separados, pero relacionados funciones dentro del mismo producto .
  • Es difícil organizar las guías de introducción si se utiliza la misma biblioteca o integración en todas las líneas de productos.

5 características específicas para impulsar la arquitectura del sitio

Cada empresa y sus necesidades de documentación son únicas. Hay algunas tendencias en torno a las funciones de documentación específicas que se analizan a continuación y que se utilizan entre empresas populares como Stripe y Auth0. Puede utilizarlos como inspiración para crear sus propios sitios de documentación de API:

  • Navegación fija : la navegación fija es imprescindible para cualquier persona que cree documentos largos, ya que mantiene la barra lateral de navegación siempre a la vista. Se pueden encontrar ejemplos de navegación fija en los documentos de Stripe, Auth0 y Algolia.
  • Estado de desplazamiento guardado : guardar el estado de desplazamiento puede resultar útil si el usuario actualiza la página. Incluso puede agregar el enlace de encabezado más cercano en la URL como un enlace hash en caso de que un visitante copie / pegue la URL desde el navegador.
  • Estilos de navegación de la barra lateral: la navegación de la barra lateral izquierda en acordeón y sin acordeón se utiliza mucho para la documentación y depende de factores como la cantidad de enlaces de navegación. Puede aprovechar proyectos de código abierto como Navgoco para crear una navegación impresionante al estilo de acordeón.
  • Documentación de tres columnas : considere una referencia de API de tres columnas utilizando Slate como modelo estándar. Los documentos de 3 columnas pueden ser útiles para la referencia de API de estilo CRUD donde la referencia de API principal es la misma independientemente del idioma, pero un visitante puede ver rápidamente la implementación específica en su idioma principal también.
  • Botón Editar en Github : almacenar su documentación en GitHub o similar facilita que los desarrolladores contribuyan a sus documentos. Un botón Editar que apunta al repositorio de origen puede fomentar la participación de la comunidad y garantizar que su documentación se corrija en busca de errores. Las organizaciones más grandes como Microsoft Azure tienen un botón Github en sus documentos publicados que apunta a azure-docs en Github .

La configuración de documentos adecuada para su entorno

Hay muchas formas de diseñar y organizar la documentación del desarrollador, y cada empresa tendrá requisitos específicos en torno a su documentación. Sin embargo, al investigar patrones de diseño comunes en la documentación para desarrolladores moderna, puede asegurarse de que sus desarrolladores encontrarán la ayuda que necesitan. Su documentación también puede ser una poderosa herramienta de marketing, lo que significa que debe tratarla como un producto vendible. Realice pruebas A / B y pida comentarios a los demás constantemente. Después de todo, es un documento vivo.

 

Publicar un comentario

0 Comentarios