Creación de Documentos de Diseño en Markdown para Proyectos de Software
Contenido del curso
Carlos Eduardo Gomez García
Emmanuel Rodríguez
RUBÉN HERNÁNDEZ PUERTA
José Alberto Ortiz Vargas
Marco Elizalde
Julio Gutierrez
Company_admin
Rafael Moro
José Alberto Ortiz Vargas
Jorge Villalobos Gutierrez
ProfesorEmmanuel Rodríguez
Marlon García Cedillo
David Montoya Perez
Jonathan Lopez Bello
Miguel Peláez
Sergio Iván Buitrago Merchán
Daniel Alessandro García Batres
Royer Guerrero Pinilla
Juan Carlos Pineros
Alex Camacho
ProfesorMarco Elizalde
Alexis Alexis Antonio Jiménez Joaquín
Jair Israel Avilés Eusebio
Nicoll Idaly Angulo Mejia
Julio Gutierrez
Company_admin
William Schnaider Torres Bermon
Irving Juárez
Andrea Lopez
Jorge Ivan Meza
José Calderón
Royer Guerrero Pinilla
Reinaldo Mendoza
Francisco Enrique Giménez Vera
Reinaldo Mendoza
Me parece importante el hecho de poner lo que está fuera del alcance, aunque seguramente muchas personas puedan decirte: ¿y por qué no los ponemos? Siempre me pasa jaja. . Adicionalmente aquí les dejo el template del Markdown aquí:
# Titulo: Template de documento de diseño --- ## Overview: Problema a resolver Descripción.. ### Alcance(Scope) Descripción.. #### Casos de uso Descripción... * Caso de uso 1 * Caso de uso 2 * ... #### Out of Scope (casos de uso No Soportados) Descripción... * Caso de uso 1 * Caso de uso 2 * ... --- ## Arquitectura ### Diagramas poner diagramas de secuencia, uml, etc ### Modelo de datos Poner diseño de entidades, Jsons, tablas, diagramas entidad relación, etc.. --- ## Limitaciones Lista de limitaciones conocidas. Puede ser en formato de lista. Ej. * Llamadas del API tienen latencia X * No se soporta mas de X llamadas por segundo --- ## Costo Descripción/Análisis de costos Ejemplo: "Considerando N usuarios diarios, M llamadas a X servicio/baseDatos/etc" * 1000 llamadas diarias a serverless functions. $XX.XX * 1000 read/write units diarias a X Database on-demand. $XX.XX Total: $xx.xx (al mes/dia/año)
Concuerdo contigo, es muy importante dejarlo establecido y más cuando hay un contrato de por medio,
jaja tienes razón, siempre pasa que les terminamos dando ideas de funcionalidades no contempladas.
Les comparto los casos de uso soportados y no soportados que agregue al documento:
#### Casos de uso Descripción... * Como editor me gustaria poder subir una review de una camara * Como editor me gustaria poder subir una review de un lente para las camaras * Como editor me gustaria poder subir review de accesorios para las camaras * Como usuario no registrado me gustaria poder leer una review #### Casos de uso No Soportados Descripción... * Como usuario no registrado me gustaria poder subir una review de una camara * Como editor me gustaria dar feedback a otras review * Como editor me gustaria aprobar comentarios en reviews de usuario registrados * Como usuario no registrado me gustaria registrarme * Como usuario no registrado me gustaria poder compartir una review en mis redes sociales * Como usuario registrado me gustaria comentar en las reviews * Como usuario registrado me gustaria dar seguimiento de los comentarios en la reviews que me interesan
Recomiendo utilizar Typora para leer, crear y editar archivos markdown
Gracias.
Typora es de paga. Yo les recomiendo un plugin de VS Code llamado "Markdown Preview Enhanced" que es para tener una vista previa junto al documento con extensión md.
Para exportar el documento "md" a pdf o imagenes pueden usar "Markdown PDF"
Con el tema de caso de uso soportados y no soportados, ¿es una buena practica ser detallista? Por ejemplo, por que no solo decir en un caso de uso: Como editor me gustaria poder subir una review de una camara y de lentes para camaras. Si no que este caso se divide en dos. ¿Por que?
son entidades diferentes. imagina que implementar reviews para camaras tarda 1 semana, si estás haciendo método ágil una historia así toda junta va a estar tardadisima. también es más dificil de probar. imagina que también al final, la gente puede publicar 100 veces más reviews de lentes que de camaras, porque de pronto se producen más lentes al año que camaras. pudiera hasta tener requerimientos de escalabilidad diferentes. así podrían salir cosas después.
Son eventos diferentes y el ser detallista ya te pone, dentro del ciclo de vida del software, en la etapa de diseño.
Recuerda que diseño no es la UI sino, desde un punto de vista en 3ra persona o "no técnico", se establecen los eventos que determinan flujos, funcionalidad y experiencia.
Comparto mi idea
Las limitaciones me parecen complicadas de redactar. Poder dar la cantidad exacta (o aproximada) de los valores que queremos limitar, me parece que solo se dan cuando ya tenemos algo de experiencia en el tema. Si intento hacerlo con una API en un ambiente mas real, no sabria que numeros poner.
Las limitaciones no me convencen realmente como se estan redactando aca.
Casos de usos = Historias de usuarios
No es exactamente igual. Pero son equivalentes.
Comparto mi documento de diseño (El inicio). Es algo sencillo tecnica y funcionalmente.
# Sala de conciertos --- ## Overview: Se requiere visibilizar los proximos eventos de las agrupaciones musicales de forma ordenada según calendario. Estos eventos serán cargados por los mismos organizadores de los eventos o por las mismas bandas en una pantalla emergente de gestión. Una vez que cada evento se cree se generará un código único. de 8 digitos. Una vez cada evento alcance su fecha de ejecución más un día será retirado de la lista. Los eventos podrán ser eliminados de la lista con un código único generado. En caso de que haya varios eventos en la misma fecha, no se hará organización adicional. ### Alcance(Scope) Desarrollo de un portal web de visualización libre de publicidad acorde a los eventos de agrupaciones musicales, la cual puede ser cargada, modificada y eliminada unicamente por los gestores del evento. #### Casos de uso Descripción... * Como **espectador** quiero entrar a la página principal y ver un listado de los próximos eventos. * Como **espectador** quiero ver el listado de los próximos eventos organizados por la fecha. * Como **espectador** me gustaría al hacer clic, ver información más detallada del evento. * Cómo **gestor** quiero ver un botón que me permita acceder a una página de gestión de eventos. * Cómo **gestor** quiero poder ver dos opciones iniciales en la pantalla emergente de gestíon de eventos: Crear evento y Gestionar evento. * Cómo **gestor** quiero poder crear un evento cargando el flyer de la banda y demás información asociada al mismo. * Cómo **gestor** quiero recibir en mi celular un SMS y un correo indicando el código único de gestión del evento, una vez el evento haya sido creado. * Cómo **gestor** estando ubicado en la pantalla de Gestionar Evento, quiero poder ingresar el código que recibí previamente. * Cómo **gestor** al ingresar correctamente el código, quiero ver una ventana que me permita editar la información del evento o eliminarlo de ser requerido. #### Out of Scope (casos de uso No Soportados) Descripción... * Como **espectador** me gustaría filtrar los eventos por fecha, ubicación, género, etc. * Cómo **gestor** me gustaría personalizar la forma en que se visualiza mi evento. * Cómo **gestor** me gustaría tener un botón de compra de boleteria en cada evento. * Cómo **dueño del portal** me gustaría compartir automaticamente los eventos creados en todas mis redes sociales el día anterior y el dia del evento.
Template en ingles
# Title: Design Document Template --- ## Overview: Problem to Solve Description... ### Scope Description... #### Use Cases Description... * Use Case 1 * Use Case 2 * ... #### Out of Scope Description... * Use Case 1 * Use Case 2 * ... --- ## Architecture ### Diagrams Include sequence diagrams, UML diagrams, etc. ### Data Model Include entity design, JSON structures, tables, entity-relationship diagrams, etc. --- ## Limitations List of known limitations. Can be in list format. E.g., * API calls have latency X * No support for more than X calls per second --- ## Cost Description/Cost analysis E.g., "Considering N daily users, M calls to service/database/etc." * 1000 daily calls to serverless functions. $XX.XX * 1000 read/write units daily to X Database on-demand. $XX.XX Total: $xx.xx (per month/day/year)
Mis casos de uso
Casos de uso
Out of Scope
Hasta que punto es necesario poner lo que no se cubre con la arquitectura? en mi concepto esto no se debe poner, ya que puede salir infinidad de cosas que al cliente se le ocurran y que no esten especificadas en esta sección. Me parece que solo de estar que cubre lo que este en los casos de uso, lo que no este alli no esta contemplado y ya.
Cuando haces un proyecto debes de especificar lo que se espera que se haga y lo que no se espera que se haga, esto con el fin de evitar por ejemplo malos entendidos entre muchas otras cuestiones.
Es muy importante, ya que debe de quedar muy claro para todos los involucrados, principalmente el cliente, que no va a hacer el sistema a desarrollar y que esto no influya para aceptación del proyecto.
¿puedo utilizar este template para realizar un sistema aunque no sea api?
Asi es, como se menciono el template es para trabajar el diseño agnostico de un sistema.
Las limitaciones me parecen más un SLO
Para el cálculo de costos, existe alguna calculadora que de datos muy certeros?
Hablando de Cloud providers... ellos ofrecen calculadores para realizar estimaciones de cuanto podrá costar implementar una solución, por ejemplo:
La parte de limitaciones me parece que se podria hacer al final del proyecto, cuando conocemos issues bien conocidos
La ídea de colocar un costo estimado de la solución me parece muy interesante
Esos "casos de uso" se parecen mas a historias de usuario pero les falta la sección PARA.
La página de diagramas que está en la sección recursos, no tiene diagrama de casos de uso.
Feedback please...
Scope
Creacion de una infractructura backend basada en cloud computing y la creacion de una API que incluya los diferentes endpoints para poder cumplir con los casos de uso.
Podria ser mas especifico, pero buen inicio
EL PUNTO ES QUE SE ENTIENDA
Si senor, tener claro que es lo que se quiere resolver
