Comentarios para mejorar los trabajos 16-17

Sobre la memoria

Para los grupos que hayan presentado el trabajo en formato documento aunque hay cosas que también pueden ser útiles para otros formatos.

• En la portada poner nombres y apellidos de cada componente, grupo al que pertenecen (1 o 2, mañana o tarde), curso académico, nombre del proyecto (deliberaciones, almacenamiento,...) e ID de Opera.
• Siempre enumerar las secciones y subsecciones
• Todos los grupos deberían tener una nomenclatura de nombre del proyecto para poder versionarlo. Ejemplo: deliberaciones-g1-1516-v2.01 (no necesariamente este, discutir posibilidades). Debería estar explicado en el documento en la parte de entrega cómo podría encontrar de manera sencilla un grupo del próximo curso la versión entregada y estable del código. Pensar en usar, por ejemplo, los tags en GIT.
• Poner una página al inicio con control de versiones del documento
• Poner una página al inicio con los enlaces importantes que correspondan, por ejemplo, repositorio/s de código del equipo, repositorio compartido, repositorio de incidencias, wiki, despliegue, etcétera.
• Hacer un índice de figuras
• Todas las figuras deben tener una leyenda y deben ser referenciadas y explicadas en el cuerpo del texto del documento.
• Cuando describa los cambios que ha hecho en el sistema sería bueno resumir dichos cambios de manera general: refactorización, añadir funcionalidades o lo que proceda pero a un alto nivel y luego, si procede, poner una lista con cambios más de bajo nivel que hayan implicados eso cambios de bajo nivel.
• En muchos casos, los documentos repiten la misma información en varios sitios. En un informe técnico se debe intentar contar las cosas en un solo sitio salvo el resumen, introducción y conclusiones en donde es frecuente repetir información y, en caso de tener que repetir algo para aclarar la lectura del texto se debe poner una referencia al sitio principal donde se dan detalles del asunto en cuestión. Ejemplo: Como se explica en la Sección X.Y, el entorno de desarrollo que se usa en el proyecto es ZZZZ.
• Debe quedar clara, en cada bloque, la diferencia entre:
  • el proceso abstracto de gestión definido
  • la herramienta que da soporte e implementa dicho proceso y cómo se usa dicha herramienta
  • la posible descripción de la instalación de dicha herramienta si es que fuera relevante y necesario. En muchos casos podría ser más práctico poner un vídeo y poner un enlace al mismo describiendo estos pasos.
  • el ejercicio que se proponga que tiene que tener una parte de enunciado y otra parte de solución bien diferenciados. La solución debe ser completa, paso a paso y autocontenida.
  • Lecciones aprendidas si las hubiera. En este apartado se pueden poner reflexiones y lecciones aprendidas. Se hizo algo de una forma y se ha visto que, tal vez, hubiera sido mejor hacerlo de otro modo.

En el proceso abstracto se define la norma de uso del proceso sin especificar nada concreto con respecto a una herramienta determinada (e.g. GIT). En la parte de cómo dar soporte a ese proceso con una herramienta determinada se especifican detalles de cómo dar soporte al proceso abstracto con la herramienta. Por último, en los ejercicios se debe poner por una parte un enunciado claro del ejercicio y por otra parte la solución a dicho ejercicio. El ejercicio tiene que ser algo concreto y personalizado para el proyecto en cuestión. No valen ejercicios genéricos que valdrían para cualquier proyecto. Hay una confusión generalizada entre usar una herramienta (por ejemplo jenkins o maven) y afirmar que se está siguiendo una aproximación determinada (por ejemplo de construcción automática o integración continua). Las herramientas son medios que dan soporte a un proceso, no son el proceso.

• Añadir un apartado sobre las mejoras que se proponen para el futuro (curso siguiente) y que no han sido desarrolladas en el sistema actual.
• Proponer mecanismos automáticos para actualizar el código en el repositorio central. Ejemplo: una tarea jenkins cuando se haga un tag en el repositorio de un equipo.
• Pensar en todo momento que el documento debería ser comprensible por otros compañeros vuestros que no hayan hecho el trabajo. En casi todos los casos esto no es así y el documento da por asumidos muchos conocimientos y aún así no pone referencias a dónde buscar más información.
• En la introducción no se debería describir directamente la funcionalidad del subsistema. Para ello sería mejor tener un apartado propio en el que se defina la funcionalidad del sistema y las interacciones con otros subsistemas.
• El apartado "resumen" en un documento técnico no suele tener número de sección y suele estar alineado en el centro
• La gestión de incidencias debería contener explícitamente dos apartados. Uno de cómo se han gestionado la incidencias internas y otro el cómo se han gestionado y se ofrece protocolo para gestionar las incidencias externas tanto las recibidas como las que se reporten a otros subsistemas.
• Cuando una incidencia esté relacionada con un commit, señalar el commit dentro de la propia incidencia
• En general no se han descrito pautas básicas de entrega del proyecto. En pocos casos se ha establecido una nomenclatura para los nombres del entregable del proyecto ni se han usado mecanismos como los "tags" para señalar entregables. Esto debería ponerse en la memoria y usarse en la práctica.
• Los despliegues, en algunos casos, son manuales. Debe intentarse un nivel de automatización de los despliegues mayor.
• En cuánto a los detalles de descripción del sistema se echa en falta que no haya en todas las memorias (o al menos en las directamente implicadas por esa decisión) una decisión del modelo de voto usado e información del formato utilizado en el voto.

Sobre el diario

• En el diario sería mucho mejor, además de decir cuándo se han tomado las decisiones, añadir qué tiempos y tareas se decidieron y qué imputación en horas real se ha hecho. También, en caso se haber diferencias significativas, se debe hacer un agregado por miembros del grupo y el total de horas imputadas. De no haber diferencias explícitas se considerará que todos los miembros del proyecto han aportado por igual a menos que se detecte, por ejemplo, baja actividad en el repositorio de código, de incidencias u otro elemento del proyecto. Si se quieren hacer diferencias, sería conveniente hacer algo parecido a lo hecho por otros grupos, en el que se desglosa de mutuo acuerdo el grado de implicación en el proyectoen una escala de 1 a 5. Si esto no está puesto explícitamente, se considerará que todos han trabajado de manera similar.
• Si es posible incluir una foto de cada miembro del grupo al lado de su nombre. También tener dicha foto actualizada en Opera.