¿Busca optimizar su proceso de documentación de productos sin requerir experiencia técnica? Apidog ofrece una solución integral que permite a los gerentes de producto y a los equipos de operaciones colaborar sin problemas en la creación, gestión y publicación de documentación profesional. Con su interfaz intuitiva, funciones de colaboración en tiempo real y publicación sin mantenimiento, Apidog transforma la forma en que los equipos abordan los flujos de trabajo de documentación.
Cada producto necesita su propia documentación. Incluso si su producto es una aplicación orientada al consumidor con un diseño de interacción muy intuitivo y simple, seguirá habiendo áreas que necesiten más explicación, pero que añadirían complejidad si se presentaran directamente en la interfaz del producto. Por lo tanto, la gestión, el mantenimiento y la publicación de documentos son preocupaciones cruciales para cada producto.
Al crear documentación de productos, los equipos suelen utilizar herramientas de documentación listas para usar como Notion, o herramientas de gestión de contenido como Confluence y CMS, o generadores de documentación como Docusaurus y Gitbook. Sin embargo, estas soluciones a menudo encuentran los siguientes problemas:
- La documentación requiere codificación para escribir, con altos costos. Incluso después de escribir la documentación, la experiencia de lectura real a menudo no cumple con las expectativas;
- La documentación implica la colaboración de múltiples roles, lo que dificulta la gestión de versiones y la comunicación de sugerencias de optimización a otros;
- Publicar la documentación terminada en el entorno de producción es demasiado simple o demasiado complejo, lo que puede implicar procesos de ingeniería difíciles de manejar para colegas no técnicos, lo que lleva a errores.
El equipo de Apidog usó previamente Docusaurus para crear nuestra documentación. A medida que nuestra documentación continuaba iterando, también encontramos algunos de los problemas mencionados anteriormente. Después de resumir nuestras experiencias y lecciones aprendidas, desarrollamos soluciones y las integramos en Apidog. Ahora, la documentación del producto del equipo de Apidog ha sido completamente migrada a Apidog, con toda la creación y presentación manejadas por Apidog.
Compartiré nuestra práctica sobre cómo construir documentación de productos a través de Apidog. Antes de eso, si desea ver más de cerca los efectos específicos de la documentación del producto de Apidog, puede consultar la documentación de ayuda de Apidog; los comentarios son bienvenidos.
Antecedentes
Antes de presentar nuestra práctica, hay algunos contextos que quizás deban explicarse primero, para que todos puedan comprender mejor por qué hacemos las cosas de esta manera. La documentación del producto de nuestra empresa generalmente es creada en colaboración por colegas del departamento de producto y operaciones. El proceso principal es el siguiente:
El proceso anterior no requiere la participación de personal técnico; todas las operaciones relacionadas con la documentación del producto son completadas por colegas de estos dos departamentos. A continuación, explicaré cómo completar la tarea de crear documentación de productos a través de Apidog de acuerdo con este proceso.
Proceso Central
1. Crear una Rama de Sprint para la Gestión y Colaboración de Contenido
Después de que comienza una iteración de desarrollo, los colegas de operaciones crean una rama de iteración en Apidog para colocar todos los documentos que involucran cambios en la iteración actual dentro de esta rama para la colaboración, evitando el impacto directo en la rama principal.
Después de la creación, los gerentes de producto importan los documentos existentes que necesitan modificación en esta rama de iteración basándose en las características realmente actualizadas en la iteración, y crean nuevos documentos para nuevas características directamente en la rama de iteración. La operación aquí es completamente consistente con el uso de ramas de iteración para la documentación de API.
Debido a que hemos establecido protección en la rama principal, no se permiten cambios directos en el contenido del documento en la rama principal. Esto significa que no puede modificar manualmente el contenido de la documentación publicada que los usuarios pueden ver directamente, lo que hace que la documentación del producto sea más estable y reduce las situaciones en las que los cambios aleatorios conducen a que los usuarios vean contenido incorrecto.
2. Usar el Hermoso Editor Markdown para Escribir Cada Documento
Los gerentes de producto usarán Markdown para escribir la documentación que necesita ser actualizada en la iteración actual dentro de la rama de iteración. La funcionalidad Markdown de Apidog es muy potente, con varios componentes visuales en los que se puede hacer clic para insertar muchos estilos complejos con una barrera de entrada baja, lo que le permite escribir fácilmente artículos hermosos sin esfuerzo adicional.
Además de la inserción visual de estilo MD general, Apidog ha añadido las siguientes características especiales:
- Insertar APIs/documentos de proyecto, permitiendo que los documentos se vinculen formando cadenas de referencia con navegación fluida, proporcionando a los lectores una experiencia más fluida y resolviendo mejor las necesidades y problemas de los lectores; esta es una característica muy importante.
- Proporcionar funciones ricas de inserción de recursos, como iconos, bloques resaltados, tablas, pasos, Mermaid, videos, etc., para que no tenga que pasar tiempo buscando recursos usted mismo o aprendiendo la sintaxis de estilo MD para que los documentos se vean mejor.
3. Colegas de Producto/Operaciones Colaboran para Pulir Documentos
Después de que los gerentes de producto escriben la versión inicial de los documentos en la rama de iteración, para mejorar la calidad, claridad y utilidad para el usuario del documento, entregan los documentos a los colegas de operaciones para que los lean desde la perspectiva del usuario y proporcionen sugerencias de modificación para pulir.
Esto solía ser la parte más lenta y laboriosa, que requería la colaboración mutua de ambas partes, con una parte explicando sus ideas y proporcionando sugerencias de modificación específicas para ciertas partes; luego la otra parte recibía, entendía y realizaba los cambios. Durante el proceso de ida y vuelta, a menudo había varios problemas como malentendidos, cambios incorrectos y diferencias de contenido entre las versiones del documento, lo que conducía a una eficiencia muy baja.
Ahora, usando Apidog, ambas partes pueden realizar modificaciones directamente en los documentos, con notificaciones de mensajes en tiempo real enviadas a IM cuando se realizan cambios, lo que permite a otros ingresar inmediatamente al documento y ver fácilmente los cambios específicos, mejorando en gran medida la eficiencia de la colaboración. Aquí están los pasos específicos:
- Los gerentes de producto crean la versión inicial de los documentos. Después de que el personal de operaciones ve la notificación, leen el documento y realizan modificaciones directamente al contenido que desean cambiar dentro de este documento.
- Las modificaciones activan automáticamente notificaciones al guardar, enviando tarjetas de mensaje de cambio al grupo de IM preconfigurado. Después de que los miembros del grupo ven las tarjetas de mensaje de resumen de cambios, pueden hacer clic en el enlace de notificación para ingresar al documento relevante con un solo clic.
- A través del historial de modificaciones, compare las diferencias seleccionando la versión actual y la versión original para ver fácilmente las modificaciones de la otra parte y decidir cómo ajustar el documento. Puede optar por no aceptar sugerencias y restaurar la versión original, o aceptar modificaciones y mantener la última versión.
Los equipos de producto y operaciones repiten los pasos anteriores hasta que el contenido del documento se pule y se determina una versión que todos aprueban.
4. Preparación y Revisión Antes de la Publicación Oficial del Documento
Para garantizar que el contenido y las capturas de pantalla del producto en los documentos sean completamente consistentes con lo que los usuarios pueden acceder, recomendamos tomar capturas de pantalla en el entorno de producción del producto. Esto también permite verificar que las nuevas capacidades lanzadas en el entorno de producción funcionan correctamente. Después de que el personal de operaciones utiliza las nuevas funciones en línea y toma capturas de pantalla, las añaden a los artículos.
Operaciones confirma los documentos de contenido completados de esta iteración, los selecciona y envía una solicitud de MR para fusionar en la rama principal.
El gerente de operaciones u otros administradores de proyecto revisan el contenido del documento a publicar, confirman que es correcto y luego eligen fusionar en la rama principal.
Una vez completada la fusión, cuando los usuarios acceden a los documentos publicados, pueden ver el contenido más reciente fusionado en la rama principal.
Otras Ventajas
Además de las capacidades ya introducidas, Apidog también tiene las siguientes características en términos de publicación de documentos para ayudar a todos a construir sitios de documentación de productos que satisfagan mejor sus necesidades.
1. Establecer Estilos Generales del Sitio de Documentación que Coincidan con el Estilo del Producto/Empresa
Puede establecer el estilo general del sitio de documentación publicado, haciendo que el estilo de todo el sitio web esté más alineado con el tono de su empresa, y agregando más recursos relacionados y enlaces de contenido de la empresa para brindar a los usuarios una mejor experiencia.
La documentación de ayuda de Apidog ha establecido su propio logotipo y algunos enlaces de recursos relacionados con Apidog. La parte superior izquierda contiene el logotipo de la empresa, la parte superior derecha contiene varios enlaces de recursos relacionados con la empresa, y la documentación de API abierta que más interesa a los desarrolladores también está configurada dentro de la documentación del producto:
2. Experiencia de Publicación Sin Mantenimiento
En Apidog, solo necesita hacer clic en el botón "Publicar" en la función de publicación de documentación para publicar toda la documentación en internet con un solo clic para que sus usuarios la lean. Apidog proporciona oficialmente dominios para que todos los usen, ahorrando mucho trabajo de mantenimiento.
Por supuesto, si necesita que la documentación se parezca más al sitio web de su propia empresa, también ofrecemos la funcionalidad de dominio personalizado, lo que le permite usar el dominio de su propia empresa para acceder a la documentación.
También puede configurar fácilmente la búsqueda regular, la búsqueda de texto completo de Algolia, integrar GA, configurar redireccionamientos y otras capacidades avanzadas en los sitios de documentación de productos publicados con operaciones simples. Estas configuraciones no requieren que los operadores tengan suficientes capacidades de ingeniería; se pueden configurar fácilmente siguiendo la guía de la interfaz y la documentación de ayuda.
3. Múltiples Configuraciones Amigables para SEO
Apidog genera automáticamente Slugs razonables para los sitios de documentación publicados basándose en la configuración básica para permitir que los usuarios los accedan y compartan mejor.
Por supuesto, si tiene necesidades de SEO más avanzadas, también admite Slug personalizado, Meta Datos y varias otras configuraciones de contenido para cada documento individual.
Conclusión
Lo anterior es la práctica específica del uso de Apidog para el mantenimiento de la documentación del producto.
Además del contenido mencionado anteriormente, también podemos mantener la documentación de ayuda del producto, la documentación del desarrollador y la documentación de la API en un solo estilo y vincularlas todas, proporcionando una experiencia de usuario aún mejor. Si su situación actual es adecuada, le invitamos a probar esta práctica y recomendarla a otros colegas. Esperamos que esto pueda aportar algunas mejoras de eficiencia y calidad a su trabajo de creación de documentación de productos.