Documentación y conocimiento
¿Por qué está ahí esa resistencia de 0 Ω? Documentar el porqué
Los ficheros registran el qué, nunca el porqué. Qué decisiones merecen un motivo escrito, dónde ponerlo, un formato de cinco líneas y lo que cuesta no tenerlo.
# Cómo documentar las decisiones de diseño en hardware
Hay una resistencia de 0 Ω entre dos zonas de masa de una tarjeta.
A simple vista parece innecesaria. El esquema no explica por qué está ahí y el layout tampoco. Un ingeniero que llega al proyecto dos años después tiene tres opciones: dejarla sin entenderla, quitarla y comprobar experimentalmente por qué existía, o buscar en correos, tickets y conversaciones antiguas hasta encontrar alguna pista.
La resistencia no es el problema.
El problema es que la decisión sobrevivió, pero su razonamiento no.
En proyectos que duran varios años, esto se repite con componentes, rutas, footprints opcionales, puntos de ensayo, márgenes, protecciones y decisiones mecánicas. El diseño sigue funcionando, pero cada vez resulta más difícil distinguir entre lo esencial, lo conservador y lo que podría simplificarse.
Documentar la intención de diseño sirve precisamente para conservar esa diferencia.
Las preguntas que los archivos de diseño no siempre pueden responder
Un esquema o un layout describen muy bien qué hay.
No siempre explican por qué está así.
Por ejemplo:
- ¿Por qué se utilizó esta pieza y no una equivalente más barata?
- ¿Por qué esta pista sigue un recorrido aparentemente innecesario?
- ¿Por qué existe una huella que normalmente queda sin montar?
- ¿Por qué este punto de ensayo está exactamente ahí?
- ¿Por qué se eligieron 4,7 kΩ y no 10 kΩ?
- ¿Por qué se descartó una solución aparentemente más simple?
- ¿Qué condición obliga a mantener esta separación?
- ¿Qué problema apareció cuando se probó la alternativa?
En muchos casos el motivo era evidente para quien diseñó el circuito.
Eso es precisamente lo que hace que no se escriba.
Meses o años después, el contexto ya no está presente y el propio diseño no basta para reconstruirlo con seguridad.
No todas las decisiones necesitan documentación
Intentar justificar cada componente convierte la documentación en otro problema.
La mayoría de las decisiones de un diseño son rutinarias o pueden deducirse razonablemente de las buenas prácticas y del propio circuito.
Una clasificación útil es ésta.
Decisión rutinaria
Ejemplo:
Condensador de desacoplo de 100 nF junto al pin de alimentación de un integrado.
Normalmente no necesita una explicación específica, salvo que exista alguna condición especial.
Decisión calculada pero convencional
Ejemplo:
Pull-up de 4,7 kΩ en un bus I²C debido a capacidad de bus y velocidad requeridas.
Puede merecer una nota corta, un cálculo enlazado o una referencia a la especificación correspondiente.
No necesita necesariamente un documento independiente.
Decisión no evidente, excepcional o contraintuitiva
Aquí sí merece la pena dejar contexto.
Por ejemplo:
- un puente de 0 Ω cuya finalidad no resulta obvia;
- una pieza considerablemente más cara que otra aparentemente equivalente;
- una huella opcional que se mantiene intencionadamente;
- una pista con una geometría extraña por motivos de EMC o integridad de señal;
- una protección aparentemente redundante;
- una solución que parece subóptima pero evita un problema que ya se encontró anteriormente.
Una buena pregunta es:
¿Un ingeniero competente que vea esto por primera vez podría considerar razonable cambiarlo o eliminarlo?
Si la respuesta es sí, probablemente merece una explicación.
Esta regla mantiene la cantidad de documentación razonable.
Dónde debe vivir la justificación
No hay un único lugar correcto.
La mejor opción depende de cuánto contexto haga falta y de dónde vaya a buscarlo quien revise el diseño.
| Lugar | Útil para | Limitación |
|---|---|---|
| Nota en el esquema | decisiones ligadas a una red o componente concreto | espacio limitado |
| Comentario de BOM | selección de componente, sustituciones, restricciones de montaje | puede perderse en exportaciones o procesos posteriores |
| Nota de layout | decisiones geométricas o de colocación | no siempre llega a quien sólo revisa el esquema |
| Registro de cambio | explicar por qué una decisión se modificó | no captura necesariamente decisiones originales |
| Documento de notas de diseño | razonamiento largo, alternativas y compromisos | puede quedar desconectado del objeto al que se refiere |
| Issue o registro técnico enlazado | análisis, ensayos y discusión trazable | requiere conservar el enlace y el sistema |
La solución práctica suele ser combinar dos niveles:
- una señal corta donde aparece la decisión;
- una explicación más extensa donde haya espacio.
Por ejemplo, en el esquema:
R45 — 0R link. Do not remove.
See design note DN-017.Y en DN-017, el razonamiento completo.
Así la persona que está a punto de borrar R45 ve inmediatamente que no es accidental y sabe dónde buscar el contexto.
Un formato corto que sí se puede mantener
Una justificación útil no necesita ser larga.
Por ejemplo:
Decision:
R45, 0 Ω link between AGND and DGND regions.
Date:
2024-06-11
Alternatives considered:
Direct copper connection, ferrite bead, separate regions.
Reason:
Single controlled connection point selected after prototype testing showed
lower ADC noise than the other evaluated configurations.
Constraint:
Do not create a second AGND-DGND connection elsewhere on the PCB.Es un ejemplo ficticio, no una recomendación general sobre cómo dividir masas. La estrategia de masa depende del circuito, las frecuencias, las corrientes de retorno, el ADC, el layout y otros factores.
Los campos más valiosos suelen ser alternativas consideradas y restricciones.
Las alternativas indican qué caminos ya se exploraron.
La restricción indica qué cambio aparentemente inocente puede romper el comportamiento deseado.
Guarda también la evidencia cuando exista
“Lo probamos y funcionaba mejor” es mejor que nada, pero dentro de unos años puede no ser suficiente.
Cuando la decisión dependa de una medida, simulación o ensayo, enlaza la evidencia.
Por ejemplo:
Reason:
ADC noise was lower with a single-point connection.
Evidence:
LAB-ADC-014, measurements on Prototype P3.
Test condition: 25 °C, 12 V input, firmware 0.9.7.No hace falta adjuntar un informe a cada resistencia.
Pero si una decisión poco intuitiva se sostiene sobre un resultado experimental, conservar ese resultado aumenta mucho su valor.
Documenta la decisión cuando la tomas
La mejor justificación se escribe cerca del momento en que se decide.
Si se reconstruye al terminar el proyecto, parte del razonamiento ya se ha perdido.
La memoria tiende a simplificar:
Elegimos X porque era mejor.
cuando la decisión real pudo ser:
X era ligeramente peor en consumo, pero evitaba un problema de arranque, estaba disponible en dos proveedores y permitía mantener la misma huella.
Ese detalle es precisamente el que otro ingeniero necesitará para decidir si la restricción sigue siendo válida.
Esto no sustituye al registro de cambios
La intención de diseño y el historial de cambios responden a preguntas distintas.
Un registro de cambios puede decir:
Rev B → Rev C: sustituido U12 porque el regulador original superaba el límite térmico durante operación continua.
Eso explica qué cambió y por qué cambió.
Una nota de diseño puede decir:
U12 se seleccionó con margen mínimo de 25% en corriente y requiere cobre térmico en ambas capas exteriores.
Eso explica qué debe seguir siendo cierto en el diseño actual.
Hay decisiones importantes que existen desde la primera revisión y nunca aparecen en ningún ECO precisamente porque nunca cambiaron.
Por eso ambos mecanismos se complementan.
Qué ocurre cuando se pierde la intención de diseño
La ausencia de contexto suele aparecer de cuatro formas.
Arqueología
Alguien necesita entender una decisión y dedica horas a revisar:
- correos;
- commits;
- informes antiguos;
- tickets;
- chats;
- versiones de esquemas.
El coste se repite cada vez que cambia la persona que trabaja en esa zona.
Regresiones
Una característica aparentemente innecesaria se elimina durante una simplificación o reducción de coste.
El problema que esa característica evitaba reaparece.
Sin la justificación original puede resultar difícil relacionar ambas cosas.
Parálisis
También puede ocurrir lo contrario.
Nadie se atreve a tocar:
R127
C84
U9
optional footprint JP3porque nadie sabe si están ahí por necesidad o por accidente histórico.
El resultado es un diseño que acumula decisiones antiguas que nadie se siente capaz de cuestionar.
Trabajo repetido
Una alternativa descartada hace tres años vuelve a proponerse.
Se analiza otra vez, se prototipa otra vez y se descarta por la misma causa.
Registrar las alternativas consideradas evita parte de este ciclo.
La documentación también ayuda a simplificar diseños
Conservar la intención no sirve sólo para evitar errores.
También permite eliminar cosas.
Supongamos que una nota dice:
C41 added to solve reset transient observed with power supply Rev A.
Tres años después, esa fuente de alimentación ya no existe.
Ahora hay una razón concreta para comprobar si C41 sigue siendo necesario.
Sin esa nota, hay dos comportamientos habituales:
- nadie se atreve a quitarlo;
- alguien lo quita sin saber qué problema estaba resolviendo.
La documentación convierte una decisión histórica en algo que se puede reevaluar.
Eso es especialmente importante en reducción de coste, rediseños por obsolescencia y mantenimiento de productos de larga vida.
Qué merece una nota de diseño
Algunos buenos candidatos son:
- decisiones tomadas después de un fallo de prototipo;
- soluciones relacionadas con EMC o integridad de señal;
- deratings poco evidentes;
- márgenes térmicos ajustados;
- componentes seleccionados por una característica no visible en la BOM;
- footprints opcionales;
- straps y jumpers;
- restricciones mecánicas;
- componentes que no deben sustituirse por equivalentes de mismo encapsulado;
- alternativas evaluadas y descartadas;
- dependencias entre hardware y firmware;
- circuitos que sólo funcionan correctamente bajo determinada secuencia de alimentación.
No hace falta documentarlos todos con el mismo nivel de detalle.
La cantidad de contexto debería ser proporcional a lo difícil que sería reconstruir la decisión.
Cómo empezar en un proyecto que no tiene ninguna justificación
No intentes explicar retrospectivamente cada elemento de un diseño de cinco años.
Parte del razonamiento ya no puede recuperarse de manera fiable y terminarías documentando hipótesis como si fueran hechos.
Es mejor empezar con las decisiones nuevas.
Una regla sencilla:
Documenta la próxima decisión que no sería evidente para alguien que no estuvo en la conversación.
Después, la siguiente.
También puedes añadir contexto cuando una zona antigua vuelva a abrirse por:
- un rediseño;
- una sustitución de componente;
- un problema de campo;
- una revisión de coste;
- una modificación de fabricación.
Así la documentación crece precisamente en las zonas que siguen activas.
Una comprobación final
Antes de cerrar una decisión no evidente, comprueba que otro ingeniero pueda saber:
- qué se decidió;
- por qué;
- qué alternativas se consideraron;
- qué restricción debe conservarse;
- dónde está la evidencia, si la decisión dependía de un ensayo o cálculo.
Eso suele ser suficiente.
El objetivo no es registrar cada pensamiento del diseñador.
Es evitar que una decisión técnicamente importante termine convertida, unos años después, en un componente que nadie se atreve a tocar porque nadie recuerda para qué sirve.
Cuando ese contexto se guarda separado del objeto al que pertenece, termina siendo difícil de encontrar. En XKEMA la información técnica y las notas pueden mantenerse asociadas a los elementos de hardware y a su contexto de revisión, de forma que el razonamiento no dependa únicamente de encontrar un documento aislado.