La documentación del software es solo un conjunto de artículos. Pero incluso ellos pueden volverte loco. Primero, pasas mucho tiempo buscando las instrucciones necesarias. Entonces entiendes el texto oscuro. Haces lo escrito, pero el problema no se resuelve. Buscas otro artículo, te pones nervioso... Una hora después dejas todo y te vas. Así es como funciona la mala documentación. Qué lo hace así y cómo solucionarlo: lea debajo del corte.
Había muchas deficiencias en nuestra documentación anterior. Llevamos casi un año reelaborándolo para que el escenario descrito anteriormente no afecte a nuestros clientes. Mirar, и .
Problema 1: artículos poco claros y mal escritos
Si la documentación es imposible de entender, ¿qué sentido tiene? Pero nadie escribe artículos incomprensibles a propósito. Ocurren cuando el autor no piensa en la audiencia y el propósito, vierte agua y no revisa el texto en busca de errores.
- La audiencia. Antes de escribir un artículo, es necesario pensar en el nivel de preparación del lector. Es lógico que en un artículo para principiantes no debas saltarte los pasos básicos y dejar los términos técnicos sin explicación, pero en un artículo sobre una característica poco común que solo los profesionales necesitan, debes explicar el significado de la palabra PHP.
- objetivo. Una cosa más en la que pensar de antemano. El autor debe fijar un objetivo claro, determinar el efecto útil del artículo y decidir qué hará el lector después de leerlo. Si no se hace esto, terminará con una descripción por el simple hecho de describir.
- agua y bichos. Hay mucha información y burocracia innecesarias, los errores y las erratas interfieren con la percepción. Incluso si el lector no es un nazi gramatical, el descuido en el texto puede desanimarlo.
Considere los consejos anteriores y los artículos serán más claros, garantizado. Para hacerlo aún mejor, utilice nuestro .
Problema 2. Los artículos no responden a todas las preguntas.
Es malo cuando la documentación no se mantiene al día con el desarrollo, no responde preguntas reales y los errores que contiene 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 ritmo del desarrollo.
La función ya está en lanzamiento, el marketing planea cubrirla y luego resulta que el nuevo artículo o traducción aún no está en la documentación. Incluso tuvimos que posponer el lanzamiento debido a esto. Puedes pedirles a todos que entreguen tareas a los redactores técnicos a tiempo tanto como quieras, pero no funcionará. Si el proceso no se automatiza, la situación se repetirá.
Hemos realizado cambios en YouTrack. La tarea de escribir un artículo sobre una nueva característica recae en el redactor técnico en el mismo momento en que la característica comienza a probarse. Luego, marketing se entera de ello para prepararse para la promoción. Las notificaciones también llegan al mensajero corporativo de Mattermost, por lo que es simplemente imposible perderse las noticias de los desarrolladores.
La documentación no refleja las solicitudes de los usuarios.
Estamos acostumbrados a trabajar así: surgió una característica, hablamos de ello. Describimos cómo encenderlo, apagarlo y realizar ajustes finos. Pero, ¿qué pasa si un cliente utiliza nuestro software de una forma que no esperábamos? ¿O tiene errores en los que no pensamos?
Para que la documentación sea lo más completa posible, recomendamos analizar solicitudes de soporte, preguntas en foros temáticos y consultas en motores de búsqueda. Los temas más populares se transferirán a los redactores técnicos para que puedan complementar los artículos existentes o escribir otros nuevos.
La documentación no se está mejorando.
Es difícil hacerlo perfectamente de inmediato; todavía habrá errores. Puede esperar recibir comentarios de los clientes, pero es poco probable que informen sobre cada error tipográfico, inexactitud, artículo incomprensible o infundado. Además de los clientes, los empleados leen la documentación, lo que significa que ven los mismos errores. ¡Esto se puede usar! Solo necesita crear condiciones en las que sea fácil informar un problema.
Disponemos de 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 existe? ¿El evaluador notó la inexactitud? ¿El socio se ha quejado de errores ante los responsables de desarrollo? ¡Todos en este grupo! Los redactores técnicos solucionan algunas cosas de inmediato, transfieren algunas a YouTrack y dan a otras algo de tiempo para pensar. Para evitar que el tema decaiga, de vez en cuando os recordamos la existencia del grupo y la importancia del feedback.
Problema 3. Se necesita mucho tiempo para encontrar el artículo adecuado.
Un artículo que no se puede encontrar no es mejor que un artículo que no se puede encontrar. El lema de una buena documentación debería ser "Fácil de buscar, fácil de encontrar". ¿Cómo lograr esto?
Organizar la estructura y determinar el principio para elegir temas.. La estructura debe ser lo más transparente posible para que el lector no piense: "¿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. Este era el caso en la antigua documentación del sistema ISP.
- De tareas. Los títulos de artículos y secciones reflejan las tareas de los usuarios; Los títulos casi siempre contienen verbos y respuestas a la pregunta "cómo hacerlo". Ahora pasamos a este formato.
Cualquiera que sea el enfoque que elija, asegúrese de que el tema sea relevante para lo que buscan los usuarios y que esté cubierto de una manera que aborde específicamente la pregunta del usuario.
Configurar una búsqueda centralizada. En un mundo ideal, la búsqueda debería funcionar incluso cuando se escribe mal o se comete un error con el idioma. Nuestra búsqueda en Confluence hasta ahora no puede complacernos con esto. Si tienes muchos productos y la documentación es general, adapta 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ás en una sección específica, solo para los artículos que contiene.
Agregar contenido y rutas de navegación. Es bueno cuando cada página tiene un menú y rutas de navegación: la ruta del usuario a la página actual con la capacidad de regresar a cualquier nivel. En la documentación antigua del sistema ISP, había que salir del artículo para acceder al contenido. Era un inconveniente, así que lo arreglamos en el nuevo.
Colocar enlaces en el producto.. Si la gente acude al soporte una y otra vez con la misma pregunta, tiene sentido agregar una pista con su solución a la interfaz. Si tiene datos o información sobre cuándo un usuario está experimentando un problema, también puede notificarlo con una lista de correo. Muéstreles preocupación y quíteles la carga del apoyo.
A la derecha de la ventana emergente hay un enlace a un artículo sobre cómo configurar DNSSEC en la sección de administración de dominios de ISPmanager.
Configurar referencias cruzadas dentro de la documentación. Los artículos que estén relacionados entre sí deben estar "vinculados". Si los artículos son secuenciales, asegúrese de agregar flechas hacia adelante y hacia atrás al final de cada texto.
Lo más probable es que una persona primero busque una respuesta a su pregunta, no a usted, sino a un motor de búsqueda. Es una pena que por motivos técnicos no aparezcan enlaces a la documentación. Así que ocúpate de la optimización de los motores de búsqueda.
Problema 4. El diseño obsoleto interfiere con la percepción
Además de los malos textos, la documentación puede estropearse por diseño. La gente está acostumbrada a leer materiales bien escritos. Blogs, redes sociales, medios: todo el contenido se presenta no solo de manera hermosa, sino también fácil de leer y agradable a la vista. Por lo tanto, puedes comprender fácilmente el dolor de una persona que ve un texto como el de la siguiente captura de pantalla.
Hay tantas capturas de pantalla y aspectos destacados en este artículo que no ayudan, solo interfieren con la percepción (se puede hacer clic en la imagen)
No deberías hacer una lectura larga de la documentación con un montón de efectos, pero debes tener en cuenta las reglas básicas.
Disposición. Determine el ancho, la fuente, el tamaño, los títulos y el relleno del texto del cuerpo. Contrate a un diseñador y, para aceptar el trabajo o hacerlo usted mismo, lea el libro de Artyom Gorbunov "Tipografía y diseño". Presenta sólo una vista del diseño, pero es más que suficiente.
Asignación. Determinar qué requiere énfasis en el texto. Normalmente se trata de una ruta en la interfaz, botones, inserciones de código, archivos de configuración y bloques de "Nota". Determinar cuáles serán las asignaciones de estos elementos y registrarlas en el reglamento. Tenga en cuenta que cuanto menos secreción, mejor. Cuando hay muchos, el texto tiene ruido. Incluso las comillas crean ruido si se usan con demasiada frecuencia.
Imágenes. Acuerde con el equipo en qué casos se necesitan capturas de pantalla. Definitivamente no es necesario ilustrar cada paso. Una gran cantidad de capturas de pantalla, incl. botones separados, interfieren con la percepción, estropean el diseño. Determine el tamaño, así como el formato de los resaltados y firmas en las capturas de pantalla, y regístrelos en el reglamento. Recuerde que las ilustraciones siempre deben corresponder a lo escrito y ser relevantes. Nuevamente, si el producto se actualiza periódicamente, será difícil realizar un seguimiento de todos.
Longitud del texto. Evite artículos demasiado largos. Divídalos en partes y, si esto no es posible, agregue contenido con enlaces ancla al comienzo del artículo. Una forma sencilla de hacer que un artículo sea visualmente más breve es ocultar los detalles técnicos que necesita un círculo reducido de lectores debajo de un spoiler.
Formatos. Combina varios formatos en tus artículos: texto, vídeo e imágenes. Esto mejorará la percepción.
No intente ocultar los problemas con un diseño hermoso. Honestamente, nosotros mismos esperábamos que el "envoltorio" guardara la documentación obsoleta; no funcionó. Los textos contenían tanto ruido visual y detalles innecesarios que las regulaciones y el nuevo diseño fueron impotentes.
Gran parte de lo anterior estará determinado por la plataforma que utilice para la documentación. Por ejemplo, tenemos Confluence. Tuve que jugar con él también. Si está interesado, lea la historia de nuestro desarrollador web: .
Dónde empezar a mejorar y cómo sobrevivir
Si su documentación es tan amplia como la de ISPsystem y no sabe por dónde empezar, comience con los problemas más grandes. Los clientes no comprenden el documento: mejoren los textos, establezcan regulaciones, capaciten a los redactores. La documentación está desactualizada: ocúpese de los procesos internos. Comience con los artículos más populares sobre los productos más populares: solicite soporte, consulte los análisis del sitio y las consultas en los motores de búsqueda.
Digamos de inmediato: no será fácil. Y tampoco es probable que funcione rápidamente. A menos que estés empezando y hagas lo correcto de inmediato. Una cosa que sabemos con certeza es que mejorará con el tiempo. Pero el proceso nunca terminará :-).
Fuente: habr.com