0. Introducción

El objetivo de la elaboración de la documentación técnica del proyecto es facilitar al resto de grupos a acceso a la información del mismo que va a ser utilizada por dichos grupos. En este espacio deberemos indicar las APIs que se ofertan, los componentes y cualquier información relevante que sea de utilidad para los grupos que quieran acceder a la información ofertada.

También es imprescindible definir claramente el modo de acceso (público y/o autenticado) y los mecanismos que se utilizarán para ello.

1. Componentes

Si durante el desarrollo del pórtico se han creado componentes reutilizables por el resto de los grupos el Responsable técnico asegurará que los Miembros del equipo de desarrollo dejan disponibles los componentes y documentarlos para su reutilización por el resto de los grupos. Para ello el Responsable técnico supervisará que se realizan las siguientes acciones por parte de los  Miembros del equipo de desarrollo.

• Configurar el componente para ser incluido en un proyecto, desacoplándolo de cualquier lógica no relacionada con él mismo.
• Registrar el componente para que sea descargado y reutilizado por el resto de los grupos usando: Maven, Verdaccio, etc.
• Añadir la documentación del componente al apartado Documentación técnica > Componentes. En caso de no tener en nuestro espacio dicha estructura podemos copiarla desde la plantilla de espacio de pórtico.
• Una vez añadido y documentado se deberá probar la inclusión en un proyecto siguiendo los pasos indicados, a ser posible por una persona que no conozca en profundidad el componente para poder validar la documentación.

2. APIs de servicios

Si en nuestro pórtico se generan proyectos que ofertan servicios a otros grupos vía REST, SOAP o RMI el el Responsable técnico asegurará que los Miembros del equipo de desarrollo documenten las diferentes APIs generadas de manera que cualquier grupo pueda utilizarlas sin dificultad. En el caso de que las API requieran autenticación gestionada por el proyecto, el Responsable técnico definirá el proyecto Jira al que los grupos clientes deberán registrar las solicitudes de alta de sus aplicaciones.

Para los diferentes tipos de API, los Miembros del equipo de desarrollo deberán documentar los métodos ofrecidos y la forma de acceso a los mismos en la sección Documentación técnica > APIs de servicios > REST | SOAP | RMI 

En el caso de que sea una API REST o SOAP se deberá generar previamente la pertinente documentación con Enunciate o similar para enlazarla a la correspondiente ficha y también cualquier archivo o componente que sirva a las aplicaciones clientes para acceder al servicio  (librerías, clientes ya generados, entidades, etc). Estos componentes deberán subirse a un entorno que permita añadirlos a su proyecto por parte de cualquier equipo de desarrollo.

A su vez los Miembros del equipo de desarrollo deberán asegurar que dicha información está actualizada, llevando un control de cambios y marcando los métodos que entren en desuso con la pertinente etiqueta. El Responsable técnico deberá comprobar el estado de dicha documentación antes de cada actualización del proyecto o proyectos incluidos en el pórtico. También deberá notificar a todos los grupos los cambios en cada versión de la API para planificar las actualizaciones que sean necesarias en las aplicaciones clientes.

3. HOW TO y FAQ

Los Miembros del equipo de desarrollo deberán rellenar las secciones Documentación técnica > HOW TO  y Documentación técnica > FAQ con la información que tengan a priori y la irán enriqueciendo conforme se usen las APIs de cara a tener la mayor información útil para los grupos de desarrollo.

Los grupos externos deberán registrar como comentarios en la sección FAQ las cuestiones que les hayan ocurrido y los Miembros del equipo de desarrollo trasladarán la pegunta/respuesta a la FAQ borrando el comentario que la originó para no meter ruido.

El Responsable técnico deberá ir revisando la información de ambas secciones para asegurar que no están desfasadas y que se están atendiendo a las preguntas que hacen otros grupos.