¿Cómo describes tu solución/sistema?

Question

Estoy a punto de escribir algunos estándares/directrices y plantillas que usarían los gerentes de proyectos, desarrolladores y analistas de negocios. El objetivo sería comprender mejor la solución que está o fue desarrollada.

Una parte de esto es proporcionar un estándar/directriz para documentar la solución. P.ej. documentando la pieza de software que resuelve/cumple con los requerimientos de usuario/caso comercial.

Ahora bien, ser un programador yo puedo ver que es imposible dictar y decir "cada solución debe definir X usando Y y presentarla de acuerdo a la Z", como XYZ no siempre es aplicable etc.

Sin embargo, sé que incluso para mis proyectos de hobby siempre termino describiendo mis soluciones de una forma u otra, módulos/componentes, comentarios de código fuente, API, modelo de base de datos, alguna taxonomía utilizada, un diario de registro, formato xml, etc.

Entonces, para continuar con mi trabajo, agradecería mucho si pudieras compartir lo que documentas para describir tu solución (y preferiblemente también cómo y por qué) - Sé que variará mucho dependiendo de muchos delgados gs pero cualquier respuesta general o específica es de interés. Gracias.

actualización no estaba claro, pero no me refería a las necesidades del usuario con Z. X Y me refiero a todos los posibles tipos de documentación de un sistema pueda tener. Por lo tanto, léalo como "imposible indicar que cada solución debe tener: lista de marcos requeridos, manual operativo para el software del servidor, datos maestros requeridos, matriz de requerimientos del usuario vs pruebas, especificación de la interfaz del usuario. Si bien tiene sentido producir un límite conjunto de requisitos, es difícil ser claro y preciso, ya que lo más importante/relevante es diferente de proyecto a proyecto.

Además, hace mucho tiempo que pregunté esto y nunca acepté una respuesta, lo siento por eso. tal vez, ya que es una cuestión abierta, sería mejor como un wiki de la comunidad?

Answer 1

SI este proyecto suyo va a disfrutar de cualquier tipo de longevidad, es posible que desee comenzar a pensar en utilizar alguna metodología alineada de la industria. Al final, probablemente gastará más tiempo y posiblemente termine con el mismo resultado final.

Depende también del nivel de documentación de que se trate: Para obtener orientación arquitectónica basada en la aplicación, consulte Microsoft Application Architecture Guide 2.0 (publicada recientemente).

Si su nivel es inferior, comience con algo como SandCastle y amplíe lógicamente lo que produce.

Personalmente, me gusta comenzar con un diagrama de interacción, simplemente mostrando cómo todos los componentes del sistema interactúan entre sí, luego tomar cada componente y dividirlo en clases. Divida las clases en diagramas de secuencia y continúe hasta llegar a los cuadros de estado del nivel del método o por muy bajo que tenga sentido para su proyecto.

Si es más alto nivel que necesita, echar un vistazo a mi anterior post: Enterprise, Systems and Application Architecture (best Practise)

Al final del día, siempre y cuando tenga sentido lógico a las personas que lo leen, y es útil (como opuesto a algo que solo tienes que entregar y nunca volverás a usar) lo has hecho bien.

El problema más grande a menudo es mantener la documentación actualizada. Eso lo llevará rápidamente a las tareas de creación/mejora de procesos y procedimientos.

Answer 2

documentación es siempre la parte más difícil de cualquier proyecto. Si quieres empezar de nuevo, entonces es posible que desee comprobar hacia fuera Domain Driven Design.

Usar plantillas de historia puede ser muy beneficioso si tiene la plantilla correcta.

Como [X]
Quiero [Y]
modo que [Z]

En una línea similar es posible que desee mirar a Use Cases

Answer 3

Muy poco ¡Desafortunadamente!

Sin embargo, si sus directrices son para administradores y desarrolladores, el idioma que use es tan importante como la forma en que lo presenta. Evitar el uso de palabras de moda y la jerga de marketing, (Here's a good list!)

personalmente encuentro diagramas y dibujos ayudan a reforzar las ideas, los gráficos de la interacción del usuario previsto con el sistema de flujo puede ayudar a presentar mejor lo que el sistema es supone hacer. (¡Con un análisis en profundidad de cómo el sistema realmente logra eso luego, por supuesto!)

Answer 4

Usa palabras del dominio actual.Si hay una palabra de dominio empresarial generalmente utilizada, utilice la misma palabra de forma coherente en la documentación y el código. Si hay un término de programación generalmente utilizado (por ejemplo, patrones de diseño bien conocidos), utilícelo al escribir código y documentar los detalles técnicos.

Para documentar cómo funcionará el programa, como parte del diseño de la interfaz de usuario, produzco secuencias de imágenes (en papel o PowerPoint) que muestran cómo los usuarios realizarán su tarea con la interfaz de usuario. Ese es un lenguaje común que todos entenderán, desde los usuarios hasta los clientes, los gerentes y los programadores.

Answer 5

Tal vez porque acabo de leerlo y sigue zumbando alrededor de mi cabeza, pero creo que vale la pena leer 37signals Getting Real. Si bien se trata de comenzar un proyecto, el enfoque de la documentación es muy agradable para mí (como programador). No es del gusto de todos, pero si los demás están de acuerdo con el enfoque, incluso podría hacer que la documentación sea placentera. Lo encontré así.

Answer 6

Aquí está una lista de cosas que me bajó por que creo que tiene sentido tener al describir una solución. Lo hice una wiki así que por favor únete y desafía y agrega.

1. datos Repositorios (donde se almacenan los datos? ¿Cómo se accede?)
2. Formato de datos (¿Qué formatos se utilizan? Cualquier nuevo introducido? Especificación) tamaño de crecer?
3. de configuración (que se pueden configurar, lo que es el valor por defecto) dependencias
4. Biblioteca/Marco/embalaje (proveedor, licencia, versión)
5. solución Construido (cómo adquirir todos los archivos, etc y paso a paso para construir)
6. Módulos (alcance definido/por qué se introdujo módulo) Documentación/Fuente de código
7. Clase (generado por Doxygen o equivalente)

también de interés: 1. Seguridad (¿qué área de la solución i s bajo seguridad, contraseña/encriptado, etc.) 2. Transferencia de datos (¿Qué se transfiere entre discos/red? Por qué variables el

Answer 7

Para extender el alcance de su proyecto, será mejor que use palabras de dominio para la comunicación. Para el descubrimiento de requisitos, se puede usar prototype tools para construir la interfaz de usuario rápidamente para garantizar que los requisitos se comprendan bien. En caso de que su propósito sea encontrar la mejor manera de documentar soluciones, creo que tiene algo que ver con solution architecture. También creo que el estándar IEEE 1471 proporciona un enfoque holístico para documentar la arquitectura del software. También consulte el enfoque perspectives and viewpoints. Por supuesto que puedes hacerlo con tus herramientas UML favorate.

Answer 8

Básicamente hay muchas maneras de documentar los proyectos. 2 enfoques que he utilizado en el pasado son 1) desarrollo impulsado por el uso y 2) desarrollo impulsado por prueba. Como solo utilicé el desarrollo impulsado por Test una vez, estoy aconsejando cómo usar el desarrollo impulsado por Use-Case.

La clave aquí es utilizar la notación UML a fondo. Los usuarios, analistas de negocios y desarrolladores hablan diferentes idiomas (obviamente) y lo que intenta hacer es hacer que su documentación tenga sentido. Hay 3 documentos básicos que son claves.

1. Especificaciones comerciales - Este documento es producida por el usuario, sin ningún tipo de interferencia o consulta con el equipo de desarrollo. ¿Por qué? porque este documento necesita captura puramente lo que necesita el usuario. Ejemplo, el usuario quiere un programa para hacer café. En este momento, la cafetera del usuario debe encenderse manualmente. El cerebro del usuario requiere tiempo para ejecutar todos los cilindros por la mañana.

2. Especificación de requisitos de software - Aquí es donde el analista descompone los requisitos del usuario en especificaciones funcionales. El analista crea flujos en función de las necesidades del usuario. Aquí es donde empiezas a usar UML. Comience con Casos de uso y Diagramas de actividad para obtener una idea de cómo se va a sentir el sistema. Obtenga otras especificaciones derivadas, como requisitos de seguridad y otras necesidades, como restricciones de infraestructura.

3. Descripción del diseño del software: este es el documento técnico que la arquitectura o el diseñador de la solución produce para diseñar la solución que cumpla con los requisitos. El arquitecto descompone las especificaciones funcionales y traduce los flujos en especificaciones técnicas. Cada caso de uso se puede dividir en Diagramas de Secuencia y Diagramas de Comunicación. Lo que puedes hacer con estos diagramas es comenzar a crear las funciones para las clases. Estos diagramas se pueden usar para desarrollar diagramas de clase. State Machines, como sabrá, divide los diagramas de clase pero, por lo general, no voy tan lejos. También puede documentar toda la arquitectura y desglosar sus componentes en este documento mediante Component Structures. El documento también puede incluir la infraestructura de despliegue que el sistema va a ser puesto en.

El uso de estos 3 documentos en conjunto pueden ayudar a los lectores a comprender cómo funcionan las cosas en el sistema mejor. Los programadores pueden entender de dónde vienen las especificaciones técnicas y cómo necesitarán funcionar. Si no puede hacer una especificación técnica comprensible para los programadores con el fin de realizar las funciones correctas, también podría decirles cómo van a necesitar funcionar.

Para coordinar con miembros de equipos de diferentes niveles, por ejemplo, usuarios, gerentes, analistas de negocios, arquitectos de soluciones y programadores, creo una matriz que conecta especificaciones comerciales, especificaciones funcionales y especificaciones técnicas/de diseño. La matriz también incluirá módulos de prueba que se coordinarán con los elementos que se probarán. La matriz es realmente valiosa cuando se implementa el método de desarrollo V-Model.

Matrix Ejemplo: "Necesidad de la empresa A" -> "Functional Spec A" y "funcional Spec B" "Functional Spec A" -> "Componente A", "componente B", y "Componente C" "Componente B" -> "Clase A" y "Clase B"

Por supuesto, esto siempre se ve mejor en una hoja de cálculo.

Answer 9

TOGAF (El Open Group Architecture Framework) define un "método" de cómo un arquitecto debe definir una solución. Una parte de TOGAF también participa en la definición de qué entrada y salida deben producirse como parte de un proyecto arquitectónico.

Sin embargo, para su pregunta de qué documentación necesita que se comparta entre varias personas (BA, Programadores, Probadores, Administradores, etc.), debe mirar Vistas y Visores en TOGAF. Todas estas personas que mencionas son tus partes interesadas, y las Vistas y Puntos de Vista abordan las preocupaciones de los interesados. Por lo tanto, te animo a que pruebes las vistas y los puntos de vista.