Header Ads Widget

Ticker

6/recent/ticker-posts

El arte y la personalización de la experiencia de documentación de API

 

Una API es un método de comunicación. En el mejor de los casos, es una herramienta para facilitar la creación de software, pero en el peor, una pérdida de tiempo y una molestia constante. Las buenas API abstraen la complejidad y proporcionan rápidamente datos claros y valiosos, mientras que las malas API abstraen demasiado, no permiten ninguna personalización o no son claras y, por lo tanto, son difíciles de usar.

La documentación de la API es otra capa de información abstracta para que un usuario desarrollador la descifre. Al combinar la documentación con una API, le proporciona a su usuario un códice y un camino hacia el éxito. La documentación de una buena API proporcionará significado, estructura, claridad y las expectativas adecuadas para ayudar a los desarrolladores a tener éxito.

Todo esto lleva a la API, un proceso en gran parte intangible, a algo que podemos contextualizar . Luego visualiza . Usamos la documentación y la interacción de la API para pintar una arquitectura en nuestras mentes que ayuda al consumidor desarrollador a comprender las relaciones entre objetos, clases y funciones.

La documentación es el contenido más importante que puede producir un proveedor de API . Hoy, recopilaremos las mejores prácticas fundamentales para la documentación de API, pero también ofreceremos nuevas perspectivas sobre la personalización del portal de desarrolladores, la empatía del usuario y los trucos de la interfaz de usuario para mejorar la experiencia general del desarrollador.

Documentación: clave para la experiencia integral del desarrollador

La mayoría de los arquitectos saben que una buena documentación es una combinación de demostraciones , guías de introducción y tutoriales . Tener una caja de arena es maravilloso al igual que copiar / pegar fragmentos para una variedad de idiomas . Lo que llevará esta experiencia al siguiente nivel es el desarrollo de viajes de usuarios de personas clave . Desempaquetemos eso un poco:

Piense en un desarrollador novato que descubre su API por primera vez. Tal vez lleguen con un poco de experiencia en programación, pero ciertamente no están familiarizados con los obstáculos de configurar una conexión API web. ¿Qué información necesitan? ¿Qué les dará suficiente contexto para aprender, pero también para ver el éxito temprano y encontrar entusiasmo por el producto?

Por el contrario, considere un desarrollador experimentado . Sueñan con Node.JS y desayunan API. Están interesados ​​en asimilar rápidamente los parámetros, comprender la funcionalidad única o aprender sugerencias avanzadas sobre cómo maximizar las ofertas de API. Estos casos de vanguardia abrumarían al nuevo desarrollador, pero crearían entusiasmo para alguien que quiera expandir sus horizontes.

Sin mencionar, piense en un desarrollador que consume su API en un entorno empresarial . Tienen fechas límite y, a menudo, tienen un solo problema que quieren resolver. Han pasado la creación de prototipos y necesitan empujar algo que no se rompa. ¿Cómo sería su experiencia?

Al desarrollar personas de usuario y enraizar su proceso en una base de empatía, su equipo podrá verificar el trabajo durante todo el proceso. Podría ser tan simple como: “¿Nuestro personaje principiante encontrará valioso a X? Si es así, agregue. Si no, considere editar o eliminar ” .

Al final del día, los equipos
Al final del día, cualquier forma en que los equipos puedan recordar que su trabajo busca mejorar la vida y el trabajo de un ser humano real realmente hace que incluso algo como la redacción técnica parezca mucho más importante e impactante.

Las personas son una excelente manera de comenzar con esa práctica.

Relacionado: lea nuestro artículo sobre desarrollo de personas de usuario de desarrollador

Asume cero

Al describir su tecnología en la copia del sitio, los proveedores de servicios a menudo usan un lenguaje detallado que es distanciador para algunos. Por ejemplo, cuando habla de "marcos", ¿qué quiere decir exactamente? El término puede tener diferentes connotaciones para los desarrolladores de otro equipo, o incluso entre colegas. La eliminación de suposiciones en las descripciones de los servicios obligará a su equipo a aclarar las terminologías y, por lo tanto, relacionar los conceptos con más claridad con los usuarios.

Ser explícito en su lenguaje y consciente de la jerga es una excelente manera de eliminar los prejuicios en la forma en que las personas entenderán su API. Una forma de lograrlo es crear un glosario . A medida que cambia la semántica y los significados de las palabras varían según el contexto, un glosario puede alinear a su equipo y mejorar su voz pública.

Métricas de documentación

Una herramienta para la documentación es el uso de mapas de calor y métricas de usuario muy simples Existen numerosas herramientas que ofrecen capacidades de mapas de calor, como CrazyEgg u Optimizely .

El uso de mapas de calor podría brindar una visión sin precedentes de las áreas problemáticas y los elementos de página infrautilizados. Estos análisis pueden revelar cuándo una página es demasiado larga (nadie se desplaza tan lejos), cuándo algo no funciona (caramba, mucha gente tiende a quedarse en este párrafo) e incluso qué tipos de usuarios estás atrayendo ( eh, hay mucha gente que se desplaza directamente al SDK de Ruby).

Al combinar un mapa de calor con algo tan simple como la extensión Page Analytics , puede obtener una imagen mucho más clara de dónde pueden estar los problemas.

Priorizar la estética

Sin duda, el éxito depende del contenido y la funcionalidad de una API, pero un gran diseño visual es fundamental para el proceso de navegación y descubrimiento. Estas son algunas de las mejores prácticas clave a seguir:

  • Muestre, no diga : Incluso la documentación más elocuente y claramente descrita palidecerá en comparación con algo que muestre valor inmediato.
  • Utilice una estética de calidad : los usuarios pueden estar mirando su documentación durante horas, así que considere cómo hacerla más agradable visualmente . Permita márgenes generosos, colores tranquilos pero contrastantes para promover la accesibilidad y un tipo de letra que enfatice la legibilidad.
  • Jerarquía de información : considere cómo dividir su información en bits fácilmente consumibles. Consolide descripciones en secciones y use subtítulos y diagramas para facilitar la legibilidad.

Prueba de experiencia en documentación

A menudo, los equipos de diseño o documentación de API se acercan mucho a su producto. Literalmente sueñan con eso (¿quizás tú también?). La atención a los detalles es excelente, pero también es necesario considerar la perspectiva de un extraño . Por lo tanto, si es posible, aplique métodos de investigación de usuarios y comentarios primarios; Las opiniones externas se pueden utilizar para mejorar la experiencia de la documentación.

Anteriormente, escribimos sobre qué preguntas hacer al acumular comentarios de los usuarios. Puede obtener información valiosa al observar a un nuevo usuario, escuchar su proceso de pensamiento y permitirle desarrollar ciertas acciones.

Incluso los pequeños comentarios realizados durante una sesión de investigación pueden cambiar por completo la forma en que el equipo piensa sobre su trabajo. Del mismo modo, si hay alguna pregunta sobre una nueva iteración, las pruebas A / B pueden ofrecer métricas para ayudar en la toma de decisiones. Afortunadamente, Google Analytics junto con Optimizely y CrazyEgg enumerados anteriormente ofrecen capacidades de prueba A / B.

Relacionado: Relaciones con los desarrolladores: cómo ofrecer un alcance de desarrolladores incomparable

Pensamientos finales

Dedicar tiempo a visualizar toda la experiencia de la documentación puede ayudar a convertir un documento técnico aburrido en una obra de arte. Como principal punto de contacto de una API, la documentación tiene un gran valor y debe tratarse como su forma de contenido más importante. Invertir más tiempo en la documentación de la API puede alinear a su equipo al lograr un consenso sobre el lenguaje, exponer áreas de debilidad o complejidad y, lo más importante, deleitar a sus usuarios.

Publicar un comentario

0 Comentarios