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:
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:
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.
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:
... y haces click en “Ayuda”, aparece un tema de ayuda tragicómico que dice algo como
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.
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:
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.
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.
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, cuestie 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:
escribe algo como:
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:
10; print_count(stdout, “empleados”, n) /* código
deliberadamente ofuscado */ }
o
obtienes la misma salida. Por esa misma razón, si piensas sobre ello, sueles encontrar programadores que escriben cosas como:
Esto mismo podría haberse especificado como:
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+Impr Pant) 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.