Header Ads Widget

Ticker

6/recent/ticker-posts

8 pequeños ajustes de API Docs que ofrecen grandes resultados en DX

 


Crear documentación de API brillante puede ser complicado. Es una especie de acto de equilibrio: seleccionar la información esencial que los desarrolladores necesitan para comenzar rápidamente, sin dejar de desarrollar otros temas más complicados en detalle. Pero, ¿qué pasaría si pudiera mejorar la experiencia del desarrollador para los usuarios en general con solo unos pocos ajustes simples?

Inspirándonos en algunas de las últimas incorporaciones de Stripe a su documentación , hemos creado una lista de 8 de los ajustes más pequeños para sus documentos de API que garantizan una gran experiencia de desarrollador. Desde un modo oscuro amigable con la vista hasta una humilde tabla de contenido, aquí hay algunos pequeños cambios que le dan a la documentación de API una ventaja especial.

1. Modo oscuro

El modo oscuro, también llamado modo nocturno , ha vuelto en los últimos años. Ya sea que debamos agradecer la nostalgia de las interfaces de computadora de los ochenta o el creciente número de usuarios de Reddit a medianoche, el modo oscuro se está convirtiendo lentamente en una expectativa. Estudios recientes incluso han sugerido que las interfaces en modo oscuro consumen menos energía y son más agradables a la vista.

En cualquier caso, el modo oscuro es una característica sencilla que puede agregar a sus documentos API. A algunos desarrolladores les encantará solo por los cosméticos, mientras que otros se encontrarán rápidamente construyendo nuevas integraciones bajo la luz de la luna, gracias a la visibilidad mejorada.


2. Califica esta página

Otra característica de tendencia en las páginas de soporte de todo tipo, no solo los documentos de API, es la capacidad de calificar la página. Los documentos de Shopify preguntan "¿Qué tan útil fue esta página?", Lo que le permite responder en una escala de cinco puntos desde una sonrisa hasta fruncir el ceño, mientras que Stripe hace la pregunta binaria "¿Fue útil esta sección?"

Independientemente de cómo elija implementarlo, una función de calificación esencial es una manera fácil de mejorar la experiencia del desarrollador. Por supuesto, tener un widget de calificación en cada página (o sección) es solo la mitad: también debe volver a visitar y revisar las páginas en función de los comentarios de los desarrolladores.


3. Carga instantánea

Es el siglo XXI y la velocidad es más importante que nunca. No hay nada más frustrante que una página que tarda varios segundos en cargarse, especialmente cuando está escaneando docenas de ellas a la vez, buscando encontrar un tidbit ultra específico.

¡Haga un favor a sus desarrolladores y optimice las páginas para velocidades de carga rápidas! Stripe ahora cuenta con “carga instantánea” en sus páginas de documentos, pero ciertamente no nos quejamos si sus páginas toman algunas décimas de segundo. Con medidas simples como el almacenamiento en caché y la optimización de imágenes, reducir los tiempos de carga de la página es más fácil de lo que cree.


4. Widget de estado

En nuestro artículo reciente sobre 5 ejemplos de excelente documentación de API, elogiamos a GitHub por el sencillo widget de estado de API que presentan en cada página. Aunque esta característica en particular puede ser un poco más complicada en términos de implementación, es un fantástico ahorro de tiempo en esas raras circunstancias en las que su API está en mantenimiento o se derrumba.


5. Temas destacados

La sección "Temas destacados" o "Temas populares" es un pequeño ajuste que recogimos de la documentación de la plataforma de Google Maps. Encontrará que muchos desarrolladores llegan a la página de inicio de su documentación, ya sea a través de una búsqueda o por referencia, y esta es una excelente oportunidad para que los guíe en la dirección correcta.

Si se usa correctamente, una sección de "Temas destacados" guía a los desarrolladores hacia la información que es más probable que busquen. Alternativamente, puede utilizar esta función para promocionar funciones nuevas o poco apreciadas, que de otro modo se pasarían por alto.


6. Haga clic para copiar

Hacer clic para copiar es una función que he visto en la documentación de referencia de Stripe y Twilio . Es exactamente lo que parece: un botón en el que puede hacer clic para copiar un fragmento de código automáticamente. Claro, es posible que solo ahorre medio segundo del tiempo de sus desarrolladores, pero cada pequeño detalle cuenta, ¡especialmente cuando los desarrolladores están copiando cosas una multitud de veces!


7. Tabla de contenido

Una tabla de contenido es una simple adición a cada página de su documentación. Una vez más, esto ayuda a ahorrar tiempo a los desarrolladores, una y otra vez. En los documentos de Shopify, incluyen una sección "En esta página" con hipervínculos a las dos a cinco partes de la página.

No hay reglas establecidas sobre cómo implementar esto. Si elige incluir una tabla de contenido en cada página o solo en algunas de ellas, por ejemplo, depende de usted. En cualquier caso, el objetivo final es que los desarrolladores obtengan la información que necesitan más rápido.


8. ¿Qué sigue?

¿Que sigue? es otra característica que eliminamos de Twilio Docs. Puede suponer que los desarrolladores que leen su documentación están siguiendo una progresión, tal vez implementando su API por primera vez, y, en base a eso, puede ofrecer sugerencias sobre lo que deberían leer a continuación en forma de ¿Qué sigue? sección.

Por ejemplo, si comienza en la página Envío de mensajes de Twilio , eventualmente se le recomendará la documentación para "convertir sus mensajes en una conversación", "rastrear el estado de entrega de los mensajes" u "optimizar la capacidad de entrega de sus mensajes". Todas estas son sugerencias relevantes, ¡y puede apostar a que un puñado de desarrolladores hace clic en ellas!


Pensamientos finales

Ahí lo tiene: ocho pequeños ajustes para sus documentos API que brindan una gran experiencia para el desarrollador. Claro, algunos de estos son más efectivos que otros, pero hemos obtenido cada uno de ellos directamente de la mejor y más grande documentación del mundo. Puede apostar que si implementa estas mismas características en sus documentos de referencia, los desarrolladores solo tendrán cosas buenas que decir sobre los cambios.

Publicar un comentario

0 Comentarios