Especificación Técnica

Hace algunos meses me pidieron que hiciera una especificación técnica sobre uno de los desarrollos que teníamos que comenzar, y me hizo gracia darme cuenta que nunca había hecho una. He estimado, he desestimado, he desarrollado, he subdesarrollado, pero nunca había escrito una Tech-Esp. Así que lo ataque con soltura y flojera, lo que me ganó que hiciera una mierda de especificación, como todos notaron.

Al ver mi fallo, me senté a ello con renovadas energías. Leí, investigué, averigüé y pedí ejemplos, luego de lo cual volví a hacerla. No siento que haya quedado bien, o que sirviera de algo, pero al parecer a los demás sí les gustó. Incluso, mi jefe, que no desarrolla, me escribió lo siguiente:

"Me gustó mucho como está escrita la especificación. Incluso yo mismo podría hacer la programación (jajá jajá). Esto debería crear un hito en el área de Desarrollo, y todas nuestras nuevas actividades deberían venir acompañada de este tipo de Especificación Técnica. Apuntemos hacia allá".

Como les dije, me parece que la Especificación no fué la gran vaina, pero bueno... Y ahora, aprovechando que me pidieron que hiciera algunas más, pensé en publicar los pasos a seguir aquí, para justificar el tag Digerati, que tengo tan abandonado. Espero que esta información me sirva en el futuro para mejorar mis especificaciones, y les sirva a ustedes como pírrica guía cuando tengan que hacer alguna.

(Nota: En todos los sites de la gente que sabe dicen que no se puede hacer un manual de una página para escribir especificaciones técnicas, que es precisamente lo que pretendo hacer. Lo bueno es que yo no soy gente que sabe!).


Title (Título): No hay mucho que explicar aquí. Sencillamente coloquen los títulos apropiados. En mi caso, lo que mejor me ha funcionado es colocar la Actividad a espedificar, la Sub-Actividad (si la hay), y terminar con "Especificación Técnica".

Revision History Log (Registro Histórico de Revisiones): No es más que una tabla con las columnas "Revisión", "Fecha", "Autor" y "Descripción", donde cada una de las personas que modifiquen el documento colocarán sus datos, y la fecha y explicación de la modificación. Por supuesto, la primera línea (Revisión 1.00) tendrá tu nombre, la fecha de creación de la especificación, y la descripción "Documento Inicial" (Initial Draft), o algo similarmente ambigüo.

Overview (Introducción): Un par de párrafos detallando qué se busca con esta especificación, hacia qué tipo de personas está dirigida (personal técnico, usuarios finales, configuradores, etc), comentarios generales de qué cubre y qué no cubre el documento, etc.

Initial Issues (Puntos Iniciales): Para qué sistema se está haciendo la especificación, directorios usados, configuración previa, etc.

Use Cases (Casos de Uso): Detalla las operaciones, paso a paso pero sin profundizar en descripción, que el Usuario Final podrá realizar luego de desarrollado lo especificado en el documento. Hay quien dice que esta sección no la llena tecnología, sino los encargados del Control de Calidad; si es así, los felicito.

User Interfaces (Interfaces de Usuario): Cambios a pantallas y demás cosas que el Usuario Final verá: páginas, botones, navegación, validaciones, listas, búsquedas, etc. Tan detallado como se pueda.

Detailed Navigation (Navegación Detallada): Detalla la navegación que el Usuario Final podrá realizar luego de desarrollado lo especificado en el documento. A grandes rasgos, es similar a los Casos de Uso, pero especificando las pantallas, opciones y acciones usadas. Hay quien dice que esta sección no la llena tecnología, sino los encargados de la Especificación Funcional; si es así, los felicito más aún que antes.

Detailed Operation Design (Diseño de Operaciones Detallado): Es, a mi parecer, el meollo de la especificación. Es aquí donde el verdadero trabajo comienza, pues debemos aclarar, para cada una de las funciones pedidas, qué es lo que se espera desarrollar, dónde y cómo, basándonos en los puntos anteriores.

Assumptions (Asumciones): Un breve resumen de las condiciones del sistema que son requeridas para que el nuevo desarrollo funcione; qué información debe manejar el Usuario Final; qué pasos previos se deben llevar a cabo para que el estado del sistema sea el requerido, o qué pasos posteriores se deben hacer luego de ejecutadas las operaciones especificadas.

Final Issues (Puntos Finales): Convenciones a usar, código que puede o no ser modificado, frameworks a usar, etc.

References (Referencias): Toda la documentación que pueda ayudar a entender mejor la actual especificación, o que apoye al desarrollador durante sus labores. Si colocan aquí un link a este documento, no me molestaré!

Glossary (Glosario): Explicación de las palabras o términos usados durante la especificación que no sean de dominio general.


Como palabras finales, el idioma de la especificación dependerá de las reglas de la empresa para la que la hagas, así como de si es una especificación interna o va para un cliente o contratista. Lo normal es que vayan en inglés o en tu idioma (español, asumo?) y es por eso que he colocado los títulos y secciones en ambos idiomas.

Les agradezco sus comentarios, y en la medida de lo posible iré modificando este post para añadir, modificar o quitar lo que sea necesario, hasta que quede una guía práctica y útil, si no decente.

Creemos una clase llamada "Clase", otra llamada "Instancia", tomemos un par de cervezas, y disfrutemos las mariqueras que saldrán en la conversación. Como extra bonus, para los valientes, podemos crear una llamada "Primitiva". -- Gorka

Es mejor hablar en inglés, las cosas suenan mejor... No solo es el caso de Jaime Limón y Jack Lemmon. Ya les presenté a todos a KiloTrón (mil y pico de esos tipos forman una pistola). Cómo sería en español? MilTrón. Y se imaginan comparar a los Transformers con el Monstruo MilTron, nuestro seguro servidor? Starscream sería el Intrépido Volador? Nooooo! -- Gorka

Hace algún tiempo estaba entrevistando a un ejecutivo de una gran empresa, y le pregunté qué querían sus clientes. Él me dijo "Ellos lo quieren gratis, ahora, y perfecto". -- Ron Jeffries

Ya sé que tú crees que comprendes lo que tú piensas que he dicho. Pero no estoy seguro de que te des cuenta de que lo que has oído no es lo que yo quería decir. -- Patrick Murray