On Writing Friendly and Welcoming Documentation / PyCaribbean

Slide 1

Slide 1 text

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.

Slide 2

Slide 2 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring ¡Hola, soy Tracy! @limedaring (daring, not darling)

Slide 3

Slide 3 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring

Slide 4

Slide 4 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring

Slide 5

Slide 5 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring

Slide 6

Slide 6 text

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.

Slide 7

Slide 7 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring

Slide 8

Slide 8 text

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.

Slide 9

Slide 9 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring

Slide 10

Slide 10 text

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

Slide 11

Slide 11 text

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

Slide 12

Slide 12 text

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

Slide 13

Slide 13 text

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

Slide 14

Slide 14 text

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

Slide 15

Slide 15 text

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

Slide 16

Slide 16 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring We’re chatting content, not design   (and deﬁnitely not grammar.) Estamos hablando de contenido, no de diseño (y deﬁnitivamente no de gramática.)

Slide 17

Slide 17 text

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?

Slide 18

Slide 18 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring Creating friendly and welcoming writing. Creando escritura amistosa y acogedora.

Slide 19

Slide 19 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring Remember —   your readers aren’t you. Recordá — tus lectores no son vos.

Slide 20

Slide 20 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring

Slide 21

Slide 21 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring

Slide 22

Slide 22 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring

Slide 23

Slide 23 text

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.

Slide 24

Slide 24 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring

Slide 25

Slide 25 text

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.

Slide 26

Slide 26 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring

Slide 27

Slide 27 text

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.

Slide 28

Slide 28 text

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.

Slide 29

Slide 29 text

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 ﬁrst programming project) need to know?”

Slide 30

Slide 30 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring

Slide 31

Slide 31 text

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 diﬀerent types. Below, we outline various forms of authentication available in Requests, from the simple to the complex.

Slide 32

Slide 32 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring

Slide 33

Slide 33 text

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.

Slide 34

Slide 34 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring

Slide 35

Slide 35 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring “Cream the butter”

Slide 36

Slide 36 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring “Cream the butter” “Truss the bird”

Slide 37

Slide 37 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring “Cream the butter” “Truss the bird” “Fold the egg whites”

Slide 38

Slide 38 text

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”

Slide 39

Slide 39 text

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”

Slide 40

Slide 40 text

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”

Slide 41

Slide 41 text

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.

Slide 42

Slide 42 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring

Slide 43

Slide 43 text

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/

Slide 44

Slide 44 text

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.”

Slide 45

Slide 45 text

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.

Slide 46

Slide 46 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring

Slide 47

Slide 47 text

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.)

Slide 48

Slide 48 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring

Slide 49

Slide 49 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring

Slide 50

Slide 50 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring

Slide 51

Slide 51 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring

Slide 52

Slide 52 text

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.

Slide 53

Slide 53 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring

Slide 54

Slide 54 text

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/

Slide 55

Slide 55 text

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.

Slide 56

Slide 56 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring The basics of   writing clearly. Los fundamentos de la escritura con claridad.

Slide 57

Slide 57 text

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.

Slide 58

Slide 58 text

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? Simpliﬁcá su idioma.   ¿Hay una manera más directa de escribir lo mismo?

Slide 59

Slide 59 text

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. Simpliﬁed: Be careful when modifying your source code.

Slide 60

Slide 60 text

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.

Slide 61

Slide 61 text

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.

Slide 62

Slide 62 text

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.

Slide 63

Slide 63 text

Slide 64

Slide 64 text

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.

Slide 65

Slide 65 text

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.

Slide 66

Slide 66 text

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.

Slide 67

Slide 67 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring Don’t forget your headlines. No olvides tustitulares.

Slide 68

Slide 68 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring

Slide 69

Slide 69 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring

Slide 70

Slide 70 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring

Slide 71

Slide 71 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring Document with pictures. Documentá utilizando imágenes.

Slide 72

Slide 72 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring

Slide 73

Slide 73 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring

Slide 74

Slide 74 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring

Slide 75

Slide 75 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring

Slide 76

Slide 76 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring In conclusion… En conclusión…

Slide 77

Slide 77 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring Remember that your readers have diﬀerent backgrounds and experiences than you. Recuerde que sus lectores tienen diferentes antecedentes y experiencias que usted.

Slide 78

Slide 78 text

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.

Slide 79

Slide 79 text

PYCARIBBEAN T R AC Y O S B O R N @limedaring Simplify. (applies to length, word choice and complexity, layout, everything.) Simpliﬁcá. (Se aplica a la longitud, elección de palabras y complejidad, diseño, todo.)