El pasado
Soy el jefe de producto del producto SaaS, Apidog. Lleva en línea más de dos años y ofrece una gran cantidad de funciones relacionadas con el desarrollo, las pruebas y la documentación de API. Esto también significa que requiere un conjunto completo de documentos de ayuda.
Anteriormente, utilizábamos la herramienta Docusaurus para mantener nuestros documentos de ayuda. Es una herramienta de documentación basada en Markdown con amplias funciones de personalización.
Sin embargo, el uso de esta herramienta fue un desafío para nosotros.
En primer lugar, es una herramienta basada en código, que puede ser fácil de usar para los desarrolladores, pero para un jefe de producto, modificar cualquier cosa significaba extraer código y realizar una solicitud de combinación. Pasé mucho tiempo tratando de entender la lógica de Git. Esto también nos llevó a menudo a descuidar pequeñas optimizaciones en la documentación porque era simplemente demasiado engorroso.
En segundo lugar, se basaba completamente en Markdown, que tiene un soporte muy limitado para el estilo más allá del texto plano. Durante mucho tiempo, nuestra documentación de ayuda careció de una página de inicio decente.
En tercer lugar, Docusaurus tenía un soporte deficiente para varios idiomas. Nuestra herramienta en sí ofrece varios idiomas (inglés, japonés, y más por venir) y proporciona documentación de ayuda en inglés y japonés. Sin embargo, en Docusaurus, estos solo podían implementarse como dos proyectos completamente separados. Además, debido a que la ayuda en japonés era mantenida por nuestro equipo de operaciones japonés, a menudo había actualizaciones en la documentación en inglés que no se sincronizaban con el japonés.
A mediados de 2024, de repente nos dimos cuenta de que Apidog en sí es una herramienta de documentación (aunque principalmente una herramienta de documentación de API). ¿Sería una buena idea utilizar Apidog directamente para mantener su documentación de ayuda?
Experimentación
De hecho, Apidog es una herramienta de documentación de API bastante potente. Admite el diseño visual de API, la combinación de Markdown y documentos de API, la navegación personalizada y los dominios personalizados. Muchas empresas lo utilizan para mantener su documentación de API.
Pero usar Apidog por completo para mantener la documentación de ayuda fue un nuevo experimento.
Pensé que debería intentarlo. Si pudiera crear un hermoso ejemplo, tal vez las empresas que usan Apidog para la documentación de API también podrían usarlo para su documentación de ayuda.
Comencé este experimento alrededor de Septemper 2024.
Apidog admite directamente Markdown, por lo que el primer paso fue simple: migrar la documentación mantenida originalmente en Docusaurus.
Una gran característica es que Apidog admite una sintaxis mucho más potente que Markdown nativo. Por ejemplo, incluye efectos como Card, Image Background, Step, Highlight y más.
Pasé mucho tiempo transformando los documentos de ayuda de Markdown existentes, haciendo que su estilo fuera más hermoso y moderno.
También creé rápidamente una página de inicio del documento, remediando un arrepentimiento anterior.
Sin embargo, durante este proceso, también descubrí algunas deficiencias en las capacidades de documentación de Apidog.
Por ejemplo, no admite slugs de documentos y utiliza números como sufijos de URL en su lugar, lo que obviamente no es bueno para el SEO.
Además, solo admite la búsqueda dentro de los títulos de los documentos, no del contenido, lo que claramente es inadecuado para la documentación de ayuda.
Afortunadamente, soy el jefe de producto de este producto. Para mí, estas son dos demandas de alta prioridad en el backlog.
Esto fue en octubre de 2024.
Nuevas funciones
El 25 de octubre, lanzamos la versión 2.6.26. Esta versión admitía Slugs personalizados y la generación automática de Slug basada en los nombres de los documentos.
El 15 de noviembre, la versión 2.6.31 admitía Algolia DocSearch, lo que permitía búsquedas de documentos de texto completo.
Durante este período, agregamos un módulo de soporte a los documentos de ayuda originales, con cada página representando una pregunta frecuente de los usuarios.
Al mismo tiempo, utilizamos la función de versión de API para crear documentos de ayuda en japonés. Admitimos la publicación de varias versiones de documentos, y los lectores pueden elegir qué versión leer en la página. Puede considerar cada versión como una revisión o como un idioma diferente.
Así que ahora, puedo cambiar directamente entre inglés/japonés en la documentación de ayuda.
Ahora, tengo un conjunto de documentos de ayuda hermosos y potentes mantenidos utilizando nuestro propio producto. Lo equipé con dominios y navegación personalizados, y se ve perfecto.
La mejor parte es que ya no es necesario un pull y MR cada vez, y cada jefe de producto puede mantener directamente la documentación de ayuda para sus funciones recién lanzadas. La eficiencia y la eficacia han aumentado significativamente en comparación con antes.
Nuestro equipo de soporte técnico también puede mantener directamente las preguntas frecuentes de los correos electrónicos o Discord en la sección de soporte, simplemente usando Apidog.
Todas las imágenes se pueden cargar directamente al espacio de Apidog sin necesidad de herramientas especiales para cargarlas en una CDN.
A principios de diciembre, nuestra nueva versión de los documentos de ayuda de Apidog se puso en marcha. Puede leerlo en https://docs.apidog.com.
Ahora puedo decir con orgullo que Apidog es una excelente herramienta para mantener la documentación de ayuda y la documentación de API. La mayoría de las funciones anteriores son gratuitas.
Usar Apidog para mantener nuestra documentación de ayuda fue la mejor decisión que tomé en la segunda mitad de 2024.
