La documentación del software es simplemente un conjunto de artículos. Pero incluso ellos pueden frustrar. Primero, pasas tiempo buscando la instrucción que necesitas. Luego, intentas descifrar un texto poco claro. Haces lo que se indica, pero el problema persiste. Buscas otro artículo, te pones nervioso... Después de una hora, te rindes y te vas. Así es como funciona una mala documentación. Qué la hace así, y cómo solucionarlo, léelo a continuación.
En nuestra antigua documentación había muchos defectos. Hace casi un año estamos trabajando en su revisión para que el escenario descrito anteriormente no afecte a nuestros clientes. Mira, y .
Problema 1. Artículos confusos y mal redactados
Si no se puede entender la documentación, ¿cuál es su sentido? Pero nadie escribe artículos confusos intencionadamente. Surgen cuando el autor no considera a la audiencia y el objetivo, da palabrería y no revisa el texto en busca de errores.
- La audiencia. Antes de escribir un artículo, hay que pensar en el nivel de preparación del lector. Es lógico que en un artículo para principiantes no se deben omitir los pasos básicos ni dejar términos técnicos sin explicación, mientras que en un artículo sobre una función rara, necesaria solo para profesionales, se debe explicar el significado de la palabra PHP.
- El objetivo. Otra cosa que es mejor considerar de antemano. El autor debe establecer un objetivo claro, definir la acción útil del artículo, decidir qué hará el lector después de leerlo. Si esto no se hace, resultará ser una descripción por describir.
- Palabrería y errores. Mucha información innecesaria y burocratismos, errores y erratas obstaculizan la percepción. Incluso si el lector no es un defensor del idioma, la falta de cuidado en el texto puede alejarlo.
Toma en cuenta los consejos anteriores, y los artículos serán más comprensibles - garantizado. Para hacerlo aún mejor, adopta nuestras .
Problema 2. Los artículos no responden a todas las preguntas
Es malo cuando la documentación no sigue el desarrollo, no responde a preguntas reales, y los errores no se corrigen durante años. Estos son problemas no tanto del autor, sino de la organización de los procesos dentro de la empresa.
La documentación no sigue el desarrollo
La función ya está en lanzamiento, el equipo de marketing planea cubrirla, y resulta que aún no hay un nuevo artículo o traducción en la documentación. Debido a esto, incluso hemos tenido que posponer el lanzamiento. Se puede pedir a todos que transmitan las tareas a los escritores técnicos a tiempo, pero eso no funcionará. Si no se automatiza el proceso, la situación seguirá repitiéndose.
Hemos realizado cambios en YouTrack. La tarea de redactar un artículo sobre la nueva función se asigna al escritor técnico en el mismo momento en que comienza la prueba de la funcionalidad. En ese momento, el equipo de marketing también se entera para prepararse para la promoción. Las notificaciones también llegan al mensajero corporativo Mattermost, así que es imposible perderse las noticias de los desarrolladores.
La documentación no refleja las solicitudes de los usuarios.
Estamos acostumbrados a trabajar de esta manera: la función salió, nosotros la comunicamos. Describimos cómo activarla, desactivarla, hacer configuraciones finas. Pero, ¿qué pasa si el cliente utiliza nuestro software de una manera que no anticipamos? ¿O tiene errores que no se nos habían ocurrido?
Para que la documentación sea lo más completa posible, recomendamos analizar las consultas en el soporte, preguntas en foros temáticos y búsquedas en los motores de búsqueda. Los temas más populares deben ser enviados a los escritores técnicos para que complementen los artículos existentes o escriban nuevos.
La documentación no se está mejorando.
Es difícil hacerlo perfecto de inmediato, siempre habrá errores. Se puede esperar comentarios de los clientes, pero es poco probable que informen sobre cada errata, inexactitud, artículo confuso o no encontrado. Además de los clientes, los empleados también leen la documentación, por lo que ven los mismos errores. ¡Esto se puede aprovechar! Solo hay que crear condiciones en las que sea fácil informar sobre un problema.
Tenemos un grupo en el portal interno donde los empleados dejan comentarios, sugerencias e ideas sobre la documentación. ¿El soporte necesita un artículo, pero no hay ninguno? ¿Un probador notó una inexactitud? ¿Un socio se quejó a los gerentes de desarrollo sobre errores? ¡Todo se dirige a este grupo! Los escritores técnicos corrigen algunas cosas de inmediato, algunas las transfieren a YouTrack, y otras las toman para reflexionar. Para que el tema no se olvide, de vez en cuando recordamos la existencia del grupo y la importancia de los comentarios.
Problema 3. El artículo que necesitas se tarda mucho en encontrar.
Un artículo que no se puede encontrar no es mejor que un artículo que no existe. El lema de una buena documentación debe ser la frase "Fácil de buscar, fácil de encontrar". ¿Cómo lograrlo?
Organizar la estructura y definir el principio de selección de temas. La estructura debe ser lo más clara posible, para que el lector no se pregunte "¿Dónde puedo encontrar este artículo?". En resumen, hay dos enfoques: desde la interfaz y desde las tareas.
- Desde la interfaz. El contenido duplica las secciones del panel. Así era en la antigua documentación de ISPsystem.
- Desde las tareas. Los títulos de los artículos y secciones reflejan las tareas de los usuarios; en los encabezados casi siempre hay verbos y respuestas a la pregunta "cómo hacer". Ahora estamos cambiando a este formato.
Cualquiera que sea el enfoque que elija, asegúrese de que el tema corresponda a las consultas de los usuarios y esté cubierto de manera que el usuario resuelva su pregunta de manera clara.
Establecer una búsqueda centralizada. En un mundo ideal, la búsqueda debería funcionar incluso cuando cometes un error tipográfico o te confundes de idioma. Nuestra búsqueda en Confluence aún no puede ofrecer esto. Si tiene muchos productos y la documentación es general, adapte la búsqueda a la página en la que se encuentra el usuario. En nuestro caso, la búsqueda en la página principal funciona para todos los productos, y si ya está en una sección específica, solo en los artículos de esa sección.
Agregar contenido y "migas de pan". Es bueno que en cada página haya un menú y migas de pan — el camino del usuario hasta la página actual con la posibilidad de volver a cualquier nivel. En la antigua documentación de ISPsystem, había que salir del artículo para acceder al contenido. Era incómodo, por lo que en la nueva lo corregimos.
Colocar enlaces en el producto. Si las personas llegan una y otra vez al soporte con la misma pregunta, es razonable agregar un consejo con su solución en la interfaz. Si tiene datos o un entendimiento de cuándo el usuario se enfrenta a un problema, también puede notificarlos mediante un aviso. Así demuestra preocupación y alivia la carga del soporte.
A la derecha, en la ventana emergente, hay un enlace al artículo sobre la configuración de DNSSEC en la sección de gestión de dominios de ISPmanager.
Configurar enlaces cruzados dentro de la documentación. Los artículos relacionados deben estar «interconectados». Si los artículos forman una secuencia, asegúrate de agregar flechas hacia adelante y hacia atrás al final de cada texto.
Es probable que la persona busque la respuesta a su pregunta primero en un motor de búsqueda en lugar de acudir a ti. Es decepcionante si no hay enlaces a la documentación por razones técnicas. Así que cuida de la optimización para motores de búsqueda.
Problema 4. Un diseño obsoleto dificulta la percepción
Además de los textos deficientes, el diseño puede arruinar la documentación. Las personas están acostumbradas a leer materiales bien diseñados. Los blogs, redes sociales y medios presentan su contenido de manera bella y también conveniente para la lectura, agradable a la vista. Por lo tanto, es fácil entender el dolor de alguien que ve el texto como en la captura de pantalla a continuación.
En este artículo hay tantas capturas de pantalla y resaltados que no ayudan, sino que solo dificultan la percepción (la imagen es clickeable)
No deberías convertir la documentación en una historia larga llena de efectos, pero es necesario tener en cuenta algunas reglas básicas.
Diseño. Define el ancho del texto principal, la fuente, tamaño, encabezados y márgenes. Atrae a un diseñador, y para aceptar el trabajo o hacerlo tú mismo, lee el libro de Artem Gorbunov «Tipografía y Diseño». Es solo una perspectiva sobre el diseño, pero es bastante suficiente.
Resaltados. Determina qué necesita énfasis en el texto. Generalmente, esto incluye el camino en la interfaz, botones, fragmentos de código, archivos de configuración, secciones de «Presta atención». Establece cómo serán estos elementos resaltados y regístralo en el protocolo. Ten en cuenta que cuántos menos resaltados haya, mejor. Cuando hay muchos, el texto «hace ruido». Hasta las comillas crean ruido si se usan con demasiada frecuencia.
Capturas de pantalla. Acordar con el equipo en qué casos se necesitan capturas de pantalla. No es necesario ilustrar cada paso. Un gran número de capturas de pantalla, incluidos botones individuales, dificulta la percepción y arruina el diseño. Define el tamaño, así como el formato de los resaltados y títulos en las capturas de pantalla, y regístralo en el protocolo. Recuerda que las ilustraciones siempre deben coincidir con lo escrito y ser actuales. Nuevamente, si el producto se actualiza regularmente, será difícil mantener el seguimiento de cada uno.
Longitud del texto. Evite artículos excesivamente largos. Divídelos en partes y si no es posible, añade un índice con enlaces de anclaje al principio del artículo. Una forma sencilla de hacer que un artículo se vea visualmente más corto es ocultar los detalles técnicos, que solo interesan a un público específico, bajo un spoiler.
Formatos. Combina varios formatos en los artículos: texto, video e imágenes. Esto mejorará la comprensión.
No intentes ocultar problemas con un diseño atractivos. Honestamente, nosotros también esperamos que el 'empaquetado' salvara la documentación obsoleta, pero no funcionó. Había tanto ruido visual en los textos y detalles innecesarios que el reglamento y el nuevo formato fueron ineficaces.
Mucho de lo descrito anteriormente dependerá de la plataforma que utilices para la documentación. Por ejemplo, nosotros usamos Confluence. También tuvimos que trabajar con eso. Si te interesa, lee la historia de nuestro desarrollador web: .
Por dónde comenzar las mejoras y cómo sobrevivir
Si tu documentación es tan vasta como la de ISPsystem y no sabes por dónde empezar, comienza con los problemas más serios. Si los clientes no entienden la documentación, trabaja en mejorar los textos, establece reglamentos y capacita a los escritores. Si la documentación está desactualizada, ocúpate de los procesos internos. Empieza con los artículos más populares sobre los productos más demandados: pregúntale a soporte, revisa la analítica del sitio y las consultas en los motores de búsqueda.
Seamos claros: no será fácil. Y tampoco será rápido. A menos que estés empezando y lo hagas bien desde el principio. Lo que sabemos con certeza es que con el tiempo será mejor. Pero el proceso nunca terminará :-).
Fuente: habr.com
