Header Ads Widget

Ticker

6/recent/ticker-posts

Tres pasos clave para escalar un portal para desarrolladores

 


La documentación de la API de calidad es sin duda el elemento vital de la experiencia del desarrollador. La mayoría de las herramientas de autoservicio requieren tutoriales detallados, incluso para un uso sencillo. Sabemos que la adopción por parte de los desarrolladores impulsa el éxito de numerosas API, así que ¿por qué no hacerles la vida lo más fácil posible?

Kristof Van Tomme , cofundador y CEO de Pronovix , cree que podemos crear portales de desarrolladores fáciles de usar siguiendo las mejores prácticas clave. Estos se enfocan en mejorar la incorporación, el acceso a los recursos y la facilidad general del proyecto. También debemos escalar nuestros documentos de manera efectiva a medida que crece nuestra biblioteca de API disponibles. Esta tarea puede resultar bastante abrumadora. Los mayores partidarios de su tecnología merecen las mejores experiencias que pueda brindarles.

Afortunadamente, Kristof nos ha brindado tres soluciones principales para escalar portales de desarrolladores. Hemos resumido sus recomendaciones a continuación, basándonos en los comentarios que ha recopilado de empresas y desarrolladores.

Vea a Kristof Van Tomme discutir lo que debe considerar al crear un portal para desarrolladores:

1.Haga que su contenido sea visible

La capacidad de descubrimiento se suele pasar por alto al escalar portales; sin embargo,  hacer que las API sean detectables es muy importante para crear productos de autoservicio. Las empresas ofrecen un número creciente de servicios a medida que se expanden y crean numerosas API para otorgar acceso a terceros a ellas. Muchos problemas se reducen a la semántica; muchas API suelen tener nombres poco conocidos con poco valor contextual. En consecuencia, es difícil para los desarrolladores externos comprender qué API sirven para qué propósitos.

Las búsquedas de palabras clave son particularmente útiles cuando se sumerge en un territorio desconocido. Como desarrolladores y seres humanos, nos gusta rastrear elementos usando terminología que lógicamente resuena con nosotros. La eficiencia se desploma cuando los títulos de API consisten en secuencias alfanuméricas aleatorias. Esto deja a los desarrolladores en la oscuridad. La creación de un portal es un ejercicio de diseño de UI / UX; aunque la información clave puede estar a solo unos clics de distancia, el descubrimiento puede ser sorprendentemente difícil.

Podemos explorar una breve lista de recursos con bastante rapidez. Sin embargo, se vuelve exponencialmente más tedioso analizar cientos de documentos cuando la búsqueda no es confiable. En consecuencia, el crecimiento de las bibliotecas puede convertirse en la peor pesadilla de un desarrollador. La creación y ubicación adecuadas de metadatos son clave, pero su portal también requiere una jerarquía organizativa clara.

Lea también: Guía definitiva para más de 30 soluciones de documentación de API

Crea una estructura organizada

Kristof dice que de este enfoque surge una estructura de contenido en capas. Tendrá sus API empaquetadas con información crucial, como archivos OAS , Markdown y JSON. Estos archivos JSON contendrán metadatos clave para la búsqueda.

El diseño en capas de Kristof, que conduce progresivamente a los desarrolladores a información más granular.

Generalmente, esta capa de contenedor de API ( verde, ver arriba ) es el nivel más bajo de su documentación. El nivel inmediatamente superior a esa base incluye guías de bloques de construcción y materiales instructivos. Se accede a estas guías a través de páginas de destino, que en última instancia provienen de la página de destino principal de su portal para desarrolladores. Por lo tanto, moverse a través de un portal bien organizado es similar a navegar por un sitio web. Empieza amplia y luego reduce su enfoque.

También elogia el enfoque por facetas de DHL, que muestra todas las API a la vez y permite el filtrado:

DHL proporciona a los desarrolladores una interfaz ordenada y de fácil navegación.

Lo mejor de todo es que este diseño emula casi todas las páginas de búsqueda de productos que encontramos en línea. Esa familiaridad es sólida e innata da a los usuarios una idea de dónde ir. Esta combinación de claridad y eficiencia permite a sus desarrolladores trabajar de manera más inteligente.

Podemos resolver los problemas de descubrimiento y búsqueda con un poco de esfuerzo. Sin embargo, este es el gremlin del desarrollo "más fácil" de tratar. La estructura del contenido es una cosa, pero asegurar los recursos y la financiación es aún más desafiante.

Relacionado: Cómo los malos portales para desarrolladores acaban con las API

2. Demuestre un valor comercial claro

Los dueños de negocios a menudo lidian con sus resultados finales. Su portal de desarrollador transmite tanto cómo usar sus API como qué las hace valiosas. Esto, a su vez, atrae a los desarrolladores al redil, legitimando gradualmente sus servicios y promoviendo el éxito de la empresa. Muchos equipos de productos no se dan cuenta de lo fundamental que es la experiencia del desarrollador para obtener ingresos.

Estos portales para desarrolladores son una inversión continua. Se necesita tiempo y dinero para producir contenido nuevo, y la actualización de sistemas clave requiere esfuerzo. Es posible que tenga, digamos, siete API en su biblioteca. Su contenido evolucionará y se multiplicará a medida que estas API ganen funcionalidad adicional. Cualquier cambio de API debe reflejarse en su documentación a medida que ocurren. Si su biblioteca se expande, su portal también lo hará. Esto requiere inversiones de diversas formas.

Muchas partes interesadas también contribuirán al éxito de su portal. No todo el contenido incluido será técnico. Si bien es importante incluir los entresijos técnicos, Kristof nos insta a considerar también a las " personas de negocios ". Sus API pueden ser dinamita, pero como propietario de un producto o comercializador, debe transmitir por qué estas API son adecuadas. Es por eso que deberíamos ver propuestas de valor entremezcladas con fragmentos de código.

Las mejoras del portal deben ser proactivas y reactivas

Van Tomme sostiene que su portal no debería ser solo una plataforma de producto, debería ser una plataforma de asequibilidad . Antes de llegar allí, debemos considerar cómo está cambiando la empresa. Kristof sostiene que las empresas son más flexibles y de mente abierta mientras crecen. Estas mismas empresas se vuelven resistentes al cambio a medida que maduran.

Esa falta de adaptabilidad es muy necesaria mientras su negocio se amplía. Las empresas deben adoptar la complejidad y el pensamiento sistémico. Cuando las empresas crecen, agregan servicios y herramientas a su repertorio. Los equipos técnicos deben documentar estos cambios en consecuencia. Si su portal de desarrolladores existente no puede soportar este crecimiento, es hora de una renovación. Kristof afirma que nuestros portales de documentación deben escalar de manera efectiva junto con sus respectivos negocios.

La complejidad no es algo malo. Se basa en cuatro cosas: interconexión, interdependencia, diversidad y adaptabilidad. Van Tomme plantea la hipótesis de que los portales para desarrolladores pueden ayudar a impulsar la complejidad y las cadenas de valor entre piezas de información, empresas y clientes. Estos portales son herramientas que "pueden ayudarlo a convertir su empresa en un sistema adaptativo complejo (CAS)".

Consulte también: 5 ejemplos de excelente documentación de API

3. Considere la posibilidad de combinar su backend con una GUI

Los enfoques de autoría difieren de un portal de desarrollo (o equipo) a otro. Por ejemplo, los creadores de contenido pueden favorecer un enfoque centrado en la GUI tomado de los sistemas de gestión de contenido (CMS). Otros prefieren los repositorios y los generadores de sitios estáticos (más Git, Terminal, Bash, etc.). Estos varían mucho en términos de granularidad y conocimientos técnicos requeridos. El mejor enfoque combina CMS y "documentos como código" en un solo programa, lo que a Van Tomme le resulta beneficioso.

¿Qué incluyen estos documentos en un entorno de codificación? Los desarrolladores pueden utilizar Swagger.io , OpenAPI Specification (OAS) , Markdown y varios atributos para crear documentación. También hay formatos de datos como JSON y YAML. Estas herramientas brindan a los desarrolladores numerosas formas de organizar y publicar contenido.

Hay una curva de aprendizaje asociada con estas tecnologías, especialmente para personas sin conocimientos técnicos. Estos autores preferirán un CMS . Esa flexibilidad le permite involucrar a varios miembros del equipo. Las plantillas automatizadas extraen contenido generado por CMS, lo que determina qué desarrolladores necesitan ver qué contenido en función de las configuraciones de control de acceso basado en roles (RBAC).

En resumen, su portal de desarrollador debe ofrecer contenido relevante de manera única para cada usuario. El CMS también es la salida perfecta para realizar cambios de contenido, que es donde fallan las herramientas estáticas.

Pensamientos finales

Esto puede parecer confuso, pero la premisa general es bastante sencilla. Su portal para desarrolladores ayuda a fomentar el crecimiento de una comunidad de desarrollo en torno a sus API. Para brindar excelentes experiencias a los desarrolladores, su portal debe evolucionar en respuesta a nueva documentación, negocios y un clima de desarrollo cambiante. Los portales para desarrolladores ayudarán a su empresa a seguir siendo relevante a los ojos de sus clientes.

Los portales para desarrolladores suelen ser los héroes olvidados de su empresa y sus API. Merecen atención como si fueran un organismo que vive y respira. La experiencia del desarrollador a menudo se pasa por alto; Van Tomme sostiene que ajustar estas minas de oro de información pagará inmensos dividendos para todos los involucrados. Esta información, una vez compartida, es esencial para crear nuevos mercados para sus API.

Publicar un comentario

0 Comentarios