On Writing Friendly and Welcoming Documentation / Sobre la redacción de documentación amistosa y de bienvenida / NodeConf Argentina

Keynote for the second day of NodeConf Argentina!

Transcript

1. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring On Writing Friendly and 
 Welcoming Documentation 
 Sobre la redacción de documentación amistosa y de bienvenida.
2. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring Hola, soy Tracy! @limedaring (daring, not darling)
3. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring
4. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring
5. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring
6. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring
7. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring I will be tweeting all links: @limedaring (“daring” — not “darling”) #talkpay
8. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring
9. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring Better documentation = More users. Less support requests. More contributors. Mejor documentación = Más usuarios. Menos solicitudes de soporte Más colaboradores.
10. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring
11. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring Most of these tips work 
 for all writing. La mayoría de estos consejos funcionan para todos los escritos.
12. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring
13. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring Design for Non-Designers Basics of designing so you can make effective, lovely interfaces. #talkpay
14. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring
15. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring Design for Non-Designers Basics of designing so you can make effective, lovely interfaces. #talkpay
16. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring Design for Non-Designers Basics of designing so you can make effective, lovely interfaces. #talkpay
17. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring Design for Non-Designers Basics of designing so you can make effective, lovely interfaces. #talkpay
18. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring Design for Non-Designers Basics of designing so you can make effective, lovely interfaces. #talkpay
19. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring We’re chatting content, not design 
 (and definitely not grammar.) Estamos hablando de contenido, no de diseño (y definitivamente no de gramática.)
20. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring How do we make our content, technical writing, and documentation easy to read and enjoyable? ¿Cómo hacemos que nuestro contenido, escritura técnica y documentación sean fáciles y agradables de leer?
21. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring Creating friendly and welcoming writing. Creando escritura amistosa y acogedora.
22. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring Remember — 
 your readers aren’t you. Recordá — tus lectores no son vos.
23. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring
24. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring
25. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring
26. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring Write like a human, not a machine. Escribí como un ser humano, no como una máquina.
27. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring
28. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring
29. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring But… avoid cultural references since they won’t translate. Pero ... evitá las referencias culturales ya que no se traducirán.
30. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring
31. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring Requests is the only Non-GMO HTTP library for Python, safe for human consumption.
32. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring Try personas — create a character and write for them. Probá personas — creá un personaje y escribí para ellos.
33. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring "¿Qué tendría que saber Fred (un diseñador que trabaja en su primer proyecto de programación)?" “What would Fred (a designer working on his first programming project) need to know?”
34. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring
35. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring This document discusses using various kinds of authentication with Requests. Many web services require authentication, and there are many different types. Below, we outline various forms of authentication available in Requests, from the simple to the complex.
36. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring
37. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring Remember that terms that are obvious might not be obvious to others. Recordá que los términos que son evidentes para vos pueden no ser evidentes para los demás.
38. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring
39. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring “Cream the butter”
40. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring “Cream the butter” “Truss the bird”
41. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring “Cream the butter” “Truss the bird” “Fold the egg whites”
42. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring “Cream the butter” “Truss the bird” “Fold the egg whites” “Render the fat”
43. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring “Cream the butter” “Truss the bird” “Fold the egg whites” “Render the fat” “Shock the vegetables”
44. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring “Cream the butter” “Truss the bird” “Fold the egg whites” “Render the fat” “Shock the vegetables”
45. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring Link anything that you 
 don’t want to explain. Vinculá cualquier cosa que 
 no quieras explicar.
46. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring
47. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring To get someone started with your project: teach — don’t tell. Para que alguien comience con tu proyecto: enseñar — no decir. http://stevelosh.com/blog/2013/09/teach-dont-tell/
48. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring The son says: “Hey Dad, you said you were going to teach me how to drive after school today. Are we still going to do that?” The father, without looking up from his iPad, replies: “Of course, son. The car is in the garage and I laid out a set of wrenches on the workbench. Take the car apart and look at each piece, then put it back together. Once you’ve done that I’ll take you to the DMV for your driving test.”
49. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring Reading the source works for someone already familiar with your project. Your writing about your project and documentation needs to get them to that point. Leer la fuente funciona para alguien que ya está familiarizado con su proyecto. Tus artículos sobre el proyecto y tu documentación pueden ayudar el proceso de familiarización.
50. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring
51. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring Dumb things down 
 (without making them dumb.) Haz cosas más simples 
 (sin volverlas tontas.)
52. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring
53. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring
54. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring
55. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring
56. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring Use gender-neutral language. Utilizar un lenguaje neutro en función del género.
57. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring
58. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring Try to avoid pronouns or rewrite your sentences to use plural pronouns. Tratá de evitar los pronombres o reescribí sus oraciones para usar pronombres plurales. More: http://techwhirl.com/gender-neutral-technical-writing/
59. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring Overwhelmed? 1. Take a break. 2. Have a friend review your writing. ¿Abrumado? 1. Tomá un descanso. 2. Pedí a un amigo que revise su escritura.
60. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring The basics of 
 writing clearly. Los fundamentos de la escritura con claridad.
61. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring Cut down your content. 
 Two to three sentences per paragraph. Reducí tu contenido. 
 Dos a tres oraciones por párrafo.
62. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring Simplify your language. 
 Is there a more direct way to write the same thing? Simplificá su idioma. 
 ¿Hay una manera más directa de escribir lo mismo?
63. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring Original: It is important to note that you need to be very careful when modifying your source code. Simplified: Be careful when modifying your source code.
64. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring Break into bullets and use lots of headers. Make it easy to skim. Romper en balas y utilizar un montón de cabeceras. Hacer que sea fácil de roer.
65. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring Use italics and bolding to 
 break up paragraphs. Utilizá cursiva y negrita para 
 dividir los párrafos.
66. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring We made a bunch of changes: The registration chapter has been split in two, between adding registration and then associating users with objects. The chapter was giant before so this makes it more manageable. Screenshots of the admin have been updated to reflect the new Django 1.9 styles. The few minor typos have been fixed. Updated the version of django- registration-redux that we use to 1.3. Last but not least, the Introduction has been updated. We made a bunch of changes: • The registration chapter has been split in two, between adding registration and then associating users with objects. The chapter was giant before so this makes it more manageable. • Screenshots of the admin have been updated to reflect the new Django 1.9 styles. • The few minor typos have been fixed. • Updated the version of django-registration-redux that we use to 1.3. • Introduction has been updated.
67. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring We made a bunch of changes: • The registration chapter has been split in two, between adding registration and then associating users with objects. The chapter was giant before so this makes it more manageable. • Screenshots of the admin have been updated to reflect the new Django 1.9 styles. • The few minor typos have been fixed. • Updated the version of django-registration-redux that we use to 1.3. • Introduction has been updated. We made a bunch of changes: • The registration chapter has been split in two, between adding registration and then associating users with objects. The chapter was giant before so this makes it more manageable. • Screenshots of the admin have been updated to reflect the new Django 1.9 styles. • The few minor typos have been fixed. • Updated the version of django- registration-redux that we use to 1.3. • Introduction has been updated.
68. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring We made a bunch of changes: • The registration chapter has been split in two, between adding registration and then associating users with objects. The chapter was giant before so this makes it more manageable.
 • Screenshots of the admin have been updated to reflect the new Django 1.9 styles. 
 • The few minor typos have been fixed. • Updated the version of django- registration-redux that we use to 1.3. 
 • Introduction has been updated. We made a bunch of changes: The registration chapter has been split in two, between adding registration and then associating users with objects. The chapter was giant before so this makes it more manageable. Screenshots of the admin have been updated to reflect the new Django 1.9 styles. The few minor typos have been fixed. Updated the version of django- registration-redux that we use to 1.3. Last but not least, the Introduction has been updated.
69. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring Don’t forget your headlines. No olvides tustitulares.
70. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring
71. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring
72. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring
73. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring Mark up your code snippets to make sure they’re styled differently. Marcá sus fragmentos de código para asegurarse de que estén estilados de forma diferente.
74. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring
75. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring
76. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring Document with pictures. Documentá utilizando imágenes.
77. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring
78. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring
79. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring
80. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring
81. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring In conclusion… En conclusión…
82. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring Remember that your readers have different backgrounds and experiences than you. Recuerde que sus lectores tienen diferentes antecedentes y experiencias que usted.
83. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring Be friendly and write like a human. Sé amable y escribí como un ser humano.
84. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring Simplify. (applies to length, word choice and complexity, layout, everything.) Simplificá. (Se aplica a la longitud, elección de palabras y complejidad, diseño, todo.)
85. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring
86. NO DE CO NF ARGENTI NA T R AC Y O S B O R N @limedaring ¡Gracias! @limedaring