La documentación del software es solo una colección de artículos, pero incluso ellos pueden volverte loco. Primero busca la instrucción correcta durante mucho tiempo, luego comprende el texto oscuro, haga lo que está escrito, pero el problema no está resuelto. Estás buscando otro artículo, estás nervioso ... Después de una hora escupes todo y te vas. Así es como funciona la mala documentación. Qué lo hace así y cómo solucionarlo: lea debajo del corte.
Nuestra vieja documentación tenía muchos defectos. Durante casi un año lo hemos estado procesando para que el escenario descrito anteriormente no afecte a nuestros clientes. Vea cómo fue y cómo se convirtió .
Problema 1. Artículos incomprensibles, mal escritos
Si es imposible averiguar la documentación, ¿cuál es el punto? Pero nadie escribe artículos oscuros a propósito. Se obtienen 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, debe pensar en el nivel de preparación del lector. Es lógico que en el artículo para principiantes no debe omitir los pasos básicos y dejar los términos técnicos sin descifrar, y en el artículo sobre una característica rara que es necesaria solo para los profesionales, mastique el significado de la palabra PHP.
- Propósito Otra cosa que debes pensar de antemano. El autor debe establecer un objetivo claro, determinar el efecto útil del artículo, decidir qué hará el lector después de leerlo. Si esto no se hace, se obtendrá una descripción por el bien de la descripción.
- Agua y bichos . Una gran cantidad de información innecesaria y clericalismo, errores y errores tipográficos interfieren con la percepción. Incluso si el lector no es un país de gramática, la negligencia en el texto puede alejarlo.
Considere los consejos anteriores, y los artículos serán más claros, garantizados. Para hacerlo aún mejor, responda nuestras
50 preguntas cuando trabaje en la documentación técnica .
Problema 2. Los artículos no responden todas las preguntas
Es malo cuando la documentación no se mantiene al día con el desarrollo, no responde preguntas reales, los errores no se han solucionado durante años. Estos problemas no son tanto el autor, sino la organización de los procesos dentro de la empresa.
La documentación no se mantiene al día con el desarrollo.
La característica ya está en el lanzamiento, el marketing planea cubrirla y resulta que el nuevo artículo o traducción aún no está en la documentación. Debido a esto, incluso tuvimos que posponer el lanzamiento. Puede pedir a todos que entreguen la tarea a los escritores técnicos a tiempo, pero esto no funcionará. Si el proceso no está automatizado, 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 escritor técnico en el mismo momento en que comienzan a probar la oportunidad. Luego, el marketing aprende sobre ella para prepararse para la promoción. Las notificaciones también vienen en el mensajero corporativo Mattermost, por lo que es simplemente imposible perderse las noticias de los desarrolladores.
La documentación no refleja las solicitudes de los usuarios.
Solíamos trabajar así: apareció una característica, hablamos de ello. Describimos cómo activarlo, desactivarlo y realizar ajustes precisos. Pero, ¿qué pasa si el cliente usa nuestro software de una manera que no esperábamos? ¿O está cometiendo errores en los que no hemos pensado?
Para que la documentación sea lo más completa posible, le recomendamos que analice las solicitudes de soporte, las preguntas en foros temáticos y las consultas en los motores de búsqueda. Los temas más populares deben transmitirse a los escritores técnicos para complementar los artículos existentes o escribir otros nuevos.
La documentación no se está mejorando.
Es difícil hacerlo de inmediato perfectamente, de todos modos habrá errores. Puede confiar en los comentarios de los clientes, pero es poco probable que denuncien cada error tipográfico, inexactitud, artículo incomprensible o desconocido. Además de los clientes, los empleados leen la documentación, lo que significa que ven los mismos errores. Se puede usar! Solo es necesario crear condiciones en las que sea fácil informar 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? ¿Notó el probador una inexactitud? Socio se quejó a los gerentes de desarrollo por errores? ¡Todo en este grupo! Los escritores técnicos arreglan algo de inmediato, transfieren algo a YouTrack, toman algo en qué pensar. Para mantener el tema en silencio, de vez en cuando recordamos la existencia del grupo y la importancia de la retroalimentación.
Problema 3. Tienes que buscar el artículo correcto durante mucho tiempo
Un artículo que no se puede encontrar no es mejor que un artículo que no se encuentra. El lema para una buena documentación debe ser "Fácil de buscar, fácil de encontrar". ¿Cómo lograr esto?
Agilice la estructura y determine el principio de elegir temas . La estructura debe ser lo más transparente posible para que el lector no piense "¿Dónde puedo encontrar este artículo?" Para resumir, hay dos enfoques: desde la interfaz y desde las tareas.
- De la interfaz. Contenido duplica secciones del panel. Así que estaba 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 encabezados casi siempre contienen verbos y respuestas a la pregunta "cómo hacerlo". Ahora nos estamos moviendo a este formato.
Independientemente del enfoque que elija, asegúrese de que el tema satisfaga las necesidades de los usuarios y esté cubierto para que el usuario resuelva con precisión su pregunta.
Establecer una búsqueda centralizada . En un mundo ideal, la búsqueda debería funcionar incluso cuando está triste o confundido con el idioma. Nuestra búsqueda en Confluence no puede complacer esto todavía. 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 principal funciona en todos los productos, y si ya está en una sección específica, solo en los artículos que contiene.
Agregue contenido y migas de pan . Es bueno cuando hay un menú y migas de pan en cada página: la ruta del usuario a la página actual con la capacidad de volver a cualquier nivel. En la documentación anterior del sistema ISP, tenía que salir del artículo para acceder al contenido. Era inconveniente, así que en el nuevo lo arreglamos.
Organizar enlaces en el producto . Si las personas reciben apoyo de vez en cuando con la misma pregunta, es razonable agregar una pista con su solución a la interfaz. Si tiene datos o comprende en qué momento el usuario enfrenta un problema, también puede notificárselo por boletín. Tenga cuidado y retire la carga del soporte.
A la derecha de la ventana emergente hay un enlace a un artículo sobre la configuración de DNSSEC en la sección de administración del dominio ISPmanagerConfigure referencias cruzadas dentro de la documentación . Los artículos relacionados deben estar "vinculados". Si los artículos son una secuencia, asegúrese de agregar flechas hacia adelante y hacia atrás al final de cada texto.
Lo más probable es que una persona vaya primero a buscar una respuesta a su pregunta, no a usted, sino a un motor de búsqueda. Es una pena si no hay enlaces a la documentación allí por razones técnicas. Así que cuide la optimización del motor de búsqueda.
Problema 4. El diseño anticuado interfiere con la percepción
Además de los textos incorrectos, el diseño puede arruinar la documentación. La gente está acostumbrada a leer materiales bien hechos. Blogs, redes sociales, medios: todo el contenido se presenta no solo hermoso, sino también fácil de leer, agradable a la vista. Por lo tanto, puede comprender fácilmente el dolor de una persona que ve el texto en la siguiente captura de pantalla.
Hay tantas capturas de pantalla y selecciones en este artículo que no ayudan, pero solo interfieren con la percepción (se puede hacer clic en la imagen)No vale la pena hacer un longrid con un montón de efectos de la documentación, pero debe tener en cuenta las reglas básicas.
Diseño . Defina el ancho del texto principal, fuente, tamaño, encabezados y sangrías. Involucre a un diseñador y acepte un trabajo o hágalo usted mismo, lea el libro Typography and Layout de Artyom Gorbunov. Presenta solo una de las vistas en el diseño, pero es suficiente.
Asignaciones Defina lo que necesita énfasis en el texto. Por lo general, esta es la ruta en la interfaz, botones, inserciones de código, archivos de configuración, bloques "Prestar atención". Establezca cuál será la selección de estos elementos y corríjalo en la programación. Tenga en cuenta que cuanto menos excreción, mejor. Cuando hay muchos de ellos, el texto "hace ruido". Incluso las comillas crean ruido si se usan con demasiada frecuencia.
Capturas de pantalla Organice con el equipo en qué casos se necesitan capturas de pantalla. Definitivamente no hay necesidad de ilustrar cada paso. Una gran cantidad de capturas de pantalla, incluidas botones individuales interfieren con la percepción, diseño de botín. Determine el tamaño, así como el formato de las selecciones y los subtítulos en las capturas de pantalla, corrija las regulaciones. Recuerde que las ilustraciones siempre deben ser escritas y relevantes. Nuevamente, si el producto se actualiza regularmente, será difícil hacer un seguimiento de cada uno.
La longitud del texto . Evite artículos demasiado largos. Fragméntelos en partes y, si no es posible, agregue contenido vinculado al ancla en la parte superior del artículo. Una manera fácil de hacer que un artículo sea visualmente más corto es ocultar los detalles técnicos que necesita un círculo estrecho de lectores bajo un spoiler.
Formatos Combina varios formatos en artículos: texto, video e imágenes. Esto mejorará la percepción.
No intente ocultar problemas con un diseño hermoso. Honestamente, nosotros mismos esperábamos que el "contenedor" guardara la documentación desactualizada; no funcionó. Los textos tenían tanto ruido visual y detalles innecesarios que las regulaciones y el nuevo diseño carecían de poder.
Gran parte de lo anterior estará determinado por el sitio que utilice para la documentación. Para nosotros, por ejemplo, esto es Confluencia. También tuvo que jugar con él. Si está interesado, lea la historia de nuestro desarrollador web:
Confluencia para una base de conocimiento público: cambie el diseño y configure la separación de idiomas .
Dónde comenzar a mejorar y cómo sobrevivir
Si su documentación es tan amplia como la del ISPsystem y no sabe qué tomar, comience con los problemas más serios. Los clientes no entienden cómo mejorar textos, hacer regulaciones y entrenar escritores. La documentación está desactualizada: adopte procesos internos. Comience con los artículos más populares sobre los productos más buscados: solicite asistencia, consulte análisis de sitios web y consultas de motores de búsqueda.
Digamos de inmediato: no será fácil. Y rápidamente, también, es poco probable que tenga éxito. A menos que recién esté comenzando y haciéndolo de inmediato. Sabemos una cosa con certeza: mejorará con el tiempo. Pero el proceso nunca terminará :-).