Por qué es importante escribir documentos de diseño de software

Felicidades, eres un desarrollador independiente competente. Desde sus humildes comienzos, tal vez trabajando como probador, progresó a un desarrollador de equipo, luego a un desarrollador senior, y ahora ha dado otro salto, el más grande de todos, para trabajar directamente con los clientes.

Pero donde las otras transiciones fueron lineales, esta última fue exponencial. Mientras que en el pasado recibía sus órdenes de marcha de un empleador que trabajaba con clientes o estaba en el negocio del software, ahora todas esas responsabilidades que alguna vez se distribuyeron entre pruebas de expertos, administración de programas, etc., son todas suyas. Y ahora está trabajando con clientes que no están en el negocio del software; están en otro negocio que necesita un software y no tienen una visión clara y precisa de lo que quieren de ti. Este es un desafío mucho mayor de lo que parece.

*Nota:* Aquí, estoy describiendo clientes más pequeños que quieren un ejército de un solo hombre de su desarrollador. No es la única ruta que puede tomar un freelancer, y esos no son los únicos clientes con los que trabajamos en Toptal, pero es la ruta que más disfruto. Por supuesto, si trabaja en equipo y no solo, algunos de los siguientes no se aplicarán. Por ejemplo, si está utilizando metodologías Agile o Scrum, probablemente querrá estructurar sus hitos de manera ligeramente diferente.

Todos ustedes han oído hablar de la importancia suprema de la comunicación. No puede trabajar obteniendo algunas oraciones de descripción concisa a través de Skype y diciendo "Nos vemos en tres meses cuando termine". Tienes que estar en comunicación con tu cliente y en cada etapa de tu trabajo asegurarte de tener ideas congruentes sobre el objetivo, porque es raro que un cliente te envíe esquemas y una especificación funcional detallada. Obtendrá una idea muy general de lo que se supone que debe hacer, parecerse y fluir el software. Si escribe una aplicación basada en la descripción superficial con la que suele comenzar, casi no hay posibilidad de que su cliente esté satisfecho con el resultado. En cada etapa, debe iterar su camino más cerca del acuerdo.

Después de haber trabajado durante años en empresas que estaban en el negocio del software, donde todos en el equipo eran de la misma cultura, hablaban el mismo idioma nativo, trabajaban en el mismo pasillo, se reunían todos los días, etc., era digno de mención que la la empresa aún no obtenía lo que quería la mitad del tiempo. No se equivoquen: el desafío aquí es enorme.

Por qué son importantes los documentos de diseño de software

Por lo tanto, cuando asume un nuevo proyecto, incluso antes de abrir Xcode o Visual Studio, debe tener objetivos de diseño claros y acordados . Y estos objetivos deben establecerse en un documento de especificaciones. Si el cliente no ha escrito uno, debe escribirlo y enviarlo para su revisión antes de abrir su IDE. Y si se encuentra con un cliente que dice: “No tenemos tiempo para documentos de diseño”, con franqueza, debe abandonar el proyecto porque tiene problemas por delante. La especificación no necesita ser particularmente larga; pueden ser solo unas pocas páginas, pero como mínimo debe diseñar la interfaz de usuario, incluir estructuras alámbricas (si hay un componente de interfaz de usuario) y establecer hitos de finalización.

Sin este documento, terminará en un ciclo de equívocos mordaces, los clientes disputarán lo que le dijeron o lo que les dijo, enviaron con enojo copias y pegas de comunicaciones anteriores, interpretarán y discutirán hasta que llegue el momento en que el cliente exija que haga cambios para que la solicitud cumpla con "lo que realmente pidieron", y espera que haga esos cambios sin pago.

Con este documento de diseño de software, tendrá una respuesta a cualquier objeción de este tipo: cuando surjan desacuerdos, puede consultar la especificación que el cliente acordó y firmó, señalando que la cumplió al pie de la letra. En lugar de argumentos enojados, hará enmiendas y aclaraciones al documento. En todo caso, el cliente se disculpará por dejar pasar la imprecisión en primer lugar.

Todos queremos clientes satisfechos. Todos queremos una relación de trabajo amistosa. Y todos queremos el orgullo del trabajo bien hecho. Pero estos no se pueden lograr si hay alguna vaguedad acerca de lo que realmente es el trabajo. Si su cliente dice que un documento de diseño es demasiado trabajo extra, es su trabajo explicarle que el verdadero trabajo extra surgirá cuando sea necesario realizar revisiones debido a algún tipo de malentendido. Si el cliente aún insiste en que avance sin dicho documento, debe aceptar el hecho de que tiene una relación inviable y alejarse.

¿Qué debe especificar realmente la especificación de diseño de software?

Como mínimo, debe ser una descripción de la aplicación deseada, los criterios de finalización y los hitos. Recuerde, está compartiendo lo que se describe mejor como un documento de requisitos y funciones, no como una especificación de implementación. Y a menos que una implementación específica sea un objetivo declarado del cliente, cómo hacer que funcione depende de usted.

Interfaz de usuario

La mayoría de los proyectos son aplicaciones, no bibliotecas o marcos. Pero si tiene uno de estos como entregable, considérese afortunado porque la interfaz de usuario es, de lejos, el componente más problemático de su plantilla de documento de diseño y casi siempre conduce a malentendidos. Muchos clientes te enviarán ilustraciones perfectas creadas en un editor gráfico por un diseñador gráfico que no es programador. Pero el problema es que estas ilustraciones no dicen nada sobre animaciones, estados de control (p. ej., ¿este botón está deshabilitado? ¿Desaparece cuando no se puede usar?) o incluso qué acciones realizar cuando se presiona un botón.

Antes de comenzar a escribir el código detrás de estas ilustraciones, debería poder responder todas esas preguntas. En concreto, debes saber:

1. ¿Los controles están siempre visibles y/o activados? ¿Bajo qué condiciones cambian sus estados?
2. Parece un mapa de bits, ¿es un botón?
3. ¿Qué transiciones ocurren entre estos estados y puntos de vista? ¿Y cómo deben ser animadas?

Si depende de usted generar la interfaz de usuario para la concurrencia del cliente, haga lo mismo a la inversa: use una herramienta de estructura alámbrica y cree un conjunto completo de diseños de pantalla, incluidas las variantes que muestran las vistas en diferentes estados de la aplicación. Este puede ser un trabajo exhaustivo y tedioso, pero no se arrepentirá; puede ahorrarle la reescritura de grandes cantidades de código y la recreación de interfaces debido a un malentendido menor con implicaciones importantes. Si está creando una aplicación dual (p. ej., para iPhone y iPad), cree estructuras de alambre separadas para ambas.

Las dimensiones de la pantalla también son importantes. Hay (al momento de escribir) tres tamaños de pantallas de iPhone. Los wireframes separados para pantallas de 3,5” y 4” probablemente sean excesivos, pero es posible que deba hacerlos; en la mayoría de los casos, simplemente puede cambiar las proporciones.

Si su cliente le proporciona gráficos, asegúrese de que tengan el tamaño correcto con las relaciones de aspecto adecuadas; transformar cualquier mapa de bits que tenga texto u objetos (como círculos) introducirá distorsiones. Si no coinciden, dígale al cliente que los vuelva a crear con tamaños coincidentes. No suponga que puede estirar una pantalla de presentación de 3,5” en una presentación de 4” y seguir adelante.

Funcionalidad

Preguntas clave para hacer en el documento de diseño de la aplicación:

• ¿Qué hace la aplicación y qué tan rápido lo hace?
• ¿Cuáles son las posibles condiciones de falla y cómo se manejan?
• ¿Qué operaciones únicas se realizan en la primera ejecución (es decir, después de la instalación)?
• Si el usuario crea entradas de cualquier tipo (por ejemplo, marcadores), ¿cuáles son las limitaciones?

Generalice estas ideas y sea lo más detallado y minucioso que pueda, porque los errores o malentendidos aquí significarán reescribir el código.

Hitos

Su plantilla de especificación debe diseñar hitos claros. Si su cliente escribe el diseño funcional y de la interfaz de usuario, posteriormente debe acordar un conjunto de hitos. A veces, estos también son umbrales de facturación, pero al menos proporcionan una métrica clara hacia la finalización. Los hitos pueden ser en términos de funcionalidad y/o componentes; incluso pueden ser aplicaciones separadas si el concierto involucra un conjunto de entregables. Cuando sea posible, los hitos deben tener una duración aproximadamente igual.

Ejemplo de especificación de diseño de software

Aquí, diseñaré la estructura de ejemplo de un documento de diseño adecuado. Por supuesto, esta plantilla debe ajustarse según sea necesario. Para ver otro ejemplo, consulte la especificación de muestra de Joel Spolsky, basada en este artículo. Se acerca al documento de forma ligeramente diferente, pero comparte un sentimiento similar.

Declaración de Metas

Incluya un breve párrafo que describa el proyecto y su público objetivo.

descripcion funcional

¿Qué hace la aplicación? ¿Qué estados de la aplicación (descripciones de alto nivel de los escenarios principales del usuario) encontrará el usuario?

Por ejemplo, su descripción funcional podría verse así:

• Primer intento
• Creación de un nuevo _____ (juego, búsqueda, etc.)
• Operaciones
• Comportamiento de fondo y primer plano

Interfaz de usuario

Incluya esquemas para cada página, con descripciones detalladas de:

• Cada control, incluidos los estados (habilitado/deshabilitado/resaltado) y las operaciones.
• Orientaciones admitidas y transiciones entre ellas.
• Funcionalidad representada.
• Manejo de errores.
• Dimensiones y restricciones.

Aquí están los esquemas relacionados con mi última aplicación para iOS, NotifEye:

Si está interesado, hice estas maquetas con la herramienta de estructura alámbrica de Balsamiq.

Por ejemplo, la descripción de su interfaz de usuario podría verse así:

• Barra de navegación
  • Control de navegación izquierdo: volver a la página de inicio
  • Barra de título: pantalla actual o nombre de la operación
  • Botón Nuevo: crea una Cosa nueva
• Vista de tabla
  • Sección 0: Título de la sección
  • Sección 0 filas:
    • Control de fila 0 (p. ej., imagen)
    • Línea de texto 0
    • Línea de texto 2

Hitos

Como se describió anteriormente, los plazos de finalización y los entregables esperados.

Por ejemplo, la sección de hitos en su plantilla de documento de diseño podría verse así:

1. Aplicación de fachada que muestra la pantalla y con transiciones temporales e imágenes/texto de ejemplo
2. Protocolo de comunicación: la aplicación se conecta a la red/servidor
3. Hito funcional 1: …
4. Aplicación Alpha (con funcionalidad completa)
5. Estabilidad
6. Liberar

Asegurarse de que la documentación del software siga siendo relevante

No quiero decir que la fase de diseño haya terminado una vez que usted y su cliente hayan acordado un documento de especificaciones. Siempre habrá detalles que ninguno de ustedes había considerado, y tanto usted como el cliente, mientras observan los resultados intermedios, encontrarán nuevas ideas, cambios de diseño, fallas de diseño inesperadas y sugerencias impracticables.

El diseño evolucionará y los cambios deben capturarse en su documento. En mis 25 años de experiencia, nunca he trabajado en un proyecto en el que esto no sucediera, y eso incluye mis propias aplicaciones (es decir, donde yo era mi propio cliente). Incluso entonces, creé un documento de diseño con especificaciones detalladas y lo ajusté según fuera necesario.

Sobre todo, mantente en contacto. Al menos varias veces a la semana, comuníquese con su cliente, informe sobre su progreso, solicite aclaraciones y asegúrese de que comparten visiones idénticas. Como prueba de fuego para su comunicación, trate de asegurarse de que usted y su cliente den las mismas respuestas a estas tres preguntas:

1. ¿En qué estaba trabajando el desarrollador?
2. ¿En qué está trabajando actualmente el desarrollador?
3. ¿En qué trabajará el desarrollador a continuación?