Diseñando Ansel

Ansel está diseñado, no improvisado. Los hackers pueden disfrutar ’trabajando’ en acelerar el descenso de Darktable aumentando su deuda técnica .

¿Qué es el diseño?

El diseño es un proceso por el cual se desarrolla una metodología para brindar una solución técnica a un problema humano. El proceso de diseño está destinado a converger en la solución más adecuada, mientras se lucha contra la tendencia natural a apresurarse hacia la primera o la idea más cómoda.

Sin requerimientos ni diseño, programar es el arte de añadir errores a un archivo de texto vacío. — Louis Srygley

1. El diseño comienza con un caso de uso: una tarea definida a lograr (en una imagen), por un usuario definido, en un tiempo definido. Si no hay caso de uso, entonces no hay problema que resolver, entonces mantente alejado de tu editor de código.
2. El diseño requiere conocer al usuario objetivo: educación/capacitación, nivel de artesanía/maestría, etc.
3. El diseño requiere entender las necesidades: en el contexto de Ansel, a menudo se necesitará algún conocimiento de historia del arte y fotografía en cuarto oscuro.
4. Una vez que el problema y el usuario sean comprendidos, el diseño requiere especificar:
   • las funcionalidades esperadas de la solución.
   • el alcance de la solución (¿dónde se encuentra la solución en el ciclo de vida de una imagen?).
   • las restricciones y requisitos de la solución (apoyar algún estándar, permitir procesar n imágenes por unidad de tiempo, etc.).
   • una serie de pruebas a completar que validarían la calidad de la solución, para limitar opiniones no productivas, sesgos y subjetividad en el proceso de validación.
5. Solo entonces pueden comenzar los prototipos y sesiones de ideas.

¿Qué no es diseño?

El diseño no se ocupa de:

• requisitos vagos de un usuario indefinido, futuro o imaginado,
• “sería genial si…” (así es como se crean colecciones de complementos inconsistentes),
• lo que le gusta a la gente (por cada cosa que a alguien le gusta, encontrarás a alguien que la odia),
• lo que la gente cree que quiere (a menudo no es lo que necesita),
• palabras de moda tecnológicas que “son el futuro” y, como tales, necesitan ser incorporadas en todas partes, sin importar su relevancia o viabilidad (sí, estoy hablando de IA, NFT, blockchain, etc.)

¿Qué es buen diseño?

Un buen diseño es:

• minimalista.
• robusto.
• preparado para el futuro.
• genérico y generalizado.
• mantenible con recursos limitados.
• informado por la ciencia.
• compatible/interoperable con estándares industriales.

Dado que Ansel es una aplicación basada en flujos de trabajo, un buen diseño también tiene en cuenta el flujo de trabajo como un todo y dónde encajan el problema/solución en él.

¿Cómo se hace un buen diseño?

Para ayudar en el proceso de diseño, la comunicación debe ser concisa, centrada y las personas que participan en ese proceso deben asegurarse de tener una comprensión adecuada de la teoría y el trasfondo técnico involucrado en el alcance del problema/solución.

Se debe enfatizar que, aunque el proyecto está impulsado por software, no todas las soluciones involucran programación. A veces (¿a menudo?), una mejor educación o mejor documentación es todo lo que se necesita.

El propósito de un proceso de diseño sano es evitar sesgar las soluciones demasiado pronto con un diseño/tecnología favorita y evitar perderse en las complejidades técnicas, pero siempre volver a los principios básicos de lo que estamos haciendo: post-procesar potencialmente grandes lotes de imágenes en bruto para todo tipo de medios de salida.

Esto es respaldado por el hecho de que los usuarios rara vez conocen sus propias necesidades, o más bien, las necesidades que expresan rara vez son la raíz de lo que realmente quieren. La tarea difícil del diseño es cortar a través de las ramas para llegar a la raíz, porque resolver el problema raíz generalmente resulta en soluciones más elegantes, genéricas y minimalistas.

Los problemas vienen primero

El primer paso del proceso de diseño de Ansel es presentar una solicitud de función en la Comunidad. Las solicitudes de funciones se han movido de Github porque esta plataforma no es acogedora para personas no programadoras y no angloparlantes (aunque la Comunidad solo admite francés e inglés).

Esta solicitud de función se centrará en el problema a resolver y se abstendrá de proponer cualquier solución. El problema se definirá en términos de tareas a lograr en el flujo de trabajo de un fotógrafo o resultado visual esperado de la imagen procesada, es decir, en términos del objetivo final a lograr, no en términos de herramientas o tecnicismos que se creen necesarios. Esto puede llevar a una discusión para profundizar en las raíces del problema, que generalmente están bien ocultas debajo de lo que el usuario cree que es su problema .

No se acepta ninguna propuesta de solución en esta etapa.

Las soluciones vienen segunda

Cuando la definición y el alcance del problema sean acordados entre las personas involucradas en la discusión, se podrán proponer soluciones. Puede ser necesario un debate posterior para evaluar los inconvenientes y beneficios de cada solución, llevando a la adopción de la mejor solución en principio. Las soluciones se definen por sus funcionalidades (es decir, lo que deberían hacer), no por su tecnología o medios (cómo deberían hacerlo).

No se aceptan propuestas de prototipo en esta etapa.

Las soluciones adoptadas llevarán a una nueva incidencia que será triageada en el tablero Kanban de gestión de proyectos .

Pueden estar condicionadas a la investigación de aspectos teóricos y técnicos para evaluar su viabilidad, en cuyo caso estarán triageadas en la columna Por investigar del tablero Kanban. Los hallazgos de la investigación se añadirán a la incidencia original hasta que la viabilidad de la solución esté comprobada. Cuando lo esté, la incidencia se moverá a la columna ‘Por hacer’ del tablero Kanban.

Las soluciones adoptadas pueden ser directamente triageadas para la columna Por hacer si solo requieren herramientas y técnicas bien conocidas.

Idealmente, los puntos a probar y el procedimiento de prueba para validar el prototipo deberían estar escritos incluso antes de tener un prototipo funcional. Al menos, las pruebas deben asegurar que no ocurrió regresión en las características y herramientas relacionadas.

Los prototipos son el tercer paso

Solo las incidencias triageadas en la columna ‘Por hacer’ del tablero Kanban de gestión de proyectos  serán trabajadas, por mí mismo o por cualquiera dispuesto a abordarlas.

El prototipo de la solución se propondrá en una solicitud de extracción de una rama de tema que enlace la incidencia original. Las ramas de tema necesitan ser alineadas con la rama master por ejemplo, git rebase ustream master o, si actualizas tu rama localmente con nuevos commits de master, haz git pull upstream master --rebase o configura git globalmente  para extraer a través de rebase en lugar de merge. Esto asegura que el historial de tu rama se mantenga limpio con el mínimo esfuerzo, y también mantiene limpio el historial de master cuando se fusiona tu PR.

Cuando la solicitud de extracción de prototipo se revise y si cumple con los estándares de calidad del código (ver más abajo) mientras se ajusta a las especificaciones de la solución adoptada, será aprobada y automáticamente triageada a la columna ‘Por probar/validar’ del tablero Kanban de gestión de proyectos .

La validación es el cuarto paso

Las solicitudes de extracción aprobadas se fusionarán tempranamente en la rama candidate o dev para pruebas, dependiendo de si pueden romper los historiales de edición de imágenes (al agregar nuevos parámetros de módulo o cambiar el esquema de la base de datos). Esta rama siempre será la rama principal con todas las solicitudes de extracción pendientes de validación en la parte superior. Esto está destinado a ayudar en las pruebas de personas que no necesariamente están al día con la fusión manual de ramas de git. A diferencia de la rama dev, candidate no debería romper tus ediciones.

Si no se reporta ningún error o interrupción después de algún tiempo y el prototipo cumple su propósito inicial correctamente, se fusionará en master y la incidencia relacionada se cerrará y se moverá a la columna ‘Hecho’ del tablero Kanban de gestión de proyectos .

Si el prototipo demuestra ser insatisfactorio, puede ser rechazado y otro necesitará ser trabajado.

Pro tips from a seasoned designer

Not all software problems are coding problems

Many problems don’t require more tools (or toys), and more code. More code is always bad anyway, and should be avoided whenever possible. Very often, user’s problem is they can’t see how to bend existing features to fulfill their needs. This is solved by education, aka better documentation and more tutorials, and sometimes by better UI.

Listen but don’t listen to users

Users express what they want and what they like, never what they need. And you don’t need to listen to them to know what it will be:

1. they will want the same thing as their neighbour just got,
2. they will like what they are used to.

And then, for everything one likes, you will find another one to dislike it. So the Darktable way of solving conflict is to not solve conflict, but give everyone an option, a mode, a preference to enable that special thing they like, how they like it. This means more case in your switch, more nested if, more codepaths you will need to test now, debug, and maintain in the future, and then more preferences hiding the others in the pref window. Before you know it, the code is a tumor that nobody understands anymore, and fixing it only makes it more complicated.

When you scratch beneath the surface, you find than what people actually need is much closer to other people’s needs than what they say they want. So you can reconcile the needs much easier than the desires, and without compromising. But then you have to trace the root needs below the will, and that takes abstraction skills and psychology.

UI designers are dangerous idiots

Everybody who only sees, focuses and cares about the UI is a dangerous idiot. If your GUI is complicated, it means a lot more than just a “complicated GUI” : it means that the complexity of your backend has reached your frontend. I have found the hard way that GUI complexity is never separate, and can’t be solved separately, from backend complexity and overall application architecture. GUI is not parallel to backend architecture, it’s the termination of it.

The problem of UI designers is they typically don’t code, or if they do, they suck at low-level programming and software architecture. So they focus on what little they see and understand (typical streetlight effect ), and they only produce non-actionnable designs that conflicts with what the software actually needs to work. Because that GUI is only connecting user input to the backend, and if we need that many widgets, it’s because the architecture needs that many inputs. You can’t escape it : to remove widgets, you need to remove inputs, which means your architecture will have to work with fewer degrees of freedom first. That starts with simplifying the backend, which means stinky refactoring of dusty old code nobody understands anymore.

You don’t solve GUI issues with drawings and mockups, you solve GUI issues with solving backend issues. But then you need guys who understand both levels, and they may be too expensive for you.

Ask yourself 36 times per day what was the problem you were trying to solve

It’s super easy to get lost into technicalities when programming in a low-level language and fighting third-party libs or APIs, but sometimes the solution is simple and elegant and you got carried away too far into pointers and thread locks. Always go back to the initial problem at hand, that’s your lifeline to simplicity.

What is the problem ? Who faces it ? When ? How often ? Doing what ?

The best path is the simplest path towards your solution : low techs, little code, few layers.

Document your shitty design

Many times, I completely redid a design while documenting it, because it’s when you try to explain it that your realize it’s too complicated to explain, which means it’s too complicated to understand. If you can’t explain your design in a couple of paragraphs, or your documentation has too many “if this, then that”, there are usually two reasons :

1. your GUI doesn’t expose the relevant info where user needs it, so you have to link half the documentation in your explanation to redirect users to everything they need to know or check before using the one thing you were documenting. The solution is to bring back relevant info where it’s needed.
2. your GUI has too many trays, collapsible stuff, contextual behaviours, use cases or hidden preferences, and covering all bases makes you write a novel. The solution is to linearize the workflow, maybe remove options or split features.

GUI is how users control the backend, but it’s also where they learn about existing features and what they do. The documentation should provide context, guidelines and references regarding how we do stuff, but the GUI should explain what it does itself.

Of course, there is an obvious limitation to that : in a photography application, users need to understand photography and its language, which involves things like dynamic range, color gamut, tone mapping, etc. The GUI should be self-explanatory on how it’s supposed to be used, not remove the need to learn the trade (what should be done and how).

Design is an iterative process

An application is a virtual world in which one small change can reorder how the rest of the ecosystem adapts around it. Therefore any design change can trigger the need to change other things around (refactor tools, move widgets, prune features). Which then might trigger the need to correct the initial change again. It’s a step by step process in which it is foolish to even try to get everything right at each step, what matters it that each steps improves the environment from the previous.

Sometimes, (re)design can’t be done by small steps but by large leaps : that’s when you redo the architecture. These leaps will break many things around them, which is ok if the newer architecture is simpler and more robust overall, and if you give it some time to recover before taking the sledgehammer again. But that will create a transient state in which the new design will appear worse than the previous. This is telling us that how the design is percieved is not a valid input : design quality has to be assessed against its goals and evaluated with objective metrics, not with feelings and quick tests.

And sometimes, some steps are mistakes and should be reverted. The sunk cost fallacy  should not be used to justify that some redesign should be kept because it was a lot of work to achieve. It’s expected that all research & development doesn’t make it into production.

Whack-a-mole sessions mean your architecture has run its course

Whether you keep creating new bugs while fixing old ones, or you keep creating edge cases by extending some feature, it all points in the same direction : your architecture can’t be bent any more because it has outgrown its design requirements. It might be that the backend has grown too convoluted or it might be that the existing architecture was really not planned for what you are trying to make it do, but both ways, you will have to redo the architecture and stop hacking in-place. Otherwise, you are only adding technical debt.

But then, the development cost changes scale and that saturday-afternoon project might become a month-long project.

Best-practices are guidelines, not rules

Best-practices help developing sane habits and clean code, unless you don’t understand the problem they tried to solve and use them out of their scope of validity. In that case, they become cargo cult : trying to mimic the effects in the hope that it will magically fix the causes too.

The first that comes to mind is code reuse/code sharing. If reusing the same code for (seemingly similar) features leads to too much internal branching (nested if, switch/case, etc.), to handle all possible paths, what you win on code volume is lost on cyclomatic complexity, and, by the way, your features are not as similar as you thought.

Also, duplicating code might be a starting point to locally optimize the duplicate later: once you have the complete procedure in front of you, you may spot steps that can be cached or factorized. Whereas if the procedure is only opaque, high-level, reusable API methods, then you loose the ability to spot and remove redundant computations. So, there is a principle of data reuse/sharing (aka caching computed data that will be used later with no change, to spare CPU cycles) that can be made impossible by code reuse/sharing, because it obfuscates and abstracts data lifecycle.

This becomes critical on pixel loops: you want to collapse all pixel-wise operations into the same loop, to pay the memory I/O price only once. Which means that you will have to re-implement the same affine correction ($y = a * x + b$) into each loop using it, rather than having a reusable method that does just that in its own loop.

Don’t brace yourself

If you find yourself overwhelmed by some cryptic and random bugs that keep coming and that you can’t make sense of, don’t keep fighting blindly and take a step back. Then instrument debug helpers, or higher-level managers that keep track of internal states and give you a map of the software data values at any relevant point in its lifecycle. This is especially critical in asynchronous setups, where several threads create, access or compute stuff in parallel on different timelines, and the actual ordering sequence depends on runtime context.