Joel on Software

Joel on Software   La Opinión de Joel sobre qué es Software

 

Otros artículos de "Joel on Software" en Español

Otros artículos de "Joel on Software" en Inglés

Envíele un Email al autor (solo en Inglés)

 

Especificaciones funcionales sin esfuerzo - Parte 4: Consejos


Por Joel Spolsky
Traducido por Miguel Cardo
Editado por Domingo Piña Maza
15 de octubre, 2000

Bueno, hemos hablado de por qué necesitas una especificación, qué contiene una especificación, y quién debería escribirlas. En esta cuarta y última parte de la serie, compartiré algunos de mis consejos para escribir buenas especificaciones.

La principal queja que uno puede oír de parte de los equipos que escriben especificaciones es que "nadie las lee". Cuando nadie lee las especificaciones, los que las escriben tienden a hacerse un poquito cínicos. Como la vieja tira de Dilbert en la que los ingenieros usan pilas de especificaciones de 4 pulgadas de grosor para construir extensiones a sus cubículos. En la típica empresa grande y burocrática, todo el mundo pasa meses y meses escribiendo aburridas especificaciones. Una vez está acabada, la especificación asciende a la estantería para no ser bajada nunca más, y el producto es implementado a partir de cero sin ninguna atención a lo que decía la especificación, porque nadie se leyó la especificación, porque le dejaba a uno tan atontado. El proceso mismo de escribir la especificación pudo haber sido un buen ejercicio, porque obligó a todos, por lo menos, a meditar la cuestión. Pero el hecho de que la especificación fue apartada (inédita y despreciada) cuando se terminó hace que la gente se sienta como si hubiera trabajado mucho para nada.

Así mismo, si tu especificación nunca se lee, tendrás muchas discusiones cuando se entregue el producto terminado. Alguien (la dirección, marketing, o un cliente) dice: ¡espera un momento!. ¡Me prometiste que habría un deshuesador de aceitunas! ¿Dónde está el deshuesador de aceitunas?" Y los programadores dicen, "no, en realidad, si miras la especificación, capítulo 3, sección 4, párrafo 2.3.0.1, verás que dice bastante explícitamente 'sin deshuesador de aceitunas'". Pero eso no satisface al cliente, quien siempre tiene razón, así que los gruñones de los programadores tienen que ponerse a integrar un deshuesador de aceitunas en el cacharro (haciéndolos aún más cínicos en todo lo que tiene que ver con las especificaciones). O un jefe dice, "eh, la forma de expresar este diálogo es demasiado prolija, y debería haber un anuncio en la parte de arriba de cada cuadro de diálogo". Y los programadores, frustrados, dicen: "¡pero usted aprobó la especificación que listaba exactamente el formato y los contenidos de cada cuadro de diálogo!" Pero, por supuesto, el jefe no había leído realmente la especificación, porque, cada vez que lo intentaba, su cerebro empezaba a licuarse por las órbitas de sus ojos, y, de todas formas, estaba interfiriendo con su partida de golf de los martes.

Pues eso. Las especificaciones son buenas, pero no si nadie las lee. Como redactor de especificaciones, tienes que engañar a la gente para que lea tus cosas, y probablemente deberías hacer un esfuerzo para no causar que ningún cerebro, ya demasiado pequeño, se filtre por las cuencas de los ojos.

Engañar a la gente para que lea tus cosas es simplemente, por lo común, cuesti󮠤e escribir bien. Pero no sería justo por mi parte decir solamente "sé un buen escritor" y dejarlo ahí. He aquí cuatro reglas sencillas que obligatoriamente debes seguir para hacer especificaciones que sean leídas.

Regla 1: Sé divertido

Sí, la regla número uno para engañar a la gente a que lea tu especificación es hacer la experiencia agradable. No me cuentes que no naciste gracioso, no me lo trago. Todo el mundo tiene ideas divertidas todo el rato, simplemente las autocensuran porque creen que es algo "poco profesional". Bah. Hay veces que tienes que romper las reglas.

Si lees las pilas de basura que he escrito en este sitio web, te darás cuentas que hay unos pocos y lamentables intentos de ser divertido repartidos por todo él. Sólo hace cuatro párrafos estaba haciendo un chiste asqueroso sobre fluidos corporales y mofándome de los jefes por jugar al golf. Incluso a pesar de que no soy tan gracioso, sigo intentándolo, y hasta el hecho de ir por ahí intentando ser gracioso es en sí divertido, al modo de un payaso triste. Cuando estés escribiendo una especificación, un buen sitio para ser gracioso son los ejemplos. Cada vez que necesites contar una historia sobre cómo funciona una característica, en lugar de decir:

  • El usuario pulsa Ctrl+N para crear una nueva tabla, Empleados, y comienza a introducir los nombres de los empleados.

escribe algo como:

  • La cerdita Peggy, golpeando las teclas con el pintalabios porque sus rechonchos deditos son demasiado gordos para poder apretar una sola tecla cada vez, pulsa Ctrl+N para crear una nueva tabla, Novios, y escribe el único registro "Gustavo".

Si lees mucho a Dave Barry, descubrirás que una de las formas más fáciles de ser gracioso es ser concreto cuando no es lo que se necesita. Los "chuchos sarnosos" son más graciosos que los "perros". "La cerdita Peggy" es más graciosa que "el usuario". En lugar de decir "grupos de presión", di "cultivadores zurdos de aguacate". En lugar de decir "Los que se niegan a limpiar lo que dejan sus perros deberían ser castigados", di que deberían "ser enviados a prisiones tan solitarias que los reclusos tienen que pagar a las arañas para obtener sexo".

Ah, por cierto, si crees que no es profesional ser divertido, lo siento, pero en ese caso simplemente no tienes sentido del humor. (No lo niegues. Los que carecen de sentido del humor siempre lo niegan. No me puedes engañar.) Y si trabajas en una compañía donde te respetarán menos porque tus especificaciones son joviales, divertidas, y agradables de leer, ve y encuentra otra compañía para la que trabajar, porque la vida es demasiado corta para gastar las horas del día en un sitio tan severo y desgraciado.

Regla 2: Escribir una especificación es como escribir código para que lo ejecute un cerebro

He aquí por qué creo que los programadores tienen problemas para escribir buenas especificaciones.

Cuando uno escribe código, su audiencia principal es el compilador. Sí, ya lo sé, hay gente que también tiene que leer código, pero normalmente es muy duro para ellos. Para la mayoría de los programadores ya es suficiente con conseguir que el código quede en un estado en el que el compilador lo lea y lo interprete correctamente; preocuparse de hacer código legible por los humanos es un lujo. Si escribes:

void print_count( FILE* a, char  *  b, int c ){
    fprintf(a, "hay %d %s\n", c, b);}

main(){ int n; n =
10; print_count(stdout, "empleados", n) /* código
deliberadamente ofuscado */ }

o

printf("hay 10 empleados\n");

obtienes la misma salida. Por esa misma razón, si piensas sobre ello, sueles encontrar programadores que escriben cosas como:

Sea una función, DireccionDe(x), que se define como la correspondencia de un usuario x, a la dirección de e-mail del usuario según RFC-822, una cadena ANSI. Sean el usuario A y el usuario B, donde A quiere enviar un e-mail al usuario B. Por tanto, el usuario A inicia un nuevo mensaje usando alguna (pero no todas) de las técnicas definidas en otra parte, y escribe DireccionDe(B) en el cuadro de edición Para:

Esto mismo podría haberse especificado como:

La cerdita Peggy quiere irse a almorzar, así que comienza un nuevo e-mail y escribe la dirección de la rana Gustavo en el cuadro "Para:".

Nota técnica: la dirección debe ser una dirección estándar de Internet (siguiendo RFC-822)

Ambas "significan" lo mismo, en teoría, quitando que el primer ejemplo es imposible de entender a no ser que lo descodifiques cuidadosamente, y el segundo ejemplo es fácil de entender. A menudo los programadores tratan de escribir especificaciones que parecen densos artículos académicos. Creen que una especificación "correcta" debe ser "técnicamente" correcta, y fallan estrepitosamente.

El error consiste en que, cuando uno escribe una especificación, además de ser correcta, ha de ser comprensible, lo cual, en términos de programación, significa que debe ser escrito de modo que el cerebro humano lo pueda "compilar". Una de las grandes diferencias entre ordenadores y cerebros humanos es que los ordenadores están dispuestos a quedarse esperando pacientemente mientras defines los términos que quieres usar más adelante. Pero los humanos no entenderán de qué estás hablando a no ser que les motives antes. Los seres humanos no quieren tener que descodificar algo, sólo quieren leerlo en orden y entenderlo. Para los seres humanos, tienes que proporcionar la visión general y entonces rellenarla con detalles. Con programas de ordenador, empiezas arriba y sigues hasta abajo del todo, dando detalles desde el principio. A un ordenador no le importa si los nombres de tus variables tienen sentido. Un cerebro humano entiende las cosas mucho mejor si puedes dibujar un cuadro vívido en su mente contándole una historia, incluso si tan solo es un fragmento de historia, porque nuestros cerebros han evolucionado para entender historias.

Si muestras un tablero de ajedrez a mitad de una partida a un jugador de ajedrez experimentado, aunque sólo sea durante uno o dos segundos, será capaz de memorizar instantáneamente la posición de cada pieza. Pero si mueves un par de piezas absurdamente, con movimientos que no podrían haber ocurrido en una partida normal (por ejemplo, pon algunos peones en la primera fila, o pon ambos alfiles negros en cuadros negros), entonces memorizar el tablero será mucho más difícil para él. Este caso es diferente de la forma en que piensan los ordenadores. Un programa de ordenador que pudiera memorizar un tablero de ajedrez podría memorizar con igual facilidad las posiciones posibles y las imposibles. La forma en que funciona el cerebro humano no es mediante accesso aleatorio; ciertas conexiones tienden a ser reforzadas en nuestros cerebros, y algunas cosas son más fáciles de recordar que otras simplemente porque son más comunes.

Así que, cuando estés escribiendo una especificación, intenta imaginar la persona a quien va dirigida, y trata de imaginar a cada paso lo que le estás pidiendo que entienda. Frase a frase, pregúntate si la persona que lea esta frase la entenderá en un sentido profundo, en el contexto de lo que ya les has contado. Si algunos miembros de tu audiencia objetivo no saben lo que es RFC-822, o bien lo defines, o, como mínimo, entierra la mención de RFC-822 en una nota técnica, así los ejecutivos que lean la especificación no abandonarán y dejarán de leer la primera vez que vean mucha jerga técnica.

Regla 3: Escribe tan sencillamente como te sea posible

No uses lenguaje afectado o formal porque pienses que es poco profesional escribir con frases sencillas. Usa el lenguaje más simple que puedas.

La gente usa palabras como "emplear" porque piensan que "usar" parece poco profesional. (Aquí tenemos de nuevo la expresión "poco profesional". Cuando alguien te dice que no deberías hacer algo porque es "poco profesional", ya sabes que se han quedado sin argumentos válidos.) De hecho, pienso que mucha gente cree que la escritura clara implica que algo no está bien.

Divide el texto en frases cortas. Si tienes problemas para escribir una frase de forma clara, divídela en dos o tres frases más cortas.

Evita los muros de texto: páginas completas sólo con texto. La gente se asusta y no las lee. ¿Cuándo fue la última vez que viste una revista popular o un periódico con páginas enteras de texto? Las revistas llegan hasta el punto de sacar una cita del artículo e imprimirla, en el centro de la página, en un tipo de letra gigante, solamente para evitar que parezca una página llena de texto. Usa listas numeradas, figuras, gráficas, tablas, y mucho espacio en blanco, para que la lectura "parezca" más fluida.

             

"Las revistas llegan hasta el punto de sacar una cita del artículo e imprimirla, en el centro de la página, en un tipo de letra gigante, solamente para evitar que parezca una página llena de texto"


 

Nada mejora una especificación más que montones y montones de capturas de pantalla. Una imagen puede valer mil palabras. Cualquiera que escriba especifiaciones para software sobre Windows debería invertir en una copia de Visual Basic, y aprender a usarlo por lo menos lo bastante bien como para crear maquetas de las pantalla. (Para el Mac, usa REAL Basic; para páginas Web, usa Front Page o Dreamweaver). Entonces captura esas pantallas (Ctrl+ImprPant) y pégalas en tu especificación.

Regla 4: Revisa y relee varia veces

Hum, bien, al principio había planeado tener aquí una larga exégesis de esta regla, pero es demasiado simple y obvia. Revisa y relee tu especificación varias veces, ¿de acuerdo?. Cuando encuentres una frase que no sea super fácil de entender, vuelve a escribirla.

He ahorrado tanto tiempo al no explicar la Regla 4 que voy a añadir otra regla.

Regla 5: Las plantillas se consideran dañinas

Evita la tentación de hacer una plantilla estándar para las especificaciones. Al principio puedes pensar que es importante que "todas las especificaciones tengan el mismo aspecto". Pista: no lo es. ¿Qué más da? ¿Tienen todos los libros de la estantería de tu casa exactamente el mismo aspecto? ¿Te gustaría que lo tuvieran?

Peor aún, si tienes plantillas, lo que tiende a ocurrir es que añades un manojo de secciones a la plantilla para cosas que crees que son importantes para cada función. Ejemplo: el Gran Bill decreta que, a partir de ahora, cada producto Microchof deberá tener un componente Internet. Así que la plantilla de las especificaciones ahora tiene una sección que dice: "Componente Internet". Cuando alguien escribe una especificación, no importa lo trivial que sea, tiene que rellenar esa sección llamada "Componente Internet", incluso si sólo está creando la especificación para el Teclado Microchof. (Y uno preguntándose por qué esos inútiles botones para comprar en Internet empezaron a salir como setas en los teclados).

Según se van acumulando estas secciones, la plantilla se hace bastante grande. (Aquí hay un ejemplo de una plantilla para especificaciones muy, muy mala. ¿Quién necesita una bibliografía en una especificación, por los clavos de Cristo? ¿O un glosario?) El problema con una plantilla tan grande es que escribir especificaciones asusta a la gente, pues parece una tarea tan desmoralizante.

Una especificación es un documento que quieres que lea la gente. En ese sentido, no es diferente de un ensayo en The New Yorker o de un trabajo para la universidad. ¿Has oído alguna vez de un profesor que pase plantillas para que los estudiantes escriban sus trabajos? ¿Has leído alguna vez dos buenos ensayos que pudieran encajar en una misma plantilla? Olvídate de la idea.



Esté articulo apareció originalmente en Inglés con el nombre Painless Functional Specifications Part 4  

Joel Spolsky es el fundador de Fog Creek Software, una pequeña empresa de software en Nueva York. Es titulado por la Universidad de Yale y ha trabajado como programador y gerente en Microsoft, Viacom, y Juno.


El contenido de estas páginas representan la opinión de una persona.
Todo el contenido es Copyright ©1999-2005  por Joel Spolsky. Todos los derechos son reservados.

FogBUGZ | CityDesk | Fog Creek Software | Joel Spolsky