50 preguntas para trabajar en documentación

No importa cuánto lo intente el diseñador de UX, una persona de la calle no podrá descubrir la interfaz de control de la nave espacial sin una pista. Y ni siquiera desde la calle. Solo porque el cohete es grande y hay muchas configuraciones.

Hacemos productos más simples que el software para cohetes, pero aún técnicamente sofisticados. Nos esforzamos mucho para que las interfaces de las nuevas versiones sean simples, pero nos damos cuenta de que siempre habrá un usuario que no entenderá algo e irá a la documentación. Por lo tanto, debe haber un muelle, y para no estropear la impresión del producto, debe ser útil y conveniente.

Tenemos seis productos, cuya documentación desde la fundación de la empresa fue escrita por desarrolladores. Durante medio año hemos estado reescribiendo viejos y escribiendo nuevos artículos . Bajo el corte: 50 preguntas que nos ayudan a hacerlo bien. Pero para empezar, un poco introductorio.

Por qué la documentación es importante y quién debe hacerlo

Hacer un buen muelle es difícil. En algún lugar, un gran departamento de analistas, escritores y editores está trabajando en ello, y en algún lugar los desarrolladores están escribiendo en el muelle (hecho - descrito).

Tenemos dos escritores técnicos en seis productos con varias versiones. Esto no es suficiente, por lo que los gerentes de producto, los probadores, la primera línea de soporte y el trabajo de marketing en el muelle. No escriben artículos, pero ayudan a comprender el producto y las tareas del cliente, elegir un tema y recopilar información, verificar el contenido y el diseño del artículo terminado. Juntos hacemos el muelle mejor.

Si tiene un pequeño departamento de redacción técnica, reclute personal de otros departamentos. Si no están interesados, proporcione argumentos de la lista a continuación. Primer soporte, segundo y tercer marketing y marketing de producto. Entonces, ¿por qué es importante la documentación?

1. Factor de soporte . La primera y más obvia de las razones. Si la documentación es buena, la mayoría de los clientes resolverán el problema sin contactar al soporte. El soporte restante arrojará un enlace a las instrucciones o lo revisare rápidamente yo mismo. Se puede usar la documentación completa para crear bots de chat. Todo esto reduce el tiempo de respuesta a los clientes, aumenta su satisfacción y también reduce los costos de soporte.
2. Factor de selección La documentación afecta la elección del cliente junto con el precio, la conveniencia, la funcionalidad. Esto es confirmado por nuestra investigación y comentarios de los usuarios de ISPmanager y DCImanager . En este sentido, el muelle deja de ser una necesidad de soporte, pero se convierte en una ventaja competitiva, parte del marketing.
3. Factor de fidelidad . Si el cliente se fue sin comprender el muelle al inicio o en el proceso, esto es un problema. Atraer a un cliente es demasiado costoso como para perderlo debido a artículos malos.

Cómo hacer buena documentación

Define una meta . Este es el mayor dolor. Describir una función solo por el bien de la descripción o comentar en una interfaz no es el objetivo. Un objetivo es siempre una acción beneficiosa. ¿Qué debe saber un usuario, administrador o desarrollador y poder leer después de leer un artículo? Por ejemplo, cree un sitio y agréguele un dominio, emita un certificado SSL, configure copias de seguridad, etc. Es decir, resuelva su problema.

Conoce a la audiencia . Dividimos a los clientes en usuarios, administradores y desarrolladores. Pero esto no es suficiente para crear textos útiles. Para comprender rápidamente a la audiencia, puede ir a UX y al producto, estudiar las solicitudes de soporte y sus respuestas sobre el tema, escuchar las llamadas de primera línea, mirar el sitio y el blog (el marketing también escribe las cosas necesarias). Y solo después de eso comienza a escribir.

Verificar, editar y verificar nuevamente . Los escritores técnicos deben hacer una verificación inicial. Después de ella una más. Entonces vale la pena conectar soporte, marketing y otros departamentos a la auditoría. Luego debe consultar el manual de estilo y diseño - política editorial. Alguien de un lado u otro escritor técnico lo dejó hacer la revisión final. Si tienes un editor, él asumirá esta etapa.

Distribuya el artículo después de la publicación . Si la documentación está escrita, lo más probable es que alguien la necesite. Muéstrelo a la luz y utilícelo al máximo: traduzca, consulte el producto, dele al marketing, soporte. No escribas en la mesa.

50 preguntas para trabajar en el muelle

Trabajando en la documentación, repetimos los mismos errores. Pasaron demasiado tiempo revisando los artículos, y la guía, que inicialmente parecía una panacea, no ayudó, porque el problema estaba en el enfoque y el contenido. Para que los escritores técnicos puedan recordar el artículo rápida y rápidamente, reunimos en una lista todas las preguntas que constantemente les hacíamos (u olvidábamos hacer). Úselo si también escribe un muelle.

Objetivos

1. ¿Para quién estoy escribiendo un artículo? ¿Quién es el futuro lector: usuario, administrador, desarrollador?
2. ¿Qué tareas enfrenta (trabajos a realizar)? ¿Hay una descripción de la persona?
3. ¿Cuál es el nivel de capacitación de este usuario? ¿Qué sabe él ya? ¿Qué no es obvio para él?
4. ¿Cómo se puede explicar esto a un usuario novato y no estar enojado con una explicación avanzada de cosas básicas?
5. ¿Qué más hay que explicar al usuario para que comprenda el contenido principal del artículo?
6. ¿Para qué sección de la documentación es adecuado este artículo?
7. ¿Debería este artículo o parte de él estar duplicado en otras secciones?
8. ¿A qué artículos debo vincular?
9. ¿Quizás este artículo debería ir acompañado de una instrucción en video?

Fuentes de informacion

10. ¿Los usuarios actuales tienen problemas con el tema del artículo?
11. ¿Cómo explica ahora el soporte lo que hay que hacer?
12. ¿El departamento de marketing escribió artículos de blog y noticias sobre este tema? ¿Pueden "espiar" su redacción, estructura, etc.?
13. ¿Hay alguna sección sobre este tema en el sitio?
14. ¿Qué incluyó el script la UX y el gerente de producto? ¿Por qué hizo esto?
15. ¿Cómo los competidores describen esta pregunta?
16. ¿En qué áreas todavía puedes ver las mejores prácticas?

Verificación de contenido

17. ¿Alcanzaste el objetivo del artículo?
18. ¿Todo estará claro para un usuario más avanzado?
19. ¿Todo estará claro para un usuario novato?
20. ¿Es todo lógico y consistente? ¿Sin saltos y abismos?
21. ¿Es correcta la secuencia de acciones? ¿El usuario podrá lograr el objetivo siguiendo solo estas instrucciones?
22. ¿Hemos tenido en cuenta todos los casos / rutas de usuario?
23. ¿Encaja el artículo en la sección seleccionada?

Verificación de diseño

24. ¿Hay hojas de texto ilegibles? ¿Es posible reemplazar el circuito?
25. ¿Hay párrafos largos?
26. ¿Hay párrafos demasiado cortos?
27. ¿Hay listas demasiado largas?
28. ¿Hay listas demasiado complicadas para la percepción (aquellas en las que hay más de dos o tres niveles)?
29. ¿Hay suficientes imágenes?
30. ¿No hay demasiadas imágenes? ¿Estamos ilustrando pasos demasiado obvios?
31. Si hay esquemas, ¿son comprensibles?
32. Las tablas no son difíciles de percibir?
33. ¿La página en general se ve bien?

Edición literaria

34. ¿Está todo diseñado de acuerdo con la guía?
35. ¿Es coherente el estilo del resto de la documentación?
36. ¿Alguna sugerencia que pueda simplificarse?
37. ¿Existen términos complejos que necesitan aclaración?
38. ¿Hay un clericalismo?
39. ¿Hay una repetición?
40. ¿Nada perjudica tu audición?

Revisión final

41. ¿Hay errores tipográficos, ortográficos o de puntuación?
42. ¿Están bien los guiones, los párrafos y las secciones?
43. ¿Están firmadas todas las imágenes?
44. ¿Los elementos de la interfaz están nombrados correctamente?
45. ¿Hay enlaces en todas partes? ¿Trabajan y a dónde van?

Inmediatamente después de la publicación.

46. ​​¿El artículo tiene secciones que son "arrastradas" a otros artículos? ¿Están decorados con macros para que los cambios en un artículo se apliquen automáticamente a otros?
47. ¿Se debe hacer referencia a este artículo desde otras secciones? Si es así, ¿de cuál?
48. ¿Necesita agregar un enlace rápido a este artículo en el producto?
49. ¿Tengo que enviar el enlace a soporte, marketing u otros departamentos?
50. ¿Tengo que enviar un artículo para traducción?

Esta lista se puede imprimir y poner en el escritorio o colgar en la pared. O conviértete en una lista de verificación. Algunas de las preguntas pueden incorporarse al proceso comercial. El nuestro, por ejemplo, está arreglado en el proceso de desarrollo general en YouTrack. La tarea de documentación pasa por diferentes etapas y departamentos, sin documentación escrita no se puede dar una función para liberar.