1. Documentació d'aplicacions web

1. Introducció

En entorns professionals de desenvolupament i desplegament web, la documentació és un actiu tècnic essencial. No és un annex decoratiu del projecte, sinó un element estructural que:

• Permet mantenir i evolucionar l’aplicació.
• Facilita la integració de nous membres a l’equip.
• Garanteix la traçabilitat dels canvis.
• Dona suport als processos d’auditoria i qualitat.

En el mòdul de Desplegament d’Aplicacions Web, la documentació es considera part del procés de producció i s’ha d’integrar dins del cicle de vida del projecte.

2. Eines de generació de documentació

2.1. Generadors automàtics de documentació

Són eines que generen documentació a partir de comentaris estructurats dins del codi.

Algunes exemples habituals en entorns web:

• phpDocumentor (PHP)
• Sphinx (Python)
• Doxygen (multi-llenguatge)
• Javadoc (Java)

El funcionament habitual d'estes ferramentes és el següent:

1. El desenvolupador escriu comentaris estructurats.
2. L'eina analitza el codi font.
3. Es genera documentació en HTML, PDF o altres formats.

Els seus avantatges són:

• Automatització.
• Consistència.
• Reducció d’errors humans.

2.2. Documentació com a codi (Docs as Code)

Es tracta d'un model modern on:

• La documentació es genera amb les mateixes ferramentes en que es genera el codi.
• La documentació es guarda en el mateix repositori Git.
• Es versiona junt amb el codi.
• Es publica automàticament via integració contínua.

Els formats habituals són:

• Markdown (.md)
• ReStructuredText
• HTML generat

Este model és el recomanat per a projectes professionals.

3. Documentació de components software

3.1. Què s’ha de documentar en una aplicació web?

Arquitectura

• Model utilitzat (MVC, microserveis, etc.)
• Diagrama de components
• Dependències externes

Backend

• Endpoints de l’API
• Paràmetres d’entrada
• Respostes
• Codis d’error
• Sistemes d’autenticació

Base de dades

• Model entitat-relació
• Scripts de creació
• Migracions
• Restriccions i claus

Configuració de desplegament

• Variables d’entorn
• Ports utilitzats
• Fitxers de configuració
• Dependències

3.2. Exemple d’estructura mínima de documentació tècnica

/docs
 ├── README.md
 ├── arquitectura.md
 ├── instal·lacio.md
 ├── configuracio.md
 ├── api.md
 ├── base_dades.md
 └── desplegament.md

Cada document ha de ser:

• Clar
• Estructurat
• Navegable
• Actualitzat

4. Formats de documentació

4.1. Formats habituals en entorns d'aplicacions web

4.2. Criteris de selecció del format

• Públic destinatari (equip tècnic vs client)
• Necessitat d’actualització freqüent
• Integració amb control de versions
• Automatització

En projectes d'aplicacions web, el format Markdown versionat en Git és el més adequat.

5. Eines col·laboratives

La documentació ha de permetre treball en equip.

5.1. Requisits d’una eina col·laborativa

• Control de versions
• Historial de canvis
• Gestió de permisos
• Revisió de canvis (pull requests)
• Integració amb repositori

5.2. Flux de treball recomanat

1. Crear carpeta /docs al repositori.
2. Assignar responsabilitats per secció.
3. Treballar amb branques (branching).
4. Revisió mitjançant Pull Request.
5. Validació final abans de fusionar a main.

6. Plantilles de documentació tècnica

6.1. Plantilla de document README.md

# Nom del projecte

## Descripció
Breve descripció funcional.

## Requisits
- Node.js 18
- PHP 8.2
- MySQL 8

## Instal·lació
Passos detallats.

## Execució
Com iniciar l’aplicació.

## Autors
Equip de desenvolupament.

7. Bones pràctiques professionals

• No documentar al final → documentar durant el desenvolupament.
• Evitar duplicació d’informació.
• Escriure pensant en tercers.
• Utilitzar llenguatge tècnic precís.
• Revisió periòdica de coherència.