Cada servicio proporcionado por Selectel se puede administrar en su cuenta personal - panel de control . Muchos de nuestros productos también se pueden controlar mediante solicitudes de API. Las instrucciones del producto y la documentación de la API están disponibles en un único centro de ayuda .
La idea principal del centro de ayuda es brindar a nuestros clientes la oportunidad de encontrar respuestas de forma independiente a la mayoría de sus preguntas sobre los servicios de Selectel en cualquier momento que sea conveniente para ellos.
A continuación, hablaremos sobre cómo cambiamos el enfoque para preparar la documentación y actualizamos la apariencia de la base de conocimientos.
La implementación técnica de la base de conocimientos y su componente visual hace tres años cubrió por completo todas las necesidades de un libro de referencia con información. Pero en el pasado, la empresa no se ha detenido, sino que se ha desarrollado activamente, tanto lanzando nuevos servicios como desarrollando los existentes.
Hace aproximadamente un año, notamos que la ayuda en línea existente no cumplía con los requisitos de nuestros clientes:
- el menú de navegación creció como un árbol frutal que no conoce los cuidados de un jardinero;
- la búsqueda ha dejado de ser conveniente;
- el diseño visual se fue desactualizando gradualmente.
Anteriormente, la documentación para la API de nuestros productos no estaba disponible públicamente: algunos se publicaron en el panel de control my.selectel.ru , algunos se emitieron a pedido y algunos se describieron completamente en un formato de texto, que se mantuvo actualizado. muy problemático. Ahora conocimiento de la automatización de la infraestructura de TI y la interacción con el backend de los servicios de Selectel en la pestaña Documentación de API .
Una pequeña excursión al pasado
Hace diez o quince años, pocas de las empresas que producían software en Rusia podían presumir de tener ayuda en línea. Los manuales de operación fueron escritos en formato Word utilizando estilos en constante movimiento, tratando de aplicar los GOST creados en los años 70 del siglo XX a los requisitos modernos y en constante cambio.
El meme sigue siendo popular entre los escritores técnicos:
Hasta el día de hoy, hay empresas que ya pueden presumir de una interfaz de sitio conveniente, pero su documentación se mantiene al nivel de "instrucciones de descarga en formato pdf para 45 hojas".
En las grandes empresas, la base de conocimientos está fuertemente asociada con el soporte técnico. En un mundo esférico ideal en el vacío, el usuario debería poder encontrar de forma independiente el 80% de las respuestas a sus preguntas, sin ponerse en contacto con el soporte técnico.
Un portal con documentación no genera ningún beneficio claro, pero puede ahorrar tiempo de soporte técnico debido al script:
- El usuario solicitó el servicio.
- Enfrentado a momentos no obvios a la hora de montar.
- Quería contactar con el soporte técnico.
- Fui a la base de conocimientos y encontré la información que necesitaba.
- No me puse en contacto con el soporte técnico.
- ¡Lucro!)
A menudo existe la opinión de que la información de ayuda solo ayuda a los usuarios a comprender los servicios después de conectarse. Este fue probablemente el caso en los días en que se publicaban libros impresos con información sobre cómo trabajar en Windows. Pero ahora es igualmente importante mostrar abiertamente a los usuarios potenciales cómo funciona el servicio antes de la compra.
La mayoría de las empresas de software desarrollan API tanto para uso interno como para clientes en algún momento. Las empresas comparten un conjunto de entradas al lanzar API públicas para permitir a los clientes integrar sus servicios con los productos de la empresa.
Se pueden automatizar muchas tareas personalizadas, incluido el uso de fragmentos de código listos para usar como constructor para crear la infraestructura más fácil de usar. Pero los fragmentos de código sin explicaciones de qué es, qué hace y cómo usarlo son de poca utilidad; no se utilizará la fuerza bruta para averiguar qué son los métodos y qué datos esperan para ingresar.
- ¿Qué se debe hacer para que la API pública sea agradable de usar?Como documentación para la API, generalmente dan un ejemplo mínimo de interacción, que describe los métodos (también llamados puntos finales) y proporciona respuestas del servicio. Por ejemplo, con la API de Kubernetes, puede automatizar el trabajo con clústeres y nodos en Managed Kubernetes .
- ¡Adjunta documentación!
¿Qué tareas teníamos por delante?
Nuestra solución visual dejó de facilitar la búsqueda de los artículos que necesitábamos y el menú existente se convirtió en una "hoja" ilegible. La documentación ilegible es tan mala como los textos irrelevantes. La gente está acostumbrada a leer materiales bien estructurados. Blogs, redes sociales, medios: todo el contenido se presenta no solo hermoso, sino también fácil de leer y agradable a la vista. Actualmente, los requisitos de UX y UI no se pueden ignorar, especialmente para una variedad tan grande de textos.
Con el desarrollo de tecnologías para el diseño visual de sitios, notamos que la apariencia de nuestra base de conocimientos está desactualizada. El mero uso de anclas y listas en los artículos de KB no ayudó. Fue necesario revisar toda la estructura de la documentación y el buscador.
Problemas comunes con la documentación
Generalmente ausente o nadie sabe de su existencia La
instrucción que no se puede encontrar no es mejor que la instrucción que no existe.
Resolvimos este problema de la siguiente manera: comenzamos a agregar enlaces a artículos útiles en nuestra lista de correo mensual, agregamos transiciones en las páginas de productos del sitio y también configuramos notificaciones para todos los empleados interesados de la empresa a través de un canal especial en el mensajero corporativo.
Desactualizado y no actualizado a tiempo
El proceso de documentación no está integrado en el desarrollo del producto, la documentación se realiza sobre una base sobrante.
En nuestro caso, el gerente de producto también tiene la tarea de documentar esta nueva funcionalidad mientras trabaja en la nueva funcionalidad.
La documentación es compleja y está mal organizada, es más fácil preguntar al soporte técnico cómo solucionar el problema
, no tiene sentido escribir documentación por el bien de la documentación, debe ser fácilmente accesible. Cuantas más opciones tenga para encontrar un documento, mejor.
Revisamos completamente el diseño de las secciones de nuestra base de conocimiento, en algunos casos las plantillas universales no funcionaron, por lo que tuvimos que interactuar activamente con todas las partes interesadas, ya sea un gerente de producto, soporte técnico o un equipo de desarrollo front-end.
Mover la documentación de la API al espacio público
Uno de los problemas con el uso de la documentación API generada en OpenAPI, Swagger o alguna otra herramienta de generación es la compleja integración con el resto del sitio. Es necesario que los usuarios tengan fácil acceso a todas las instrucciones y artículos; es inconveniente si los puntos finales se muestran en una vista y las descripciones de texto de los mismos procesos se muestran en otra página.
Mantener una sola imagen visual
Al crear un solo centro de ayuda, necesitábamos mantener una visualización consistente de instrucciones y especificaciones, usando un montón de "git + markdown + swagger".
Como funciona ahora
Implementación técnica
La base de conocimientos se creó originalmente en torno a una combinación de Confluence y un generador de páginas estáticas.
Abandonamos Confluence y pasamos a Documentation-as-Code. Ahora, todo el código fuente de la base de conocimientos se compone en formato Markdown y se almacena en el sistema de almacenamiento de la versión Git. Se crea un sitio de base de conocimientos a partir del repositorio utilizando Hugo Static Site Generator.
El sitio se genera a partir de los archivos contenidos en la rama maestra del repositorio de Git. Los datos se pueden actualizar solo a través de una solicitud de extracción, que le permite verificar todas las secciones nuevas de la documentación antes de que se publiquen en el dominio público. Este sistema también facilita el enfoque para realizar ediciones: los empleados de la empresa siempre pueden crear una sucursal y agregarle todos los cambios necesarios.
Más sobre la documentación como código
El principio de "documentación como código" implica el uso de las mismas herramientas para escribir documentación que para crear código:
- lenguajes de marcado de texto;
- sistemas de control de versiones;
- revisión de código.
El objetivo principal de este enfoque es crear las condiciones para el trabajo conjunto de todo el equipo en el resultado final: una base de conocimientos completa e instrucciones para utilizar los servicios de productos individuales.
Trabajar con archivos swagger
Los desarrolladores de productos de Selectel crean una API y cargan comentarios al código en formato swagger; este es un archivo de texto en formato * .yaml que se puede usar como código. Cuando se actualiza la API, el archivo swagger también se actualiza, lo que facilita la actualización de la documentación.
La siguiente solución técnica se utiliza para la documentación de API:
- repositorio git con archivos de especificación swagger en formato * .yaml, agrupados por producto;
- repositorio git con traducciones de especificaciones swagger en formato * .json;
- repositorio git con archivos en formato * .md;
- los archivos en formato * .md contienen descripciones de texto y están envueltos en etiquetas especiales de descripción de punto final, que se extraen del repositorio de git con archivos en formato * .json;
- Generador de sitios estáticos Hugo.
Además de la estructura del repositorio, se desarrollaron reglas para trabajar con él:
- se ha preparado una guía de estilo: una lista de verificación para archivos swagger, que los desarrolladores verifican cuando actualizan las especificaciones de la API;
- La rama maestra del repositorio git con archivos en formato * .md refleja el estado de las especificaciones actuales y está de facto en producción;
- La solicitud de extracción a la rama maestra se lleva a cabo cuando las actualizaciones se lanzan a producción.
Componente visual
El primer paso fue revisar la navegación y crear reglas según las cuales se formarían las secciones de la base de conocimientos. Junto con los diseñadores de UX, preparamos una arquitectura de información. La estructura debe ser lo más transparente posible para que el lector no piense: "¿Dónde puedes encontrar este artículo?" Para resumir, hay dos enfoques:
- Desde la interfaz. El contenido duplica las secciones del panel (por separado para los servicios). Este fue el caso en la versión anterior de la base de conocimientos.
- De las tareas. Los títulos de artículos y secciones reflejan las tareas de los usuarios.
Para simplificar la estructura, utilizamos una combinación de estos dos enfoques. Incluso en las versiones más nuevas del panel de control con una UX y UI bien pensadas, es necesario explicar al menos los términos, ya que nuestros productos son técnicamente complejos y los usuarios son muy diferentes.
Además de actualizar la tabla de contenido, hemos mejorado la búsqueda y las rutas de navegación. "Breadcrumbs" es la ruta del usuario a la página actual con la capacidad de volver a cualquier nivel. En la versión anterior de la base de conocimientos, era imposible ingresar a la tabla de contenido y era inconveniente, por lo que en la nueva versión lo hemos arreglado.
Cada empresa elabora documentación API de acuerdo con su propia visión de estilo, estructura y sentido de belleza. Si abrimos 4-5 API públicas de diferentes empresas, entonces, por supuesto, podremos captar algunos puntos en común: estructura, ejemplos de código voluminosos y resaltado de sintaxis, páginas largas. Sin embargo, todos los ejemplos tendrán características especiales. Por ejemplo, la localización de las descripciones de los puntos finales es poco común, mientras que la estructura de las descripciones de los puntos finales suele ser la misma.
Varias recomendaciones para estructurar la documentación de la API:
Agrupar puntos finales
Además de proporcionar información para cada punto final, si hay muchos puntos finales, es recomendable agruparlos. La larga lista continua de puntos finales dificulta la navegación.
Descripción separada de métodos
Cuando se utilizan los métodos GET / POST al mismo tiempo, solo se debe describir un método en una línea.
Es decir, la primera línea en este caso es la descripción de GET, la segunda línea es la descripción de POST, por lo que puede evitar confusiones.
Automatización de la realización de cambios
Simplifica la realización de cambios sin reformatear manualmente cada sección - en nuestro caso, solo traducimos el texto del archivo swagger, sin tocar el marcado gracias a la automatización de este proceso que han configurado nuestros especialistas en devops.
Resaltado de sintaxis A los
desarrolladores les encantan los ejemplos de código en el mundo, ningún desarrollador se quejará de que hay demasiados ejemplos; reducen en gran medida el tiempo de inmersión en el producto.
Trabajar con fragmentos de código es mucho más conveniente cuando los diferentes elementos se colorean apropiadamente según el lenguaje de programación.
Dado que el resaltado de código listo para usar estaba disponible solo para fondos oscuros, el desarrollador de frontend modificó esta solución usando highlight.js para nuestro estilo corporativo.
En lugar de una conclusión
La base de conocimientos actualizada está disponible para los usuarios desde marzo y la documentación de la API está disponible desde principios de agosto.
“- Con nosotros, cuando corres durante mucho tiempo, ciertamente te encuentras en otro lugar.Lo que ya hemos hecho es solo un paso más hacia la mejora de la base de conocimientos. Agregaremos gradualmente nuevas instrucciones y documentación a las API de nuestros otros servicios.
"Bueno, aquí, ya sabes, tienes que correr tan rápido para permanecer en el mismo lugar, y para llegar a otro lugar, necesitas correr el doble de rápido".
(Lewis Carroll "Alicia a través del espejo")