On Writing Friendly and Welcoming Documentation / PyCaribbean

Transcript

1. PYCARIBBEAN 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. PYCARIBBEAN T R AC Y O S B O R N @limedaring ¡Hola, soy Tracy! @limedaring (daring, not darling)
3. PYCARIBBEAN T R AC Y O S B O R N @limedaring
4. PYCARIBBEAN T R AC Y O S B O R N @limedaring
5. PYCARIBBEAN T R AC Y O S B O R N @limedaring
6. PYCARIBBEAN 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.
7. PYCARIBBEAN T R AC Y O S B O R N @limedaring
8. PYCARIBBEAN 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.
9. PYCARIBBEAN T R AC Y O S B O R N @limedaring
10. PYCARIBBEAN 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
11. PYCARIBBEAN 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
12. PYCARIBBEAN 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
13. PYCARIBBEAN 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. PYCARIBBEAN 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
15. PYCARIBBEAN 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. PYCARIBBEAN 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.)
17. PYCARIBBEAN 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?
18. PYCARIBBEAN T R AC Y O S B O R N @limedaring Creating friendly and welcoming writing. Creando escritura amistosa y acogedora.
19. PYCARIBBEAN T R AC Y O S B O R N @limedaring Remember — 
 your readers aren’t you. Recordá — tus lectores no son vos.
20. PYCARIBBEAN T R AC Y O S B O R N @limedaring
21. PYCARIBBEAN T R AC Y O S B O R N @limedaring
22. PYCARIBBEAN T R AC Y O S B O R N @limedaring
23. PYCARIBBEAN 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.
24. PYCARIBBEAN T R AC Y O S B O R N @limedaring
25. PYCARIBBEAN 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.
26. PYCARIBBEAN T R AC Y O S B O R N @limedaring
27. PYCARIBBEAN 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.
28. PYCARIBBEAN 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.
29. PYCARIBBEAN 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?”
30. PYCARIBBEAN T R AC Y O S B O R N @limedaring
31. PYCARIBBEAN 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.
32. PYCARIBBEAN T R AC Y O S B O R N @limedaring
33. PYCARIBBEAN 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.
34. PYCARIBBEAN T R AC Y O S B O R N @limedaring
35. PYCARIBBEAN T R AC Y O S B O R N @limedaring “Cream the butter”
36. PYCARIBBEAN T R AC Y O S B O R N @limedaring “Cream the butter” “Truss the bird”
37. PYCARIBBEAN T R AC Y O S B O R N @limedaring “Cream the butter” “Truss the bird” “Fold the egg whites”
38. PYCARIBBEAN T R AC Y O S B O R N @limedaring “Cream the butter” “Truss the bird” “Fold the egg whites” “Render the fat”
39. PYCARIBBEAN 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”
40. PYCARIBBEAN 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”
41. PYCARIBBEAN 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.
42. PYCARIBBEAN T R AC Y O S B O R N @limedaring
43. PYCARIBBEAN 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/
44. PYCARIBBEAN 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.”
45. PYCARIBBEAN 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.
46. PYCARIBBEAN T R AC Y O S B O R N @limedaring
47. PYCARIBBEAN 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.)
48. PYCARIBBEAN T R AC Y O S B O R N @limedaring
49. PYCARIBBEAN T R AC Y O S B O R N @limedaring
50. PYCARIBBEAN T R AC Y O S B O R N @limedaring
51. PYCARIBBEAN T R AC Y O S B O R N @limedaring
52. PYCARIBBEAN 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.
53. PYCARIBBEAN T R AC Y O S B O R N @limedaring
54. PYCARIBBEAN 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/
55. PYCARIBBEAN 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.
56. PYCARIBBEAN T R AC Y O S B O R N @limedaring The basics of 
 writing clearly. Los fundamentos de la escritura con claridad.
57. PYCARIBBEAN 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.
58. PYCARIBBEAN 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?
59. PYCARIBBEAN 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.
60. PYCARIBBEAN 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.
61. PYCARIBBEAN 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.
62. PAGERDU T Y T RAC Y O S B OR N @limedaring Please note that although Chrome is supported for both Mac and Windows operating systems, it is recommended that all users of this site switch to the most up-to-date version of the Firefox web browser for the best possible results.
63. PAGERDU T Y T RAC Y O S B OR N @limedaring Please note that although Chrome is supported for both Mac and Windows operating systems, it is recommended that all users of this site switch to the most up-to-date version of the Firefox web browser for the best possible results. For best results, use the latest version of Firefox. Chrome for Mac and Windows is also supported.
64. PYCARIBBEAN 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.
65. PYCARIBBEAN 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.
66. PYCARIBBEAN 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.
67. PYCARIBBEAN T R AC Y O S B O R N @limedaring Don’t forget your headlines. No olvides tustitulares.
68. PYCARIBBEAN T R AC Y O S B O R N @limedaring
69. PYCARIBBEAN T R AC Y O S B O R N @limedaring
70. PYCARIBBEAN T R AC Y O S B O R N @limedaring
71. PYCARIBBEAN T R AC Y O S B O R N @limedaring Document with pictures. Documentá utilizando imágenes.
72. PYCARIBBEAN T R AC Y O S B O R N @limedaring
73. PYCARIBBEAN T R AC Y O S B O R N @limedaring
74. PYCARIBBEAN T R AC Y O S B O R N @limedaring
75. PYCARIBBEAN T R AC Y O S B O R N @limedaring
76. PYCARIBBEAN T R AC Y O S B O R N @limedaring In conclusion… En conclusión…
77. PYCARIBBEAN 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.
78. PYCARIBBEAN 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.
79. PYCARIBBEAN 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.)
80. PYCARIBBEAN T R AC Y O S B O R N @limedaring
81. PYCARIBBEAN T R AC Y O S B O R N @limedaring ¡Gracias! @limedaring