Cómo documentar eficazmente sus decisiones de arquitectura de Salesforce

Si ha trabajado en un proyecto de Salesforce, ya sea internamente como administrador proporcionando la funcionalidad más reciente para satisfacer sus necesidades, o como arquitecto de Salesforce en una consultoría implementando proyectos complejos para sus clientes, se habrá dado cuenta de que documentar eficazmente las decisiones arquitectónicas y técnicas es absolutamente crucial (aunque no siempre se haga);

A veces lo que te frena es el tiempo necesario para documentar las cosas correctamente. Otras veces, simplemente no sabe por dónde empezar. En cualquier caso, es de esperar que esté de acuerdo en que una documentación adecuada no sólo aclara los procesos de toma de decisiones, sino que también garantiza la ejecución sin problemas y el éxito de los proyectos de Salesforce.

Entendiendo las decisiones arquitectónicas

Las decisiones de arquitectura se refieren a las elecciones estratégicas realizadas durante la planificación e implementación de un proyecto de Salesforce. Estas decisiones dan forma a la estructura y funcionalidad general de la solución, lo que influye en su escalabilidad, rendimiento y mantenimiento. Dado su profundo impacto, es crucial documentar meticulosamente estas decisiones para proporcionar una justificación clara y una referencia para futuros proyectos.

Beneficios de una documentación adecuada

1. Claridad y comunicación: Documentar las decisiones arquitectónicas mejora la comunicación entre las partes interesadas, garantizando que todo el mundo esté alineado con la dirección y los objetivos del proyecto.
3. Consistencia y estandarización: Promueve la consistencia en los enfoques y soluciones, permitiendo prácticas estandarizadas en diferentes proyectos y equipos.
4. Mitigación de riesgos: Al documentar los riesgos potenciales y sus mitigaciones, los equipos pueden abordar los problemas de forma proactiva, reduciendo la probabilidad de contratiempos en los proyectos.
5. Gestión de la deuda técnica: Una documentación adecuada ayuda en la gestión de la deuda técnica al realizar un seguimiento de las decisiones que pueden tener contrapartidas, lo que permite facilitar futuros refinamientos. Para obtener más información sobre la gestión de la deuda técnica, lea este artículo de Salesforce Ben

Guía paso a paso para una documentación eficaz

1. Defina el alcance y el contexto. Defina el ámbito y el contexto

• Esbozar los objetivos empresariales: Comience por esbozar los objetivos empresariales del proyecto. Describa lo que el proyecto pretende lograr y por qué es importante. Esto sienta las bases para comprender el propósito que subyace a las decisiones arquitectónicas.
• Detallar los objetivos empresariales
• Detallar las limitaciones: Identifique cualquier limitación que haya influido en las decisiones. Podrían ser presupuestarias, relacionadas con el tiempo o relacionadas con los sistemas y tecnologías existentes.
• Detallar las restricciones:Identifique las restricciones que influyeron en las decisiones
• Proporcione información de fondo: Incluya información de fondo relevante como proyectos anteriores, infraestructura existente o requisitos de las partes interesadas que desempeñen un papel en la configuración de las opciones arquitectónicas.

2. Identificar las decisiones clave

• Subrayar las principales decisiones: Identifique y enumere las principales decisiones arquitectónicas tomadas a lo largo del proyecto. Cada decisión debe ser claramente identificada y descrita, incluyendo su propósito y el impacto esperado.
• Categorización
• Categorice las decisiones: Agrupe las decisiones en categorías como arquitectura de datos, arquitectura de aplicaciones, integración, seguridad y rendimiento. Esto facilitará la navegación por la documentación.
• Categorice las decisiones:

3. Detallar el proceso de toma de decisiones

• Documentar las opciones consideradas: Para cada decisión, documente las diferentes opciones que se consideraron. Esto ayuda a comprender las alternativas y por qué se eligió una opción en particular.
• Documentar las opciones consideradas
• Evaluar criterios: Describa los criterios utilizados para evaluar las opciones. Esto podría incluir factores como el coste, el rendimiento, la escalabilidad y la compatibilidad con los sistemas existentes.
• Evaluar criterios:Describa los criterios utilizados para evaluar las opciones
• Explicar la justificación: Proporcione una justificación clara de la elección final. Explique por qué se ha elegido la opción elegida en lugar de las demás, destaque sus ventajas y aborde cualquier posible inconveniente.
• Explique por qué se ha elegido la opción elegida en lugar de las demás, destaque sus ventajas y aborde cualquier posible inconveniente

4. Incorporar historias de usuario

• Escriba historias de usuario claras y concisas: Escriba historias de usuario en un lenguaje sencillo y claro que sea fácil de entender. Utilice el formato estándar de historia de usuario: «Como [rol], quiero [objetivo] para que [beneficio]» Obtenga más información sobre cómo escribir historias de usuario en el artículo de Ian Gotts sobre Salesforce Ben: Cómo escribir historias de usuario para Salesforce: What We Learned From Writing 1000.
• Incluya criterios de aceptación: Defina claramente los criterios de aceptación para cada historia de usuario. Esto ayuda a establecer las expectativas y a garantizar que la funcionalidad desarrollada cumple con los estándares requeridos.
• Incluya criterios de aceptación
• Priorizar historias de usuario: Ranifique las historias de usuario en función de su importancia e impacto en el proyecto. Esto ayuda a gestionar el proceso de desarrollo y garantizar que las funcionalidades críticas se desarrollen en primer lugar.
• Priorizar las historias de usuario: Priorizar las historias de usuario

5. Utilizar ayudas visuales

• Incorpora diagramas: Utiliza diagramas, organigramas y otras ayudas visuales para ilustrar los diseños arquitectónicos y las vías de decisión. Los elementos visuales pueden mejorar significativamente su comprensión y retención de información compleja.
• Incorpore diagramas, diagramas de flujo y otras ayudas visuales
• Utilice la descomposición funcional: La descomposición funcional ayuda a dividir los procesos complejos en componentes manejables, proporcionando un enfoque claro y estructurado de la documentación. Este método consiste en empezar por los elementos más generales y profundizar en detalles más específicos según sea necesario. Al plantear preguntas del tipo «cómo» y «por qué», puede asegurarse de que la documentación capta tanto el contexto de alto nivel como los detalles específicos. Para obtener más información sobre esta metodología, lea el artículo de Caitlin Graaf en Salesforce Ben: ¿Existe una forma mejor de documentar Salesforce? Presentación de la «descomposición»
• Utilice la Notación universal de procesos (UPN): La Notación universal de procesos (UPN) es una forma estandarizada de representar procesos visualmente. Incorporar UPN puede hacer que la documentación sea más coherente y fácil de entender. Para obtener más información sobre UPN y el mapeo de procesos de negocio, eche un vistazo al módulo Comprender la Notación Universal de Procesos en Trailhead.

6. Documentar los procesos de negocio

• Crear mapas de procesos detallados: Identifique los procesos clave implicados en el proyecto. Utilice diagramas reutilizables para crear mapas de procesos detallados que describan cada paso del proceso, quién es el responsable y cuáles son los resultados esperados. Obtenga más información sobre la creación de mapas de procesos de negocio en el módulo Crear un mapa de procesos de negocio de Trailhead.
• Analice los procesos clave del proyecto
• Analice y mejore los procesos: Utilice los mapas de procesos para identificar ineficiencias y cuellos de botella. Documente cualquier mejora realizada y actualice los mapas de procesos en consecuencia para que reflejen el estado actual de los procesos.
• Analice y mejore los procesos:

7. Registrar riesgos y mitigaciones

• Identificar riesgos: Para cada decisión, documente cualquier riesgo asociado. Esto incluye los problemas potenciales que podrían surgir de la opción elegida.
• Identificar riesgos: Para cada decisión, documente los riesgos asociados
• Desarrollar estrategias de mitigación: Describa las estrategias aplicadas para mitigar los riesgos identificados. Este enfoque proactivo ayuda a anticiparse a los posibles problemas y a desarrollar planes de contingencia.
• Describa las estrategias implementadas para mitigar los riesgos identificados

8. Mantener un repositorio actualizado

• Documentación centralizada: Asegúrese de que toda la documentación se almacena en una ubicación centralizada y accesible a la que todas las partes interesadas pertinentes puedan acceder fácilmente y contribuir a ella.
• Mantenga un repositorio actualizado
• Control de versiones y registros de auditoría: Implemente un control de versiones para realizar un seguimiento de los cambios realizados en la documentación. Esto incluye el mantenimiento de un registro de auditoría de los cambios, que proporciona un historial de ediciones y actualizaciones, ayudando a comprender la evolución de la documentación. Poder ver las versiones anteriores es vital para hacer un seguimiento de la progresión de las decisiones, comprender los contextos pasados y, potencialmente, volver a versiones anteriores si es necesario.
• Control de versiones
• Actualizaciones periódicas: Actualice periódicamente la documentación para reflejar los cambios o las nuevas decisiones tomadas durante el ciclo de vida del proyecto. Un repositorio actualizado es muy valioso para el mantenimiento continuo y futuras mejoras. Para obtener una guía completa sobre la documentación de Salesforce, consulte la guía de Ian Gotts sobre Salesforce Ben: Guía completa sobre la documentación de Salesforce.
• Guía completa sobre la documentación de Salesforce

Mejores prácticas para la documentación

1. Coherencia

• Formato estandarizado: Utilice un formato y una estructura estandarizados para la documentación con el fin de garantizar la coherencia y la facilidad de uso.
• Utilización de plantillas: Cree y utilice plantillas para diferentes tipos de documentación. De este modo se garantiza que toda la información necesaria se captura y presenta de manera uniforme.
• Utilización de plantillas:

2. Accesibilidad

• Repositorio centralizado: Almacene la documentación en una ubicación central y accesible. Podría tratarse de un portal de documentación dedicado, una unidad compartida o un sistema de gestión de documentos basado en la nube.
• Disponga de un repositorio centralizado
• Fácil acceso: Asegúrese de que todas las partes interesadas pertinentes, incluidos los desarrolladores, arquitectos, gestores de proyectos y clientes, tengan fácil acceso a la documentación.

3. Colaboración

• Fomentar las aportaciones: Fomentar la colaboración y las aportaciones de varios miembros del equipo para captar diversas perspectivas y puntos de vista.
• Revisar la documentación
• Ciclos de revisión: Implemente ciclos de revisión periódicos en los que los miembros del equipo puedan aportar comentarios y sugerir mejoras a la documentación.

4. Revisión y retroalimentación

• Mecanismo de retroalimentación: Cree un mecanismo de retroalimentación donde los miembros del equipo puedan aportar sugerencias para mejorar la documentación.

Gestión de la deuda técnica

La deuda técnica se refiere a los costes futuros incurridos debido a los atajos tomados durante el proceso de desarrollo. Una documentación adecuada puede ayudar a gestionar la deuda técnica al proporcionar un registro claro de estos atajos y sus implicaciones.

1. Identificar las fuentes de deuda técnica. Identificar las fuentes de deuda técnica

• Documentar atajos: Documente claramente cualquier atajo o solución temporal implementada durante el proyecto. Explique por qué se tomaron estos atajos y cuáles son sus impactos potenciales.
• Documentar los atajos
• Seguimiento de elementos de deuda: Mantenga una lista de elementos de deuda técnica y actualícela periódicamente. Esta lista debe incluir una descripción de cada elemento, su impacto y el esfuerzo estimado necesario para solucionarlo.
• Realizar un seguimiento de los elementos de deuda técnica:Mantenga una lista de elementos de deuda técnica y actualícela periódicamente

2. Desarrollar un plan de pago de la deuda

• Priorizar los elementos de deuda: Priorice los elementos de deuda técnica en función de su impacto y urgencia. Esto ayuda a planificar el proceso de amortización de la deuda de forma eficaz.
• Priorizar los elementos de deuda técnica:
• Asignar recursos: Asignar recursos y tiempo para abordar la deuda técnica en el plan del proyecto. Esto garantiza que el pago de la deuda no se descuide en favor de un nuevo desarrollo.
• Asigne recursos:
• Asigne recursos y tiempo para abordar la deuda técnica en el plan del proyecto

3. Revisar y actualizar regularmente

• Revisiones periódicas: Lleve a cabo revisiones periódicas de la lista de deuda técnica para asegurarse de que se mantiene actualizada y refleja el estado actual del proyecto.
• Actualizar la documentación: Actualizar la documentación para reflejar cualquier cambio en la deuda técnica y los pasos dados para abordarla.
• Actualizar la documentación para reflejar cualquier cambio en la deuda técnica y los pasos dados para abordarla

Resumen

A veces, no se trata de saber cuándo documentar (aunque te hayas hecho una idea gracias a este artículo), sino que se trata más bien de cómo documentar eficazmente tus decisiones arquitectónicas y técnicas. La documentación eficaz de las decisiones arquitectónicas y técnicas es un componente fundamental para el éxito de la gestión de proyectos de Salesforce. Si sigue los pasos descritos y las prácticas recomendadas, podrá crear una documentación clara, completa y valiosa que respalde el éxito del proyecto y a su cliente (ya sea interno o externo);

Una documentación adecuada no sólo facilita una mejor comunicación y toma de decisiones, sino que también ayuda a gestionar la deuda técnica, mitigar los riesgos y conservar conocimientos valiosos para futuros proyectos. Siguiendo los pasos descritos, los arquitectos de Salesforce pueden garantizar que sus prácticas de documentación contribuyen al éxito general y a la sostenibilidad de sus proyectos. Su futuro yo y sus colegas se lo agradecerán;