La forma de redactar documentación de API en Excel o PDF y compartirla por correo es demasiado familiar.
Cuando surge un problema, se contacta a la persona responsable y se buscan correos antiguos para confirmar qué versión del documento tiene el cliente. Se vuelven a explicar los cambios, se envía el documento corregido y luego se verifica otra vez si se reflejó correctamente.
Hemos repetido este proceso tantas veces que terminamos pensando que es trabajo que realmente debía hacerse.
Pero el problema no termina con un solo documento incorrecto.
Cada vez que cambia una API, se van acumulando nuevos archivos y correos, excepciones por cliente y recuerdos de las personas responsables. Al principio es una pequeña incomodidad, pero con el tiempo se vuelve difícil confirmar qué documento es la referencia, y también aumentan las personas y el tiempo necesarios para resolver problemas.
Si un cliente desarrolla usando el formato de solicitud de una versión anterior, se producen errores de integración y retrabajo. Si los campos obligatorios o el método de autenticación se comunican de forma distinta, el calendario de desarrollo se retrasa y, si se trata de una API ya en operación, también puede derivar en errores de datos o incidentes.
Solo después de que ocurre el problema se descubre que el equipo interno de desarrollo y el cliente estaban viendo documentos diferentes.
A partir de ese momento, los desarrolladores detienen el trabajo que estaban haciendo y revisan la causa. El equipo de operaciones busca documentos anteriores y el historial de comunicación, y el cliente vuelve a verificar su implementación y la especificación que recibió. Una sola discrepancia documental detiene simultáneamente el trabajo de varias personas.
Aun así, la mayoría de los problemas se resuelven discretamente por teléfono, correo y mensajería.
Alguien vuelve a enviar el archivo corregido, alguien le explica la situación al cliente y los desarrolladores agregan con urgencia un manejo de excepciones. El problema inmediato se resuelve, pero no queda en la organización por qué ocurrió, qué clientes se vieron afectados ni qué se cambió para evitar que se repita.
El tiempo usado en este proceso es tiempo que originalmente debería haberse dedicado al desarrollo y a la mejora del producto.
El problema más grande es que todo este proceso depende de la experiencia y la memoria de una persona específica, y de su bandeja de correo. Si esa persona se ausenta o deja la empresa, la organización debe reconstruir el trabajo revisando correos y registros de mensajería.
La documentación de API sin gestionar no desaparece. Permanece dentro y fuera de la organización, convirtiéndose en deuda documental invisible.
Quizá no estamos resolviendo el problema, sino que nos acostumbramos a contenerlo con tiempo humano cada vez que aparece.
Tras haber vivido estos problemas en el trabajo real, creé SpecBridge.
SpecBridge no es simplemente una herramienta para escribir documentación de API. Es una herramienta de operación de documentación de API que permite revisar los cambios de los documentos y distribuir solo las versiones aprobadas a clientes y socios externos.
No busca reemplazar Swagger existente; se enfoca en importar Swagger/OpenAPI y Postman Collection, y gestionar los problemas que surgen durante el proceso de entrega hacia el exterior.
- Comparación de diferencias entre la versión actualmente distribuida y la versión modificada
- Revisión y aprobación de cambios
- Separación entre borradores y la versión distribuida que ven los clientes
- Gestión del alcance de publicación de documentos por cliente
- Configuración de contraseña y fecha de expiración para enlaces públicos
- Entrega del documento aprobado más reciente desde el mismo enlace
Sin necesidad de enviar un archivo nuevo al cliente cada vez, se pueden volver a distribuir en el enlace existente solo los documentos que ya pasaron la revisión interna.
Los desarrolladores pueden reducir el trabajo repetitivo de buscar documentos y reenviarlos, y la organización puede gestionar la documentación de API con historiales de cambios registrados y criterios de distribución, no con la memoria de una persona específica.
Actualmente buscamos socios que usen SpecBridge en la operación real de documentación de API y nos den feedback sincero.
Si tu equipo gestiona documentación de API en Excel o PDF, o vuelve a enviar documentos a los clientes cada vez que cambia una API, nos gustaría validar juntos empezando por uno de los documentos que usan actualmente.
Más que elogios por funciones bien hechas, queremos escuchar opiniones sinceras sobre lo que resulta incómodo en la operación real, los procedimientos innecesarios y las funciones que faltan.
Aún no hay comentarios.