Guía del analista de negocio para una buena documentación

La tarea de un analista de negocio no es sólo obtener y documentar requisitos de negocio sólidos y artefactos de soluciones, sino también estructurarlos de una manera que sea accesible a una serie de partes interesadas.

Su razón de ser es analizar y articular el negocio de forma que mejore la capacidad de su equipo para ofrecer valor al cliente de forma eficiente. Entonces, ¿cómo se masajean conjuntos de requisitos y artefactos de soluciones cada vez más grandes y complejos en algo que sea factible de mantener y ampliamente útil?

Construir un caso para la documentación

Todos hemos pasado por lo mismo: los plazos son ajustados, el presupuesto mengua… y la documentación suele ser lo primero que se tira por la ventana para ahorrar valiosos recursos.

En primer lugar, tenemos que construir el caso de negocio para una buena documentación, tanto internamente como para el cliente.

Una buena documentación nos permite reducir el tiempo dedicado a entender el negocio y la solución para que podamos centrarnos en la entrega eficiente de resultados valiosos para el cliente.

A nadie le gusta seguir las migas de pan

Imagínese que está trabajando en un nuevo proyecto empresarial y el propietario del producto le pregunta por qué el arquitecto anterior introdujo un objeto personalizado en lugar de utilizar una función estándar de Salesforce.

Sin una documentación que describa tanto el caso empresarial como la solución técnica, se queda en la estacada, buscando migas de pan en el pasado del arquitecto, intentando comprender la lógica de una decisión pasada y cómo puede influir en el trabajo que es responsable de entregar ahora. Esta situación puede evitarse con una documentación concisa.

Un mejor camino hacia adelante

La documentación de calidad debe permitir a los equipos de proyecto:

• Comprender las funciones, los procesos y los requisitos clave del negocio.
• Expresar claramente cómo la solución sirve a la(s) necesidad(es) empresarial(es)
• Comunicar cómo y por qué se construyó una solución, dadas las herramientas y los recursos disponibles.
• Digerir rápidamente cómo encaja la solución en el panorama técnico más amplio del cliente.

La documentación como entregable

Aumente la responsabilidad de la documentación de calidad incluyendo artefactos clave como entregables en su Alcance del trabajo.

Acordar mutuamente los artefactos necesarios con el cliente ayuda a generar confianza, garantizar que los requisitos y las soluciones pasen por un proceso de validación establecido (para evitar sorpresas posteriores) y responsabilizar al equipo del proyecto de la entrega de documentación que respalde la solución durante años.

Consejo: es menos costoso documentar ahora, mientras está fresco, que dedicar tiempo a documentar requisitos o soluciones retrospectivamente.

Principios de una buena documentación

El analista de negocio debe ser experto en desenredar la complejidad y crear orden a partir del caos. Su papel es proporcionar a su equipo claridad sobre el negocio y actuar como una autoridad sobre cómo la solución satisface las necesidades del negocio.

Siguiendo el mantra de Salesforce Well-Architected de trusted, fácil y adaptable, la documentación que produzca debe ser concisa, contextualizada, coherente y conectada.

Conciso pero contextualizado

Hay que encontrar un equilibrio entre proporcionar el contexto suficiente para que los lectores entiendan el «por qué» de los requisitos y las soluciones sin que los artefactos se vuelvan pesados de digerir.

Las estrategias para mejorar la legibilidad de la documentación incluyen:

• «Descomponer» los requisitos funcionales: Seguir una estructura de descomposición coherente para su información empresarial ayuda a los lectores a comprender primero el panorama general y luego profundizar en niveles inferiores de granularidad según sea necesario. Un conjunto bien estructurado de procesos empresariales permite a su audiencia precisar la parte del negocio que les concierne para que sólo ingieran la información relevante para su necesidad inmediata.
• Siga los requisitos funcionales
• Siga los «niveles de diagrama» de Salesforce Architect para la documentación técnica: Presentar la documentación técnica en el «nivel» correcto ayuda a garantizar que las audiencias técnicas (es decir, los desarrolladores) tengan el contexto requerido que necesitan sin distraerse con detalles. Salesforce Architects propone identificar el nivel de cada artefacto técnico para ayudar a los lectores a entender el propósito del documento:

Consejo: Cada pieza de documentación debe responder a una pregunta muy clara. Si los miembros de su equipo formulan constantemente una pregunta que el cuerpo actual de la documentación no puede responder, considere la posibilidad de añadirla y archivar la documentación que ya no sirva para nada.

Por último, documente sólo lo que realmente se necesita. Dependiendo de la escala y complejidad de su proyecto, la naturaleza de su documentación debe cambiar. Alinéese con su arquitecto de soluciones para generar una lista de artefactos esenciales que no sean negociables antes de dar el pistoletazo de salida.

La consistencia es la clave

La coherencia es clave, tanto para ahorrar tiempo como para producir artefactos de alta calidad una y otra vez. Algunas formas sencillas de reforzar la coherencia en su corpus de documentación son:

• Elaboración de normas de documentación para su uso en clientes y proyectos: Tanto si eres autónomo como si trabajas para una empresa consolidada, tu equipo debe contar con un conjunto de normas de documentación que describan las estrategias y expectativas para producir y mantener una documentación de calidad.
• Diseñar modelos de documentación para su uso en clientes y proyectos
• Templatizar artefactos esenciales: Produzca material de plantillas de alta calidad que pueda aplicar a cada proyecto para reducir el tiempo de configuración de la documentación.
• Personalice la documentación
• Personalizar sólo cuando sea necesario: Realice personalizaciones del material de plantilla o introduzca documentos totalmente personalizados sólo cuando sea absolutamente necesario. Asegúrese de que existe una pregunta clara a la que hay que responder antes de introducir un documento personalizado.
• Personalizar sólo cuando sea necesario

Consejo: Salesforce Architects y LucidChart disponen de plantillas de Salesforce listas para usar, incluidos ERD prediseñados, diagramas de entorno del sistema, etc. que puede empezar a utilizar hoy mismo.

Soluciones técnicas conectadas a requisitos funcionales

Un punto doloroso común de la documentación es la comprensión de la relación entre los artefactos técnicos y la función de negocio que apoyan.

• Sus requisitos funcionales responden a la pregunta: «¿Qué hace/necesita el negocio?»
• Sus artefactos técnicos responden a la pregunta: «¿Cómo resolvimos el requisito?»

La brecha a menudo existe en el «por qué»:

• «¿Por qué estamos resolviendo este requisito con esta solución concreta en este momento concreto?»

En una plataforma tan prolífica como Salesforce, a menudo existen múltiples formas de resolver un mismo requisito. Explicar claramente por qué se ha tomado una determinada decisión de diseño es crucial para ayudar a los futuros equipos de proyecto a diseñar de forma inteligente en una org de brownfield, así como para que el cliente pueda comprender la solución que poseerá en los próximos años.

Algunas formas prácticas de vincular su documentación técnica y funcional incluyen:

• Elaborar una descripción general narrativa de la solución que explique cómo la solución cumple con el estado deseado del sistema en un lenguaje sencillo
• Incluir un conjunto de decisiones de diseño clave que describan por qué se tomaron determinadas decisiones de arquitectura, incluidas las compensaciones y limitaciones.
• Incluir un conjunto de decisiones de diseño clave que describan por qué se tomaron determinadas decisiones de arquitectura, incluidas las compensaciones y limitaciones
• Utilizar un sistema de codificación para los flujos de procesos y hacer referencia a qué proceso soporta una solución técnica
• Escribir resúmenes de soluciones de alto nivel en relación con las epopeyas
• Escribir notas de configuración de bajo nivel contra historias de usuario.

Consejo: Alinee su documentación con una visión central para el sistema. Si su cliente tiene una visión relacionada con la mejora de la simplicidad y la experiencia del usuario, por ejemplo, su documentación debe destacar cómo la solución apoya esta visión.

Organización de los artefactos de documentación

Organizar la documentación requiere esfuerzo; sin embargo, con una forma de trabajo establecida, se puede minimizar el tiempo dedicado a gestionar y localizar los artefactos importantes.

Altitud del artefacto

La disponibilidad de la documentación y la accesibilidad no son iguales – el hecho de que una información esté disponible en algún lugar del corpus de la documentación de la cuenta no significa que sea inmediatamente accesible para el interesado que la necesita al alcance de su mano en un breve plazo.

Para recuperar y mantener la documentación de forma rápida y sencilla, es necesario que exista una única fuente de información y que ésta se encuentre en un lugar lógico.

Considere la automatización de la documentación para cuentas a gran escala con múltiples flujos de trabajo. El caso de uso para la nueva automatización puede ser específico para el flujo de trabajo, pero la automatización afecta el trabajo completado en otro flujo de trabajo concurrente.

<li
• Documentación a nivel de cuenta debe contener toda la documentación que afecta a la cuenta en su conjunto – es independiente del proyecto. Los ejemplos pueden incluir:
  • Panoramas generales de automatización
  • Decisiones clave de diseño arquitectónico
  • Decisiones clave de diseño arquitectónico
  • Diagramas del panorama del sistema
  • Diagramas ERD exhaustivos
  • Mapa de ruta

<li

• Documentación a nivel de proyecto debe contener la documentación que es específica para esa pieza de trabajo en particular y que probablemente no necesitaría ser referenciada por las partes interesadas que trabajan en otra faceta de la cuenta. Los ejemplos pueden incluir:
  • Historias de usuarios
  • Modelos físicos para piezas discretas de funcionalidad
  • Registros de riesgos específicos del proyecto
  • Línea de tiempo y presupuesto

<li

Al configurar sus sistemas de almacenamiento de documentos, considere dónde colocar determinadas piezas de documentación para garantizar que existan una sola vez y en la ubicación más accesible para todas las partes interesadas.

Manteniendo documentos vivos

Todos nos hemos enfrentado al horror de numerosos documentos duplicados, sin estar seguros de cuál es la versión correcta. Asegúrese de que sólo hay una fuente de verdad viva para cada uno de sus documentos clave.

Todos los cambios deben ser rastreados como versiones, con las versiones anteriores archivadas en un archivo para ayudar al seguimiento de los cambios en el tiempo, manteniendo el corpus accesible de la documentación libre de desorden.

Documentación «dentro-del-sistema»

La documentación no es algo que sólo ocurra «fuera del sistema». Salesforce ofrece una serie de formas útiles de contextualizar la configuración que los equipos de proyecto pueden aprovechar para apoyar futuros esfuerzos de aclaración y depuración.

Algunas estrategias sencillas de documentación dentro del sistema incluyen:

• Añadir siempre descripciones útiles de componentes de metadatos
• Añadir texto de ayuda a los campos cuando proceda
• Desarrollar convenciones de nomenclatura coherentes para la automatización y garantizar que los elementos y variables de Flujo se denominan y describen adecuadamente
• Añadir comentarios en línea a cualquier código personalizado y fórmulas complejas para explicar la lógica en lenguaje llano
• Depreciar componentes de metadatos utilizando convenciones de nomenclatura comunes (es decir, prefijo zDEP_)

Resumen

Centrarse en una documentación bien estructurada ayudará a:

• Equipar al equipo técnico para tomar decisiones de diseño informadas que aporten valor al negocio.
• Equipar al equipo técnico para tomar decisiones de diseño informadas que aporten valor al negocio
• Potenciar al cliente para que comprenda y valide de forma exhaustiva su solución.
• Reducir el tiempo perdido en la documentación
• Reduzca el tiempo perdido en ingeniería inversa, repetición de tareas y trabajo no planificado relacionado con la revisión de decisiones anteriores.

Al construir un caso de negocio coherente para la documentación que alinee a los equipos internos y externos, siguiendo las mejores prácticas de documentación y estructurando sus artefactos de una manera que tenga sentido, la documentación de alta calidad es alcanzable en cualquier proyecto.