El propósito de esta actividad es elaborar el esquema de documentación del proyecto en la Wiki del repositorio en Github. A partir de este esquema, los integrantes del equipo podrán ir diligenciando cada espacio en la medida que van avanzando en las actividades del proyecto.
Al final, la Wiki del repositorio debe presentar una página similar a la siguiente:
En la página principal del repositorio, elija la pestaña Wiki, la cual se señala en la siguiente imagen:
Aparecerá la Wiki en blanco, como se muestra a continuación:
En la Wiki, elija la opción para crear la primera página (Create the first page), de manera que se muestre la página a continuación:
En la parte del nombre de la página se debe dejar Home, en el texto ingrese el título del proyecto y los integrantes del equipo de trabajo, y escriba un mensaje para el commit de la wiki, como se muestra a continuación.
Una vez termine, guarde la página, de manera que se vea de la siguiente manera:
Luego de creada la página principal, se deben crear los espacios para registrar la documentación del proyecto. Cada espacio se va a crear como una página que se puede navegar a través del bloque o barra lateral en la wiki y se clasificará bajo un título en el bloque o barra lateral. Inicialmente se crearán las páginas únicamente con los títulos, y luego se irán editando para actualizar los contenidos en la medida que se van generando.
El primer espacio por crear es el que tendrá la documentación de las historias de usuario, el cual incluirá las páginas para las historias que documenta cada integrante, las historias unificadas por el equipo y las historias detalladas.
Para crear un bloque o barra lateral, elija el enlace "+ Add a custom sidebar", de manera que aparezca una página como la siguiente:
En la página, se debe dejar el nombre de la página sin modificar, y en el contenido escribir los títulos de los bloques que se tendrán y por cada título, los nombres de los espacios a documentar:
Una vez queden guardados los cambios la wiki se verá de la siguiente manera
A continuación se deben crear las páginas para cada uno de los elementos de la documentación. Para crear una página, se elige el botón "New Page" en la parte superior de la wiki:
Al elegir el botón se muestra el espacio para crear una página en la wiki, como se muestra a continuación:
Diligencie los campos de la siguiente manera:
- Título: Escriba el título de la página correspondiente al documento que se referencia en el bloque o barra lateral, para el caso del primer título debe ser "Modelo conceptual".
- Contenido: Se escribe por ahora el título en markdown de la página, para el caso actual "#### Modelo conceptual".
- Mensaje: El texto correspondiente a la acción realizada, en este caso, "Página de Modelo conceptual creada"
La página antes de guardar se debe ver de la siguiente manera:
Luego de guardar aparecerá la página con el contenido ingresado, como se muestra a continuación:
Ingrese a la página que desea enlazar, continuando con el ejemplo anterior, la página llamada "Modelo conceptual". Si no puede ver la página o el enlace, puede desplegar el bloque lateral Pages, para ver la lista de páginas creadas:
Copie el nombre de la página de la URL, como se muestra a continuación:
Luego, edite la barra lateral eligiendo el lápiz que se encuentra en la parte superior derecha de la barra:
En el espacio de edición actualice el texto correspondiente adicionando el enlace al nombre de la página, y escriba un mensaje con la descripción del cambio, como se muestra a continuación:
Al guardar la página se verá el enlace que se actualizó, como aparece en la imagen a continuación. Pruebe que el enlace funciona y repita los pasos de esta sección en caso de algún error.
Para crear las demás páginas, repita el procedimiento descrito en esta sección.
A continuación se explican los formatos en el lenguaje Markdown que se utilizarán en los espacios de documentación. Se presentan los formatos para:
- Listado de historias de usuario: Se utiliza en la documentación de las historias de usuario que propone cada estudiante y su correspondiente revisión. Se utiliza también para documentar el listado de historias de usuario consolidado por los estudiantes y dejar el enlace a cada historia de usuario detallada en este listado.
- Historia de usuario detallado: Se utiliza en la documentación del detalle de historias de usuario que realizan los estudiantes y su correspondiente revisión.
- Glosario: Permite la documentación de términos utilizados en el proyecto.
Este formato permite documentar las historias de usuario escritas por cada estudiante y la revisión que se realiza sobre dichas historias. El formato se compone de dos tablas, donde la primera permite documentar las historias, y la segunda, registrar su revisión. El formato se ve de la siguiente manera:
Listado de historias de usuario
Código | Nombre | Descripción | Responsable |
HU<<AAA>> | <<Nombre>> | <<Descripción>> | @usuario |
HU<<AAA>> | <<Nombre>> | <<Descripción>> | @usuario |
HU<<AAA>> | <<Nombre>> | <<Descripción>> | @usuario |
Revisión
Criterio | Comentario | Realizado por |
Forma | <<Comentario>> | @usuario |
Completo | <<Comentario>> | @usuario |
Consistente | <<Comentario>> | @usuario |
Independiente | <<Comentario>> | @usuario |
El listado de historias de usuario se documenta como una tabla, donde cada fila corresponde a una historia de usuario. A continuación se explica cada celda de la tabla:
- El campo HU<<AAA>> representa la historia de usuario (HU) con un consecutivo representado por el comodín <<AAA>>, que va desde 000 en adelante. Para el listado de historias de usuario, este campo también será un enlace a la historia de usuario detallada.
- <<Nombre>> es el comodín que representa el nombre de la historia de usuario
- <<Descripción>> es el comodín que representa la descripción de la historia de usuario en el formato Como X quiero Y para Z
- @usuario representa la persona que se asignará como responsable de detallar la historia en una actividad posterior.
La revisión del listado se documenta como una tabla también, la cual contiene las filas Forma, Completo, Consistente e Independiente. En la columna a continuación, en el espacio <<Comentario>>, se diligenciará en el momento de la revisión el comentario correspondiente a cada criterio. En la última columna, se registrará el usuario que realizó el comentario correspondiente al criterio.
Un ejemplo de la documentación de dos historias de usuario y el formato de revisión es el siguiente:
Listado de historias de usuario
Identificador | Nombre | Descripción | Responsable |
HU000 | Ingresar al sistema | Como administrador quiero ingresar al sistema con un usuario y contraseña para ingresar al panel de control principal | Juan Pablo Reyes |
HU001 | Recuperar contraseña | Como paciente me gustaría recuperar mi contraseña con el fin ingresar de nuevo al sistema cuando haya olvidado mi contraseña. | Juan Pablo Reyes |
Revisión
Criterio | Comentario | Realizado por |
Forma | La HU001 no tiene la forma adecuada porque (...) | Ricardo Calle Archila |
Completo | El listado no es completo porque (...) | Ricardo Calle Archila |
Consistente | El listado no es consistente porque (...) | Ricardo Calle Archila |
Independiente | Las historias son independientes porque (...) | Ricardo Calle Archila |
A continuación se copia el formato de la plantilla en Markdown:
## Listado de historias de usuario
| Identificador | Nombre | Descripción | Responsable |
|------------------------|--------------|-----------------|-------------|
| [HU<<AAA>>](HU<<AAA>>) | << Nombre >> | <<Descripción>> | @Usuario |
| [HU<<AAA>>](HU<<AAA>>) | << Nombre >> | <<Descripción>> | @Usuario |
| [HU<<AAA>>](HU<<AAA>>) | << Nombre >> | <<Descripción>> | @Usuario |
### Revisión
| Criterio | Comentario | Realizado por |
|---------------|------------------|---------------|
| Forma | << Comentario >> | @usuario |
| Completo | << Comentario >> | @usuario |
| Consistente | << Comentario >> | @usuario |
| Independiente | << Comentario >> | @usuario |El ejemplo anterior en Markdown se escribiría de la siguiente manera:
## Listado de historias de usuario
| Identificador | Nombre | Descripción | Responsable |
|----------------|----------------------|-----------------|------------------|
| [HU000](HU000) | Ingresar al sistema | Como administrador quiero ingresar al sistema con un usuario y contraseña para ingresar al panel de control principal | Juan Pablo Reyes |
| [HU001](HU001) | Recuperar contraseña | Como paciente me gustaría recuperar mi contraseña con el fin ingresar de nuevo al sistema cuando haya olvidado mi contraseña | Juan Pablo Reyes |
### Revisión
| Criterio | Comentario | Realizado por |
|---------------|---------------------------------------------------|-----------------------|
| Forma | La HU001 no tiene la forma adecuada porque (...) | Ricardo Calle Archila |
| Completo | El listado no es completo porque (...) | Ricardo Calle Archila |
| Consistente | El listado no es consistente porque (...) | Ricardo Calle Archila |
| Independiente | Las historias de usuario son independientes (...) | Ricardo Calle Archila |Este formato permite documentar el detalle de cada historia de usuario realizada por los estudiantes y su correspondiente revisión. El formato se compone de dos tablas, donde la primera permite detallar la historia, y la segunda, registrar su revisión. El formato se ve de la siguiente manera:
Historia de usuario detallada
Identificador | HU<< AAA >> |
Nombre | << Nombre >> |
Descripción | << Descripción >> |
Criterios de aceptación | << Criterios de aceptación >> |
Mockups | << Mockups >> |
Autor | @usuario |
Revisión
Criterio | Comentario | Realizado por |
Completo | << Comentario >> | @usuario |
Consistente | << Comentario >> | @usuario |
Negociable | << Comentario >> | @usuario |
Valiosa | << Comentario >> | @usuario |
Estimable | << Comentario >> | @usuario |
Pequeña | << Comentario >> | @usuario |
Comprobable | << Comentario >> | @usuario |
Cada historia de usuario se detalla en una tabla, donde en cada fila se identifican los campos a documentar, y al frente la información correspondiente a cada campo. A continuación se explica cada fila de la tabla:
- Identificador: Corresponde al identificador de la historia de usuario en el listado de historias de usuario. Se debe tener ne cuenta que <<AAA>> representa un consecutivo, desde 000 en adelante.
- Nombre: Corresponde al nombre de la historia de usuario como aparece en el listado de historias de usuario y se diligencia en reemplazo del comodín <<Nombre>>.
- Descripción: Corresponde a la descripción de la historia de usuario como aparece en el listado de historias de usuario, y se diligencia en reemplazo del comodín <<Descripción>>. Conserva el formato Como X quiero Y para Z.
- Criterios de aceptación: El comodín <<Criterios de aceptación>> se reemplaza por una lista de criterios con los que la historia se acepta cuando se termine su desarrollo. Cada criterio puede escribirse en una fila de la tabla para mayor claridad en su visualización.
- Mockups: El comodín <<Mockups>> se reemplaza por las imágenes de los mockups con los que se modela la interfaz y la interacción con la historia de usuario.
La revisión de la historia se documenta como una tabla también, la cual contiene las filas Completo, Consistente, Negociable, Valiosa, Estimable, Pequeña y Comprobable. En la columna a continuación, en el espacio <<Comentario>> se diligenciará en el momento de la revisión el comentario correspondiente a cada criterio. En la última columna, se registrará el usuario que realizó el comentario correspondiente al criterio.
Un ejemplo de la documentación del detalle de una historia de usuario y el formato de revisión es el siguiente:
Historia de usuario detallada
Identificador | HU001 |
Nombre | Recuperar contraseña |
Descripción | Como paciente quiero recuperar mi contraseña con mi correo electrónico para ingresar de nuevo al sistema cuando haya olvidado mi contraseña. |
Criterios de aceptación | Cuando se escribe un correo electrónico y se elige el botón aceptar, el sistema valida si el correo se encuentra registrado, y dado el caso, envía un mensaje al correo electrónico escrito con una nueva contraseña de ingreso y muestra por pantalla un mensaje de envío de correo exitoso. |
Cuando se escribe un correo electrónico y se elige el botón aceptar, el sistema valida si el correo se encuentra registrado, y si no lo está, muestra por pantalla un mensaje de envío de correo exitoso. | |
Cuando no se escribe un correo electrónico y se elige el botón aceptar, el sistema muestra un mensaje de error que indica que el campo de correo electrónico está vacío. | |
Mockups |
|
Autor | Ricardo Calle Archila |
Revisión
Criterio | Comentario | Realizado por |
Completo | La historia no está completa porque (...) | Juan Pablo Reyes |
Consistente | La historia es consistente porque (...) | Juan Pablo Reyes |
Negociable | La historia es imprescindible, se (...) | Juan Pablo Reyes |
Valiosa | La historia no es valiosa porque (...) | Juan Pablo Reyes |
Estimable | La historia se puede estimar porque (...) | Juan Pablo Reyes |
Pequeña | La historia tiene un tamaño que (...) | Juan Pablo Reyes |
Comprobable | La historia no es comprobable (...) | Juan Pablo Reyes |
A continuación se copia el formato de la plantilla en Markdown:
## Historia de usuario detallada
| Identificador | HU<< AAA >> |
|-------------------------|--------------------------------|
| Nombre | << Nombre >> |
| Descripción | << Descripción >> |
| Criterios de aceptación | << Criterios de aceptación >> |
| Mockups | << Mockups >> |
| Autor | @usuario |
### Revisión
| Criterio | Comentario | Realizado por |
|---------------|------------------|---------------|
| Completo | << Comentario >> | @usuario |
| Consistente | << Comentario >> | @usuario |
| Negociable | << Comentario >> | @usuario |
| Valiosa | << Comentario >> | @usuario |
| Estimable | << Comentario >> | @usuario |
| Pequeña | << Comentario >> | @usuario |
| Comprobable | << Comentario >> | @usuario |El ejemplo anterior en Markdown se escribiría de la siguiente manera:
## Historia de usuario detallada
| Identificador | HU001 |
|-------------------------|--------------------------------|
| Nombre | Recuperar contraseña |
| Descripción | Como paciente quiero recuperar mi contraseña con mi correo electrónico para ingresar de nuevo al sistema cuando haya olvidado mi contraseña. |
| Criterios de aceptación | Cuando se escribe un correo electrónico y se elige el botón aceptar, el sistema valida si el correo se encuentra registrado, y dado el caso, envía un mensaje al correo electrónico escrito con una nueva contraseña de ingreso y muestra por pantalla un mensaje de envío de correo exitoso. |
| | Cuando se escribe un correo electrónico y se elige el botón aceptar, el sistema valida si el correo se encuentra registrado, y si no lo está, muestra por pantalla un mensaje de envío de correo exitoso. |
| | Cuando no se escribe un correo electrónico y se elige el botón aceptar, el sistema muestra un mensaje de error que indica que el campo de correo electrónico está vacío. |
| Mockups | [Recuperar contraseña](https://github.com/TiCSw/docs/images/ recuperarContraseña.png "Recuperar contraseña") |
| Autor | Ricardo Calle Archila |
### Revisión
| Criterio | Comentario | Realizado por |
|---------------|-------------------------------------------|------------------|
| Completo | La historia no está completa porque (...) | Juan Pablo Reyes |
| Consistente | La historia es consistente porque (...) | Juan Pablo Reyes |
| Negociable | La historia es imprescindible, se (...) | Juan Pablo Reyes |
| Valiosa | La historia no es valiosa porque (...) | Juan Pablo Reyes |
| Estimable | La historia se puede estimar porque (...) | Juan Pablo Reyes |
| Pequeña | La historia tiene un tamaño que (...) | Juan Pablo Reyes |
| Comprobable | La historia no es comprobable (...) | Juan Pablo Reyes |Este formato permite documentar el glosario de términos utilizados en el proyecto. El formato se de una tabla que se ve de la siguiente manera:
Glosario de conceptos
Concepto | Descripción | Observaciones |
<< Nombre >> | << Descripción >> | << Observaciones >> |
<< Nombre >> | << Descripción >> | << Observaciones >> |
<< Nombre >> | << Descripción >> | << Observaciones >> |
El glosario se documenta como una tabla, donde cada fila corresponde a la definición de un término o concepto. A continuación se explica cada celda de la tabla:
- El campo <<Nombre>> se reemplaza por el concepto a definir, y representa un término utilizado en el proyecto.
- El campo <<Descripción>> representa la definición del concepto, y se reemplaza por dicha definición.
- El campo <<Observaciones>> se reemplaza por un texto, y hace referencia a comentarios o aclaraciones respecto al concepto.
Un ejemplo de algunos términos en el glosario puede ser el siguiente:
Glosario de conceptos
Concepto | Descripción | Observaciones |
Paciente | Es el usuario que accede al sistema y puede solicitar citas médicas. | |
Registro | Es la acción que realiza un usuario para tener acceso al sistema. | No se debe confundir como un conjunto de datos en el sistema. |
A continuación se copia el formato de la plantilla en Markdown:
## Glosario de conceptos
| Concepto | Descripción | Observaciones |
|------------- |-------------------|--------------------|
| << Nombre >> | << Descripción >> | << Observaciones >>|
| << Nombre >> | << Descripción >> | << Observaciones >>|
| << Nombre >> | << Descripción >> | << Observaciones >>|El ejemplo en Markdown se puede ver de la siguiente manera
## Glosario de conceptos
| Concepto | Descripción | Observaciones |
|----------|-------------------|--------------------|
| Paciente | Es el usuario que accede al sistema y puede solicitar citas médicas. | |
| Registro | Es la acción que realiza un usuario para tener acceso al sistema. | No se debe confundir como un conjunto de datos en el sistema. |