En el otoño de 2016, mi colega y yo recibimos instrucciones para mejorar la documentación y el contenido de mi antigua empresa. Pasamos un año en todo tipo de documentación: referencia de API, guías, tutoriales, publicaciones de blog. Antes de eso, escribí muelles durante 5 años, pero oficialmente no aprendí esto. Pero no se me puede llamar inexperto: además de documentar la API para proyectos y nuevas empresas, también enseñé Python Flask en seminarios mientras estudiaba en los últimos cursos en la universidad. Pero ahora es una oportunidad para concentrarme solo en mi negocio favorito: ayudar a especialistas en todos los niveles a través de la documentación técnica.

Este año aprendí mucho de la comunidad Write The Docs, de otros proveedores de API y del método de prueba y error. El año pasado, compartí mi experiencia en el informe "Lo que me gustaría saber sobre la redacción de documentación" en la Conferencia de práctica y estrategia API de Portland. Este artículo es una descripción general del conocimiento adquirido.

¿Cómo leen la gente realmente la documentación?

"Una nación se estremece ante un gran fragmento de un solo texto", foto de The Onion

¿Conoces este sentimiento como en la imagen? Sucede Tal vez no físicamente, pero lo más probable es que la gente se estremezca mentalmente. Me atormentaba constantemente la idea de que la gente no leería mis textos a menos que los dijera de una manera fácil de digerir. Gosh, esto puede suceder incluso con este artículo.

En un estudio de búsqueda de Neilson Norman Group en 2006, 232 usuarios vieron miles de páginas web. Resultó que los usuarios generalmente miran las páginas usando el patrón F:

1. “Primero leen en dirección horizontal , generalmente en la parte superior del área de contenido. Este es el elemento superior de la figura F. "
2. “Luego se mueven un poco hacia abajo de la página y hacen un segundo movimiento horizontal , que generalmente cubre un área más corta que la anterior. Este elemento adicional forma el elemento central de la figura F ".
3. “Finalmente, los usuarios escanean el lado izquierdo del contenido verticalmente . A veces, este es un escaneo lento y sistemático, que se muestra como una tira sólida en un mapa de calor. Algunas veces el movimiento es más rápido, formando puntos en el mapa de calor. Este es el último elemento vertical en la figura F. "

Mapas de calor Nielsen Norman Group

El estudio encontró algunos patrones de escaneo alternativos, como un patrón de hojaldre, un mapa irregular, una plantilla de diseño, un patrón de derivación y un patrón intencional. Le recomiendo que lea el informe .

Es importante tener en cuenta que el patrón F está en el camino de los usuarios , pero un buen posicionamiento del contenido ayuda a prevenir los escaneos F.

¿Cuáles son las implicaciones específicas para la documentación?

• Los primeros dos párrafos deben indicar la información más importante.
• Las primeras 3-5 palabras son críticas
• Encabezados, párrafos y listas con viñetas con palabras informativas
• Los cambios de fuente (tamaño, enlaces, negrita, etc.) pueden ser necesarios para mantener la atención del lector

Entonces, ¿cómo estructurar el contenido de la página?

• Evite el escaneo: asegúrese de que la información que el lector necesita esté resaltada
• Un pensamiento en un párrafo. Si hay varios, rompa el párrafo
• Los usuarios omiten todo lo que parece pancartas, así que tenga cuidado con las ilustraciones.
• No expanda demasiado la columna de texto: óptimamente 65–90 caracteres

Aprendí algunos de estos consejos de la conferencia de Kevin Burke , "Cómo escribir documentación para usuarios que no la leen". Kevin apoyó la documentación de Twilio de 2011 a 2014.

Además, los párrafos tienen sus propios detalles. Al igual que el texto de The Onion , cuando lees muchos párrafos, puedes saltarte la esencia. Entonces, ¿por qué usarlos tan a menudo? Hagamos un experimento de la documentación de Keen IO:

Lea esto rápidamente:

Los conjuntos de eventos pueden tener casi cualquier nombre, pero hay varias reglas: el nombre no debe tener más de 64 caracteres. Debe contener solo caracteres ASCII. No puede ser nulo.

Ahora lee esto rápidamente:

Los conjuntos de eventos pueden tener casi cualquier nombre, pero hay algunas reglas:

• El título no debe tener más de 64 caracteres.
• Debe contener solo caracteres ASCII
• No puede ser nulo

En ambos ejemplos, el mismo texto exacto . Este no es el binomio de Newton: el segundo ayuda a absorber la información mejor y más rápido. Si el párrafo contiene una lista de cualquier tipo, conviértala en una lista con viñetas.

Más adelante discutiremos con más detalle el diseño de la documentación y la navegación en él.

Ejemplos de código

¿Qué es la documentación API sin código, verdad? Hay ejemplos de código en muchos de nuestros documentos, y los usuarios realmente los leen. Pero el problema es que no siempre prestan atención al texto circundante.

El contexto en el código de muestra es crítico para el éxito del desarrollador. A los desarrolladores les encanta copiar y pegar rápidamente. Aquí hay un ejemplo con la API Keen IO:

var client = new Keen({ projectId: "your_project_id", writeKey: "your_write_key" }); var ticketPurchase = { price: 50.00, user: { id: "020939382", age: 28 }, artist: { id: "19039", name: "Tycho" } } client.addEvent("ticket_purchases", ticketPurchase); 

El desarrollador copia y pega rápidamente este código. Y ...



Primero, ¿cómo ejecutan el archivo? Probablemente como node file_name.js , pero esto no está en el código. Se podría indicar en los comentarios en la parte superior.

Bueno, lo comenzaron y ... ReferenceError: Keen is not defined . :-( El cliente Keen no se inició, en la parte superior no hay ninguna declaración de importación o solicitud, y solo funciona después de instalar la biblioteca npm.

El usuario lo arregló y lo ejecutó de nuevo ... ¿Adivina? Otro error! your_project_id y your_write_key .

Todo esto podría hacerse más obvio.

Aquí hay un ejemplo de la documentación de Twilio que proporciona un buen contexto para el usuario final:


Captura de pantalla de la documentación de la biblioteca Twilio Node Helper

Esto aclara inmediatamente cómo instalar la biblioteca, incrustarla en su código y qué debe reemplazarse en el código de muestra antes de ejecutarla.

Copiar y pegar errores

Como tenemos una gran cantidad de código de muestra en la documentación, copiar y pegar con éxito es una propiedad bastante importante. Aquí hay dos ejemplos de donde esto no se respeta:

 #      $ gem install rails 

Parece bastante inofensivo, ¿verdad? Piense de nuevo, ¿qué sucede cuando copia y pega esto en la línea de comando? Lo más probable es que reciba:

 bash: command not found: $ 

Un error comun. O desea que el comando se vea como en la línea de comando, o lo copia accidentalmente. Recomendaría renunciar a $ . También puede encontrar una manera de prohibir copiar y pegar este símbolo para que el error no moleste a los usuarios.

Un ejemplo más reciente: ¿comprobó lo fácil que es resaltar el código que el usuario desea copiar?

Kelsey Hightower tuvo problemas para copiar el código de muestra de StackOverflow en la presentación de Google Cloud Next.


"Los buenos programadores copian, los grandes programadores pegan"

¿Lo hizo a propósito? Nunca lo sabremos Sin embargo, esta es una ilustración de cómo los programadores intentan resaltar grandes bloques de texto en algunos sitios de documentación. Asegúrese de que la interfaz de usuario del sitio facilite la copia de bloques grandes. Incluso puede romper estos bloques para explicar los fragmentos individualmente. Entonces serán más accesibles para copiar y comprender.

"¡Eso es todo!"

"¡Eso es todo!" La frase parece bastante inofensiva fuera de contexto, pero imagina cómo ciertas palabras como "fácil", "simple", "trivial" y "fácil" se perciben cuando tienes problemas, ¡no genial! Cuando una persona está atrapada tratando de hacer que la API funcione, tal frase arroja dudas sobre su inteligencia y le hace hacer la pregunta: "¿Entonces soy estúpido?" Desmoraliza.

Simplificación excesiva

La simplificación es común. Es más común entre los principiantes en la escritura de documentación. A menudo, los autores de la documentación son al mismo tiempo los desarrolladores del sistema, por lo que algunas cosas les parecen "fáciles". Pero desarrollaron esta función, escribieron el código, la verificaron muchas, muchas veces y luego escribieron la documentación. Cuando haces algo docenas de veces, está claro que será "fácil" para ti. Pero, ¿qué pasa con alguien que nunca antes ha visto una interfaz de usuario o función?

Empatía

La elección de las palabras realmente importa. La empatía es la capacidad de comprender y compartir los sentimientos de los demás. Cuando mostramos empatía, ayudamos no solo a los recién llegados, sino también a los usuarios más avanzados. Esto ayuda a aumentar el número potencial de usuarios, casos de uso, clientes e incluso los ingresos de la empresa.

Pero cuando la documentación está escrita por un desarrollador experto de proyectos, la empatía es más difícil. Aquí hay algunos consejos útiles que me han ayudado en el pasado:

• Pida a los participantes del proyecto con menos experiencia que comenten honestamente sobre la documentación.
• Aliente a los participantes del proyecto con menos experiencia a contribuir o señalar puntos de documentación que no entiendan.
• Cree un entorno donde se alienten las preguntas, incluidas las que pueden parecer "obvias" para los participantes experimentados del proyecto; esto lo ayudará a notar los "puntos ciegos"
• Use procesadores de código en la revisión de código y los procesos de CI para garantizar la empatía y el lenguaje amigable para todos los usuarios.
• Finalmente, solicite comentarios sobre la documentación de usuarios reales, muéstreles el texto y pregunte si todo está claro

Mensajes de error como un tipo de documentación

Por lo general, es más probable que los usuarios vean mensajes de error que la documentación. Según Kate Voss, "los mensajes de error son en realidad una oportunidad". Creo que muchos desarrolladores de documentación están perdiendo esta oportunidad. Hay un lugar para la capacitación, estableciendo relaciones de confianza y expectativas de los usuarios. En primer lugar, ayudarás a las personas a ayudarse a sí mismas.

Kate en Write The Docs proporciona mucha información útil sobre cómo escribir mensajes de error. Aprendí mucho durante mi trabajo anterior sobre mensajes de error de API, además de estar al otro lado de las barricadas, recibiendo mensajes de error de otras API como desarrollador.

Kate dice que los buenos mensajes de error se basan en tres principios:

• Modestia
• La humanidad
• Utilidad

Modestia

Necesitas disculparte de inmediato, incluso si no es tu culpa. También practico esto en el servicio de soporte.

Un ejemplo:

Lo sentimos, no se pudo conectar a ___. Verifique la configuración de su red, conéctese a una red disponible e intente nuevamente.

La humanidad

Use términos legibles por humanos, evite frases como "excepción lanzada por el objetivo de la llamada". Al escribir código para el cual se activan muchos mensajes de error, es fácil salirse con la suya con un vocabulario claro.

Ejemplo (error de código de estado Twilio 401):

 { “code”: 20003, “detail”: “Your AccountSid or AuthToken was incorrect.”, “message”: “Authenticate”, “more_info”: “https://www.twilio.com/docs/errors/20003", “status”: 401 } 

Utilidad

Si recuerda uno de estos consejos, recuerde la utilidad. Comparta información con el usuario sobre cómo solucionar el problema.

Un ejemplo:

Lo sentimos, la imagen que intentaste subir es demasiado grande. Inténtalo de nuevo con imágenes de menos de 4000 px de alto y 4000 px de ancho.

Cómo escribir mensajes de error

Como con cualquier otra documentación, proporcione información importante primero. Esto se puede hacer especificando primero el objeto, luego la acción. El usuario está buscando un resultado, no cómo llegar allí. Esto es útil cuando los usuarios buscan rápidamente mensajes de error.

Mal ejemplo:

Presione el botón Atrás para volver a la página anterior.

Buen ejemplo:

Para volver a la página anterior, use el botón Atrás.

Mensajes de error de documentación

Me resulta muy útil cuando se mencionan mensajes de error generales de la API en la documentación. De esta forma, el autor de la documentación puede aclarar el mensaje de error sin ampliar la documentación, al mismo tiempo que ayuda al usuario a comprender por qué ocurre el error.

Twilio publica un catálogo completo de errores y advertencias con posibles causas y soluciones. Con este método, puede hacer que los mensajes de error reales sean más cortos pero útiles.

En caso de error 20003 (error de código de estado 401, mencionado anteriormente), hay muchas razones posibles que están claramente establecidas en el catálogo.


Fuente: https://www.twilio.com/docs/api/errors

Stripe hace algo similar con una descripción detallada de los diversos códigos de error.




Fuente: https://www.twilio.com/docs/api/errors

Incluso puede encontrar sus mensajes de error en las preguntas de StackOverflow. Responda con modestia, humanidad y beneficio. Debido al SEO, los usuarios a menudo terminan con sus mensajes de error en StackOverflow en lugar de la documentación real.

Sugerencia: si alguien no respondió con modestia, humanidad y beneficio, entonces con suficiente "reputación" puede editar las respuestas de StackOverflow.

Selección de palabras

Muchas palabras tienen patrones mentales bien establecidos. Por ejemplo, palabras como "bibliotecas", SDK, "envoltorios" y "clientes" ya están sobrecargadas y pasan por la atención del lector.

En su conferencia, "Incluso para esta conferencia, es difícil encontrar un nombre" en Write The Docs, Ruthie Bendor dice por qué elegir las palabras correctas puede ser tan difícil.

A menudo elegimos mal las palabras, aunque cuando escribimos un texto hacemos esto todo el tiempo. Al igual que muchos títulos de SDK, cada palabra evoca una amplia gama de sentimientos, ideas y definiciones en el lector. Es posible que no entienda esto, y a menudo hacemos suposiciones equivocadas.

En tal situación, el famoso proverbio es verdadero como nunca antes: "Solo hay dos tareas difíciles en el campo de la informática: invalidación de caché e inventar nombres". La cita a menudo se le atribuye a Phil Carleton, pero hoy hay muchas variaciones de este dicho. Algunas veces al final agregan "... y un error por unidad". Ruti considera que esto es una demostración de que el software actual se basa en gran medida en el código o el trabajo de otra persona.

¿Por qué se conservan los nombres de objetos incorrectos (o la documentación)?

Al igual que con la simplificación excesiva, a menudo no entendemos que el nombre es malo. Esto es lo que Ruthie llama el fracaso de la empatía . Así es como decir que el problema de las palabras fallidas no me concierne, por lo tanto, no existe.

Sugerencia para EE. UU .: Para evitar el racismo accidental, use las palabras "lista prohibida" y "lista permitida" en lugar de "negro" y "blanco".
(Fuentes: Andre Staltz y rieles / rieles / cuestiones / 33677 )

Todavía me recuerda lo que Ruthie llama un error de pensamiento novato . Es como decir "Está completamente claro para mí. No entiendo cómo alguien no puede entender esto ".

Finalmente, Ruthie menciona un error de localización . Por ejemplo, la palabra Bing en chino significa "enfermo".

Según un estudio de la Encuesta de código abierto de GitHub 2017 :

Casi el 25% de los desarrolladores que leen y escriben en inglés no es "muy bueno". Al comunicarse en un proyecto, use un lenguaje comprensible y accesible para personas de países que no hablan inglés.

¿Tiene esto en cuenta cuando usa americanismos y expresiones idiomáticas en la documentación? Muchos de ellos pueden ser incomprensibles para los usuarios.

Sugerencia: Creo firmemente que uno de los mejores "trucos" para resolver estos problemas es la diversidad del equipo de documentación.

Todavía hay casos en los que reconocemos un error, pero no podemos o no queremos corregirlo, porque nosotros ...

• Atado a ella
• No encontramos tiempo
• No vemos la importancia
• No tenemos una agencia para arreglarlo.

Puedes decir o escuchar: "¡Pero esta es mi creación!", "¿Quién se llevó a mi amorcito?" "Si cambiamos el nombre, todo se romperá", "no creo que cambiar este nombre afecte a nada importante".

No puede tener miedo de refactorizar y reescribir cuando se trata de documentación. ¿Cómo mejorarlo, si no está de acuerdo con el hecho de que inicialmente no se hizo la mejor elección?

¿Cómo elegir las palabras correctas?

Para comenzar, le recomiendo hacer una pregunta: ¿qué palabras usan sus usuarios? Los diferentes círculos de programadores usan términos diferentes, no intentes usar otros. Esto es útil no solo para lectores, sino también para búsqueda y SEO.

Al final, todo inevitablemente se reduce a una evaluación subjetiva. Sin embargo, hay algunos principios a tener en cuenta. Ruthie dice que los malos nombres son los que pueden:

• avergonzar
• molestar
• engañar
• confundir
• ofender

Buenos nombres, por otro lado:

• contribuir a una aclaración repentina ("eso es todo")
• inyectado en contexto
• explicar
• iluminar
• brindar apoyo

Recomiendo tener en cuenta estas cualidades al deducir la documentación para hacer revisiones útiles y honestas al respecto.

Elegir las palabras correctas es difícil. No hay una fórmula mágica. Todos los usuarios son diferentes, al igual que los casos de uso del producto; lo que funciona para algunos puede no funcionar para otros. Si fuera fácil, todos tendrían una documentación mucho mejor. Como Ruthie le dice a los desarrolladores: “Escribir programas es un ejercicio para inventar nombres. Tratar con eso ". Y si está escribiendo documentación para el programa de otra persona, "dígale al desarrollador si sus nombres no llegan al objetivo".