2007-09-13 22:04:25

Especificaciones Funcionales sin esfuerzo

Parte 1: �Por qu� molestarse?

http://spanish.joelonsoftware.com/PainlessSpecs/1.html
Por Joel Spolsky
Traducido por Miguel Cardo
Editado por Domingo Pi�a Maza
2 de octubre, 2000

Cuando El Test de Joel apareci�, uno de los asuntos m�s espinosos denunciados por los lectores estaba relacionado con con escribir especificaciones. Parece que las especificaciones son como pasarse la seda dental: todo el mundo sabe que deber�a estar escribi�ndolas, pero nadie lo hace.

�Por qu� no se escriben especificaciones? Dicen que porque salt�ndose la fase de escritura de especificaciones se ahorra tiempo. Se comportan como si la escritura de especificaciones fuese un lujo reservado a los ingenieros de lanzaderas de la NASA, o a los que trabajan para gigantescas compa��as de seguros. Chorradas. Para empezar, dejar de escribir una especificaci�n es el mayor riesgo a que uno se expone, sin necesidad, en un proyecto software. Es tan est�pido como lanzarse a recorrer el desierto del Mojave s�lo con la ropa que uno lleva puesta por todo equipo, esperando “cruzarlo de un salto”. Aquellos programadores e inform�ticos que se sumergen en el c�digo sin haber escrito una especificaci�n tienden a pensar que son pistoleros de nervios de acero, pegando tiros desde la cintura. No lo son. Son tremendamente improductivos. Escriben mal c�digo y producen un software mediocre, poniendo en peligro sus proyectos por exponerse a riesgos gigantescos, que nadie les hab�a pedido.

Creo que, en cualquier proyecto no trivial (m�s de una semana de codificaci�n o m�s de un programador), si no dispones de una especificaci�n, gastar�s m�s tiempo y crear�s c�digo de peor calidad. Aqu� est� el porqu�.

La funci�n m�s importante de una especificaci�n es dise�ar el programa. Incluso si eres el �nico trabajando en el c�digo, y escribes una especificaci�n solamente para tu propio beneficio, el acto de escribirla — describiendo minuciosamente c�mo funciona el programa — te obligar� a dise�arlo de verdad.

Visitemos a dos programadores imaginarios, en dos compa��as. Juan Veloz, de Bananas Raudas Software, nunca escribe especificaciones. "�Especificaciones? �No necesitamos esa mierda!". Al mismo tiempo, Mister Rogers, en La Compa��a del Software Bien Temperado, se niega a escribir c�digo hasta que la especificaci�n haya sido concretada por completo (estos son solamente dos de mis muchos amigos imaginarios).

Juan Veloz y Mr. Rogers tienen algo en com�n: ambos est�n a cargo de la compatibilidad hacia atr�s de la versi�n 2.0 de sus respectivos productos.

Juan Veloz decide que la mejor forma de proporcionar compatibilidad hacia atr�s consiste en escribir un conversor, que simplemente convierte los archivos de la versi�n 1.0 en archivos de la versi�n 2.0. Se pone a machacarlo. Teclea, teclea y teclea. Clic-clac-clac. Los discos duros giran. Vuela el polvo. Al cabo de unas dos semanas, tiene un conversor decente. Pero sus clientes han quedado descontentos. El c�digo de Juan Veloz obligar� a todos los empleados de la compa��a a actualizarse a la nueva versi�n. Su mayor cliente, Nanner Splits Unlimited, se niega a comprar el nuevo software. Nanner Splits necesita saber que la versi�n 2.0 todav�a ser� capaz de funcionar con archivos de la versi�n 1.0 sin tener que convertirlos. Juan Veloz decide programar un conversor hacia atr�s y enlazarlo a la funci�n “guardar”. Es un poco ca�tico, porque, al usar una funci�n de la versi�n 2.0, parece que funciona, hasta que te pones a guardar el archivo en formato 1.0. S�lo en ese momento se te dice que la funci�n que estabas usando media hora antes no funciona en el formato antiguo. As� que escribir el conversor hacia atr�s llev� otras dos semanas, y no funciona nada bien. Tiempo transcurrido, 4 semanas.

Ahora bien, Mr. Rogers, el de La Compa��a del Software Bien Temperado, es uno de esos tipos repelentes de tan organizados, que se niega en redondo a escribir c�digo hasta que no tiene una especificaci�n. Dedica 20 minutos a dise�ar la caracter�stica de compatibilidad hacia atr�s de la misma forma que Juan Veloz, y nos sale con una especificaci�n que b�sicamente dice:

- Al abrir un archivo creado con una versi�n anterior del producto, el archivo es convertido al nuevo formato.

La especificaci�n se muestra al cliente, quien dice: "�Espera un momento! �No queremos cambiar a todo el mundo a la vez!" As� que Mr. Rogers est� otro rato pensando, y corrige la especificaci�n para decir:

- Al abrir un archivo creado con una versi�n anterior del producto, el archivo es convertido al nuevo formato en memoria. Al guardar el archivo, se presenta al usuario la opci�n de volver a la versi�n antigua.

Han pasado otros 20 minutos.

El jefe de Mr. Rogers, un pirado de los objetos, lo mira y sospecha que algo podr�a ir mal. Sugiere una arquitectura distinta.

- El c�digo ser� construido de modo que utilice dos interfaces: V1 y V2. V1 contiene todas las funciones de la versi�n 1.0, y V2, que hereda de V1, a�ade todas las funciones nuevas. Entonces, V1::Guardar puede ocuparse de la compatibilidad hacia atr�s, mientras que V2::Guardar puede usarse para guardar las nuevas cosas. Si has abierto un archivo V1 e intentas usar la funcionalidad de V2, el programa puede avisarte en ese mismo momento, y tendr�s que elegir entre convertir el archivo o renunciar a la nueva funcionalidad.

20 minutos m�s.

A Mr. Rogers no le hace ninguna gracia. Este redise�o llevar� 3 semanas, �en lugar de las 2 semanas que estim� al principio! Pero resuelve todos los problemas del cliente, y de una forma elegante, as� que se pone manos a la obra y lo hace.

Tiempo transcurrido para Mr. Rogers: 3 semanas y 1 hora, en total. Para Juan Veloz: 4 semanas, pero su c�digo no es tan bueno.

La moraleja de la historia es que, con un ejemplo inventado, uno puede probar cualquier cosa. Uy. No, eso no es lo que quer�a decir. La moraleja de la historia es que, cuando dise�as tu producto en un lenguaje humano, s�lo lleva unos minutos el tratar de pensar en varias posibilidades, revisar y mejorar tu dise�o. Nadie se siente mal cuando borra un p�rrafo en un procesador de textos. Pero, cuando dise�as tu producto en un lenguaje de programaci�n, lleva semanas hacer una iteraci�n del dise�o. Y lo que es peor, un programador que acaba de pasar 2 semanas escribiendo algo de c�digo se va a sentir bastante identificado con ese c�digo, da igual lo mal que est�. Nada que pudieran decir el jefe de Juan Veloz o sus clientes le convencer�a de tirar su precioso c�digo conversor, incluso aunque no sea la mejor arquitectura. Como resultado, el producto final tiende a ser un compromiso entre el dise�o inicial, incorrecto, y el dise�o ideal. Era «el mejor dise�o que pod�amos conseguir, dado que ya hab�amos escrito todo este c�digo y no quer�amos tirarlo.» No tan bueno como «el mejor dise�o que pudimos conseguir y punto».

As� que esa es la raz�n principal n�mero uno para escribir una especificaci�n. La raz�n principal n�mero dos es ahorrar tiempo de comunicaci�n. Cuando escribes una especificaci�n, s�lo tienes que comunicar c�mo se supone que funciona el programa una vez. Basta con que todos los del equipo lean la especificaci�n. La gente de Calidad la lee, de forma que saben c�mo se supone que funciona el programa y para qu� tienen que hacer las pruebas. Los de marketing la usan para escribir sus vagas «hojas de caracter�sticas» para poner en la web, sobre productos que a�n no han sido creados. Los de desarrollo de negocio la malinterpretan para destilar extra�as fantas�as sobre c�mo el producto curar� la calvicie, las verrugas y dem�s, pero atrae inversores, as� que est� bien. Los desarrolladores la leen para saber qu� c�digo escribir. Los clientes la leen para asegurarse de que los desarrolladores est�n construyendo un producto por el que querr�an pagar dinero. Los redactores t�cnicos la leen y escriben un bonito manual (que se pierde o se tira, pero eso es otra historia). Los jefes la leen de modo que pueden aparentar en las reuniones de jefes que saben de qu� va la historia. Y as� sucesivamente.

Cuando no tienes una especificaci�n, toda esta comunicaci�n sigue ocurriendo, porque tiene que haberla, pero es ad hoc. Los de Calidad juguetean un poco con el programa, y, cuando algo les parece extra�o, van e interrumpen a los programadores una vez m�s para preguntarles otra estupidez sobre c�mo se supone que funciona la cosa. Adem�s del hecho de que esto arruina la productividad de los programadores, los programadores tienden a dar la respuesta que se corresponde con lo que escribieron en el c�digo, en lugar de la “respuesta correcta”. As� que los de Calidad est�n en realidad probando el programa contra el programa en lugar de probar el programa contra el dise�o, lo cual ser�a, ejem, un poco m�s �til.

Cuando no dispones de una especificaci�n, lo que ocurre con los pobres redactores t�cnicos es lo m�s divertido (tristemente hablando). Normalmente, los redactores t�cnicos no tienen tanta influencia pol�tica como para poder interrumpir a los programadores. En muchas compa��as, si los redactores t�cnicos caen en el h�bito de interrumpir a los programadores para preguntarles c�mo se supone que funciona algo, los programadores van a sus jefes y les lloran sobre c�mo son incapaces de terminar nada por culpa de estos [calificativo borrado] redactores, y si podr�an por favor mantenerles lejos, y los jefes, tratando de mejorar la productividad, proh�ben a los redactores t�cnicos desperdiciar ni un segundo m�s del precioso tiempo de sus programadores. Es f�cil saber de qu� compa��as se trata, pues los ficheros de ayuda y los manuales no te dan ninguna informaci�n que no puedas deducir de la pantalla. Cuando ves un mensaje en la pantalla que dice:

- �Desea activar el soporte LRF-1914?

... y haces click en “Ayuda”, aparece un tema de ayuda tragic�mico que dice algo como

- Le permite elegir entre tener soporte LRF-1914 (por defecto) o no tener soporte LRF-1914. Si desea soporte LRF-1914, elija «S�» o pulse “S”. Si no desea soporte LRF-1914, elija “No” o pulse “N”.

Ejem, gracias. Aqu� est� bastante claro que el redactor t�cnico estaba tratando de ocultar el hecho de que no sab�an qu� es el soporte LRF-1914. No pudieron preguntar al programador, porque (a) les daba verg�enza, o (b) el programador est� en Hyderabad y ellos en Londres, o (c) la direcci�n les ha prohibido interrumpir al programador, o cualquiera de otras patolog�as corporativas demasiado numerosas para mencionar aqu�, pero el problema fundamental es que no hab�a especificaci�n.

La raz�n principal n�mero tres para tener una especificaci�n es que, sin una especificaci�n detallada, es imposible hacer una planificaci�n temporal. No tener un plan de tiempos est� bien si se trata de tu tesis y esperas dedicarte a ella durante 14 a�os, o si eres un programador trabajando en el pr�ximo Duke Nukem y lo distribuiremos cuando estemos listos. Pero, para casi cualquier clase de negocio real, simplemente tienes que saber cu�nto tiempo van a llevar las cosas, porque desarrollar un producto cuesta dinero. T� no comprar�as un par de vaqueros sin saber cu�l es el precio, as� que �c�mo va a decidir una empresa responsable si desarrolla un producto sin saber cu�nto se va a tardar, y por tanto, cu�nto costar�? Para saber m�s sobre planificaci�n temporal, lee Planificaci�n Indolora de Proyectos de Software.

Un error tremendamente com�n es tener una discusi�n sobre c�mo deber�a dise�arse algo, y no llegar nunca a una conclusi�n. Brian Valentine, el dise�ador jefe de Windows 2000, era famoso por su lema «Las decisiones, en 10 minutos o menos, o la pr�xima es gratis».

En demasiadas organizaciones dedicadas a la programaci�n, cada vez que se discute un dise�o, jam�s consigue nadie llegar a una decisi�n, normalmente por razones pol�ticas. Por tanto, los programadores solamente trabajan en lo menos controvertido. Seg�n va pasando el tiempo, todas las decisiones duras se dejan para el final. Estos son los proyectos que m�s probablemente fracasen. Si est�s creando una nueva compa��a basada en una tecnolog�a nueva y notas que tu compa��a es constitucionalmente incapaz de tomar decisiones, podr�as perfectamente cerrarla ahora y devolver el dinero a los inversores, porque nunca distribuir�s nada.

Escribir una especificaci�n es un gran modo de fijar todas esas molestas decisiones de dise�o, grandes y peque�as, que quedan disimuladas si no tienes una especificaci�n. Incluso las decisiones de poca entidad pueden quedar fijadas por una especificaci�n. Por ejemplo, si est�is construyendo un sitio web en el que la gente se puede dar de alta, todos pod�is estar de acuerdo en que, si un usuario pierde su contrase�a, se la enviar�is por e-mail. Magn�fico. Pero no es suficiente para escribir el c�digo. Para escribir el c�digo, necesitas saber las palabras precisas que ir�n en el e-mail. En la mayor�a de las empresas, a los programadores no se les conf�an palabras que un usuario pudiera llegar a ver (y por buenas razones, la mayor parte de las veces). Por tanto, es probable que alguien de marketing o relaciones p�blicas o que haya estudiado filolog�a sea requerido para que defina el texto preciso del mensaje. «Estimado Patoso, aqu� est� la contrase�a que olvid�. Trate de ser menos descuidado en el futuro». Cuando te fuerzas a escribir una especificaci�n buena y completa (y pronto hablar� mucho m�s sobre ello), te das cuenta de todas estas cosas y o bien las arreglas o bien las marcas con una buena se�al roja.

Bien. Ya estamos en la misma p�gina. Las especificaciones son la maternidad, o la paella de los domingos. Sospecho que la mayor�a de la gente lo entiende, y mis sermones, siendo graciosos, no te est�n ense�ando nada nuevo. As� que, �por qu� la gente no escribe especificaciones? No es para ahorrar tiempo, porque no lo ahorra, y creo que la mayor�a de los programadores lo reconoce. (En la mayor�a de las organizaciones, las �nicas “especificaciones” que existen son cort�simas, una p�gina de texto que un programador escribi� en el Bloc de Notas despu�s de escribir el c�digo y despu�s de explicar la maldita funci�n a la persona n�mero 300).

Creo que la raz�n es porque a mucha gente no le gusta escribir. Mirar una pantalla en blanco es algo horriblemente frustrante. Personalmente, super� mi miedo a escribir apunt�ndome a una asignatura en la universidad en la que hab�a que presentar un ensayo de 3 a 5 p�ginas una vez por semana. La escritura es un m�sculo. Cuanto m�s escribes, m�s eres capaz de escribir. Si necesitas escribir especificaciones y no eres capaz, empieza un diario, crea un weblog, ap�ntate a una clase de escritura creativa, o simplemente escribe una bonita carta a cada uno de los parientes y compa�eros de habitaci�n que dejaste escapar en los �ltimos 4 a�os. Cualquier cosa que tenga que ver con colocar palabras sobre papel mejorar� tu habilidad de escritura de especificaciones. Si eres un jefe de desarrollo de software y la gente que se supone deber�a estar escribiendo especificaciones no lo hace, env�alos a uno de esos seminarios de escritura creativa de dos semanas en la monta�a.

Si nunca has trabajado en una compa��a que haga especificaciones funcionales, puede que nunca hayas visto una. En la pr�xima parte de esta serie, te mostrar� una breve especificaci�n de ejemplo para que lo compruebes, y hablaremos de lo que una buena especificaci�n necesita tener.

Parte 2: �Qu� es una especificaci�n?

http://spanish.joelonsoftware.com/PainlessSpecs/2.html
Por Joel Spolsky
Traducido por Miguel Cardo
Editado por Domingo Pi�a Maza
3 de octubre, 2000

(�Has le�do ya la primera parte? Si no, est� aqu�.)

Esta serie de art�culos trata sobre especificaciones funcionales, no t�cnicas. Hay gente que las confunde. No s� si hay una terminolog�a est�ndar, pero esto es lo que yo quiero decir cuando uso estos t�rminos:

1. Una especificaci�n funcional describe c�mo funcionar� un producto completamente desde la perspectiva del usuario. No le importa c�mo se implemente la cosa. Habla de funciones. Especifica pantallas, men�s, di�logos, etc�tera.
2. Una especificaci�n t�cnica describe la implementaci�n interna del programa. Habla de estructuras de datos, modelos de bases de datos relacionales, elecci�n de lenguajes y herramientas de programaci�n, algoritmos, etc.

Cuando uno dise�a un producto, por dentro y por fuera, lo m�s importante es fijar la percepci�n que tenga el usuario. Cu�les son las pantallas, c�mo funcionan, qu� hacen. M�s tarde, te preocupas de c�mo llegar de un sitio al otro. No sirve de nada discutir sobre qu� lenguaje de programaci�n usar antes de haber decidido qu� es lo que va a hacer tu producto. En esta serie de art�culos, s�lo hablo de especificaciones funcionales.

He escrito una peque�a especificaci�n de ejemplo que deber�a darte una idea de la aspecto que tiene una buena especificaci�n funcional. Antes de seguir, por favor lee la especificaci�n de ejemplo.

�La has le�do?

No, no la has le�do. Ve a leerla ahora y vuelve cuando lo hayas hecho, para que podamos hablar m�s de lo que una buena especificaci�n debe y no debe tener. Estar� aqu� esper�ndote. Gracias.

(esperando pacientemente...)

Ah, bien. Ya est�s de vuelta.

He aqu� algunas de las cosas que pongo en toda especificaci�n.

Una nota de aviso. Pura autodefensa. Si pones un p�rrafo que diga algo como «Esta especificaci�n no est� terminada», la gente no invadir� tu oficina para arrancarte la cabeza de un mordisco. Seg�n pase el tiempo, cuando la especificaci�n vaya estando terminada, puedes cambiarla a «esta especificaci�n est� terminada, seg�n mi mejor ciencia y conciencia, pero, si he olvidado algo, ind�camelo, por favor». Lo cual me recuerda que toda especificaci�n necesita:

Un autor. Algunas empresas opinan que la especificaci�n deber�a ser escrita por un equipo. Si has probado alguna vez a escribir en grupo, sabr�s que no hay peor tortura. Deja la escritura en grupo a las firmas de consultor�a de direcci�n, con sus ej�rcitos de diplomados por Harvard reci�n salidos del horno, quienes necesitan hacer monta�as de trabajo para poder justificar sus enormes tarifas. Tus especificaciones deber�an ser propiedad de, y escritas por, una persona. Si tienes un producto demasiado grande, div�delo en �reas y entrega cada �rea a una persona diferente, para que lo especifiquen por separado. Otras compa��as opinan que es ego�sta o mal “trabajo en equipo” el que una persona se «apropie del m�rito” de una especificaci�n por poner su nombre en ella. Tonter�as. La gente deber�a tener la responsabilidad y la propiedad de las cosas que especifica. Si algo est� mal en la especificaci�n, deber�a haberse nombrado un due�o de la especificaci�n, responsable de arreglarlo.

Escenarios. Cuando est�s dise�ando un producto, necesitas tener en mente algunos escenarios reales que representen c�mo lo va a usar la gente. De otra manera acabar�s dise�ando un producto que no se corresponde con ning�n uso real (como el Cue?Cat). Escoge los grupos de audiencia de tu producto e imagina un usuario ficticio, totalmente imaginario pero a la vez totalmente estereotipo de cada grupo, quien utiliza el producto de una forma totalmente t�pica. El Cap�tulo 9 de mi libro de dise�o de Interfaces de Usuario (disponible gratis online) habla sobre la creaci�n de usuarios ficticios y escenarios. Que son el lugar donde los colocas. Cuanto m�s v�vido y realista sea el escenario, mejor trabajo har�s dise�ando un producto para tus usuarios reales e imaginarios, por lo que tiendo a poner muchos detalles inventados.

No objetivos. Mientras se est� desarrollando un producto con un equipo, todo el mundo tiende a tener su funci�n favorita (real o imaginaria), sin la cual no pueden vivir. Si las haces todas, te llevar� un tiempo infinito y costar� demasiado dinero. Tienes que eliminar funciones innecesarias enseguida, y la mejor forma de hacerlo es con una secci�n de la especificaci�n que se puede llamar “no objetivos”. Cosas que no vamos a hacer. Un no-objetivo puede ser una funci�n que no piensas incluir ("�nada de interfaz telep�tico de usuario!”) o algo m�s general («En esta versi�n no vamos a preocuparnos del rendimiento. El producto puede ser lento, siempre que funcione. Si para la versi�n 2 tenemos tiempo, optimizaremos los trozos m�s lentos.”) Es probable que estos no-objetivos causen alguna discusi�n, pero es importante afrontarla abiertamente lo antes posible. "�No lo voy a hacer!”, como dec�a George Bush padre.

Una visi�n general. Es como el �ndice de tu especificaci�n. Puede ser un simple diagrama de flujo, o bien una extensa discusi�n de la arquitectura del producto. Todo el mundo la debe leer para hacerse una idea de conjunto, a partir de ella los detalles tendr�n m�s sentido.

Detalles, detalles, detalles. Finalmente, te metes en los detalles. La mayor�a lo leer� por encima hasta que necesiten saber un detalle concreto. Cuando uno est� dise�ando un servicio de tipo web, una buena forma de hacerlo es dando a todas las posibles pantallas un nombre can�nico, y escribiendo un cap�tulo que describa cada una de ellas con un nivel de detalle tan minucioso que nuble el entendimiento.

Los detalles son lo m�s importante en una especificaci�n funcional. Te habr�s dado cuenta de c�mo, en la especificaci�n de ejemplo, entro en un nivel de detalle exagerado para todos los casos de error de la p�gina de login. �Qu� pasa si la direcci�n de e-mail no es v�lida? �Qu� pasa si la constrase�a est� mal? Todos estos casos se corresponden con c�digo real que va a ser escrito, pero, lo que es m�s importante, estos casos corresponden a decisiones que alguien va a tener que tomar. Alguien tiene que decidir cu�l ha de ser la pol�tica a seguir en el caso de una contrase�a olvidada. Si no lo decides, no puedes escribir el c�digo. La especificaci�n necesita documentar la decisi�n.

Asuntos pendientes. No pasa nada por dejar asuntos pendientes en la primera versi�n de una especificaci�n. Cuando yo escribo un primer borrador, siempre me quedan muchos asuntos pendientes, pero los se�alo (usando un estilo especial para poder buscarlos luego) y, si viene a cuento, presento las alternativas. Cuando llega el momento en que los programadores empiezan su trabajo, todos ellos deben ser liquidados. (Alguien podr�a pensar que basta con dejar que los programadores empiecen con lo f�cil, y resolver los asuntos pendientes m�s tarde. Mala idea. Ya tendr�s bastantes problemas resolviendo los nuevos asuntos que surjan cuando los programadores intenten implementar el c�digo, sin que est�n todav�a por ah� los viejos asuntos pendientes que ya conoc�as por adelantando y que pudiste haber resuelto entonces. Adem�s, la forma en que resuelvas cualquier cosa no trivial puede tener un impacto considerable en c�mo se debe escribir el c�digo.)

Notas al margen. Mientras est�s escribiendo una especificaci�n, recuerda tus distintas audiencias: programadores, pruebas, marketing, redactores t�cnicos, etc. Seg�n escribes la especificaci�n, se te pueden ocurrir ideas �tiles que pueden ser de utilidad a uno solo de estos grupos. Por ejemplo, yo indico ciertos mensajes para el programador, que suelen describir alg�n detalle de implementaci�n, como «Notas t�cnicas». Los de marketing las ignoran, pero los programadores las devoran. Mis especificaciones suelen estar repletas hasta el agotamiento de “Notas de prueba”, “Notas de marketing”, y «Notas de documentaci�n”.

Las especificaciones necesitan estar vivas. Ciertos equipos de programaci�n adoptan una mentalidad “en cascada”: dise�amos todo el programa de una vez, escribimos una especificaci�n, la imprimimos, la tiramos por encima de la pared a los programadores y nos vamos a casa. Todo lo que tengo que decir es: "�Ja ja ja ja ja ja ja ja!”

Semejante forma de actuar es la causa de que las especificaciones tengan esa reputaci�n tan mala. Mucha gente me ha dicho, «las especificaciones son in�tiles porque nadie las sigue, siempre est�n obsoletas, y nunca se corresponden con el producto».

Disc�lpame, pero a lo mejor tus especificaciones est�n obsoletas y no se corresponden con el producto. Mis especificaciones se actualizan con frecuencia. Las puestas al d�a se van haciendo seg�n el producto va siendo desarrollado y se toman nuevas decisiones. La especificaci�n siempre refleja nuestro mejor conocimiento colectivo de c�mo funcionar� el producto. Solamente se congela la especificaci�n cuando el producto est� en estado de «c�digo completo» (o sea, cuando toda la funcionalidad est� completa, pero todav�a queda probarlo y depurarlo).

Para facilitar la vida de la gente, no reedito la especificaci�n a diario. Suelo mantener una versi�n puesta al d�a en un servidor, en alg�n lugar donde el equipo puede usarlo como referencia. En hitos ocasionales del proyecto, imprimo una copia de la especificaci�n con marcas de revisi�n, para que la gente no tenga que releerla toda entera — basta con que echen un vistazo a las marcas de revisi�n para ver qu� cambios se han hecho.

Parte 3: Pero... �C�mo?

http://spanish.joelonsoftware.com/PainlessSpecs/3.html
Por Joel Spolsky
Traducido por Miguel Cardo
Editado por Domingo Pi�a Maza
4 de octubre, 2000

Ahora que has le�do todo sobre por qu� necesitas una especificaci�n y qu� contiene una especificaci�n, hablemos de qui�n deber�a escribirlas.

�Qui�n escribe especificaciones?

Perm�teme contarte aqu� un poco de la historia de Microsoft. Cuando Microsoft empez� a crecer seriamente durante los 80, all� todos hab�an le�do El M�tico Hombre-Mes, uno de los cl�sicos de gesti�n de proyectos software. (Si no lo has le�do, te lo recomiendo encarecidamente). El principal argumento del libro es que, si uno a�ade programadores a un proyecto que lleva retraso, este retraso se hace a�n mayor. La causa es que, si uno tiene n programadores en un equipo, el n�mero de canales de comunicaci�n es n(n-1)/2, lo cual crece como O(n2).

Por tanto, los programadores de Microsoft estaban preocupados sobre la forma de escribir programas cada vez m�s grandes, cuando la sabidur�a dominante del momento era que a�adir programadores �nicamente empeora las cosas.

Charles Simonyi, durante mucho tiempo el “arquitecto jefe” de Microsoft, sugiri� el concepto de programadores maestros. La idea consist�a fundamentalmente en que un programador maestro ser�a responsable de escribir todo el c�digo, pero �l o ella se apoyar�an en un equipo de programadores junior como «esclavos del c�digo”. En lugar de preocuparse por depurar cada funci�n, el programador maestro simplemente prototipar�a cada funci�n, creando la estructura vac�a, y entonces se la lanzar�a a uno de los programadores junior para que la implementase. (Por supuesto que Simonyi ser�a el Maestro de Programadores Maestros.) El t�rmino “Programador Maestro” era un poco demasiado medieval, as� que Microsoft tom� el de “Program Manager”.

Te�ricamente, se supon�a que esto resolver�a el problema del M�tico Hombre-Mes, porque nadie tiene que hablar con nadie m�s — cada uno de los programadores junior s�lo habla con su �nico program manager, y as� la comunicaci�n crece como O(n) en lugar de O(n2).

Bien, puede que Simonyi conozca la Notaci�n H�ngara, pero no conoce Peopleware. Nadie quiere ser un esclavo del c�digo. El sistema no funcion� en absoluto. Lleg� un momento en que Microsoft descubri� que, pese al presunto M�tico Hombre-Mes, uno puede seguir a�adiendo gente inteligente a un equipo y obtener un aumento en la producci�n, aunque sea con valores marginales decrecientes. El equipo de Excel ten�a 50 programadores cuando yo estaba all�, y era algo m�s productivo que lo que hubiera sido un equipo de 25 — pero no dos veces productivo.

La idea de la programaci�n maestro/esclavo fue desacreditada, pero Microsoft todav�a ten�a por ah� a esa gente, llamados program managers. Un hombre inteligente, llamado Jabe Blumenthal, reinvent� pr�cticamente el puesto de program manager. A partir de aqu�, el program manager ser�a el due�o del dise�o y la especificaci�n de los productos.

Desde entonces, en Microsoft los program managers recopilan requisitos, deducen lo que se supone que hace el c�digo, y escriben las especificaciones. Hay normalmente unos 5 programadores por cada program manager; estos programadores son responsables de implementar en c�digo lo que el program manager ha implementado en forma de especificaci�n. Un program manager tambi�n necesita coordinar el marketing, la documentaci�n, las pruebas, la adaptaci�n internacional, y todo el resto de molestos detalles en que los programadores no deber�an perder el tiempo. Por �ltimo, se supone que en Microsoft los program managers tienen en mente la «visi�n global» de la compa��a, mientras que los programadores son libres para concentrarse en conseguir que sus trocitos de c�digo sean perfectos.

Los program managers son inapreciables. Si alguna vez te has quejado de que los programadores se ocupan de la elegancia t�cnica m�s que del atractivo comercial del producto, necesitas un program manager. Si alguna vez te has quejado de que quienes son capaces de escribir buen c�digo nunca son capaces de escribir buen castellano, entonces necesitas un program manager. Si te has quejado alguna vez de que parece que tu producto se mueve a la deriva, sin una direcci�n clara, necesitas un program manager.

�C�mo contratar a un Program Manager?

La mayor�a de las empresas ni siquiera tienen el concepto de program manager. Muy mal, creo yo. En mis tiempos, los grupos de Microsoft con program managers fuertes ten�an productos de gran �xito: Excel, Windows 95, y Access me vienen a la memoria. Pero otros grupos (como MSN 1.0 y Windows NT 1.0) los llevaban desarrolladores que normalmente ignoraban a los program managers (quienes de todas formas no eran muy buenos, y probablemente merec�an ser ignorados), y sus productos no tuvieron tanto �xito.

He aqu� tres cosas a evitar:

1. No asciendas un programador a program manager. Las habilidades para ser un buen program manager (escribir claro, diplomacia, tener en cuenta al mercado, empat�a con el usuario, y buen dise�o del interfaz de usuario) son muy raras veces las habilidades para ser un buen programador. Seguro que hay gente capaz de ambas cosas, pero escasean. Recompensar a buenos programadores ascendi�ndoles a un puesto diferente, uno que implica escribir en espa�ol, no en C++, es un caso cl�sico del Principio de Peter: se tiende a ascender a la gente a su nivel de incompetencia.

2. No dejes que la gente de marketing sean program managers. Sin �nimo de ofender, creo que mis lectores estar�n de acuerdo en que los buenos empleados de marketing pocas veces tienen una idea de los aspectos tecnol�gicos lo bastante buena como para dise�ar productos.

Fundamentalmente, la gesti�n de programas es una carrera profesional independiente. Todos los program managers tienen que ser muy t�cnicos, pero no tienen por qu� ser buenos programadores. Los program managers estudian la interacci�n con el usuario, se re�nen con los clientes, y escriben especificaciones. Necesitan llevarse bien con una amplia variedad de gente — desde clientes “retrasados”, pasando por irritantes programadores ermita�os que vienen al trabajo vestidos de Star Trek, hasta pomposos tipos de ventas en trajes de 2000 d�lares. En cierto sentido, los program managers son el pegamento que une los equipos de software. El carisma es crucial.

3. No obligues a que los programadores est�n por debajo del program manager. Se trata de un error sutil. Como program manager en Microsoft, dise�� la estrategia de Visual Basic (VBA) para Excel y especifiqu� totalmente, hasta el detalle m�s nimio, c�mo deber�a implementarse VBA en Excel. Mi especificaci�n se alarg� hasta unas 500 p�ginas. En el punto �lgido del desarrollo de Excel 5.0, estim� que cada ma�ana 250 personas ven�an a trabajar, y fundamentalmente lo hac�an partiendo de esa enorme especificaci�n que yo hab�a escrito. No ten�a ni idea de qui�nes eran todos esos, pero hab�a sobre una docena de personas en el equipo de Visual Basic solamente escribiendo documentaci�n para ese chisme (por no mencionar el equipo escribiendo documentaci�n por la parte de Excel, o la persona a tiempo completo responsable de los hiperenlaces en el fichero de ayuda). Lo extra�o es que yo estaba “en la base” del �rbol jer�rquico. Eso es. Yo no era el jefe de nadie. Si yo quer�a que la gente hiciera algo, ten�a que convencerles de que era lo apropiado. Cuando Ben Waldman, el desarrollador jefe, no quer�a hacer algo que yo hab�a especificado, simplemente no lo hac�a. Cuando los de pruebas se quejaban de que algo que yo hab�a especificado era imposible de probar por completo, yo ten�a que simplificarlo. Si alguna de estas personas hubiera estado por debajo de m�, el producto no habr�a sido tan bueno. Algunos de ellos habr�an pensado que no est� bien contradecir a un superior. Otras veces, simplemente me habr�a impuesto y les habr�a ordenado hacerlo a mi manera, por presunci�n o cortedad de miras. Tal como estaba organizado, no me quedaba m�s remedio que formar un consenso. Esta manera de tomar decisiones fue la mejor forma de conseguir que se hiciera lo correcto.

El art�culo final de mi serie sobre especificaciones trata de c�mo escribir buenas especificaciones que a la gente les apetezca leer.

Parte 4: Consejos

http://spanish.joelonsoftware.com/PainlessSpecs/4.html
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 s� 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 */ }

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, Direccion De?(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 Direccion De?(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.

2007-09-13 21:58:13

edited by JuananRuiz