Per què la teva empresa necessita documentació tècnica
Tota empresa que desenvolupa programari, APIs o productes digitals arriba al mateix punt: sense documentació, el coneixement viu al cap de les persones. I quan aquestes persones marxen de vacances, canvien de projecte o deixen l'empresa, el coneixement se'n va amb elles.
La documentació tècnica no és un luxe ni un "nice to have". És una peça crítica de la infraestructura de qualsevol negoci digital. Des de manuals interns fins a documentació d'APIs públiques, passant per bases de coneixement per a equips o guies d'usuari per a clients.
A AndorraDev muntem llocs de documentació per a empreses i startups com a part dels nostres serveis de disseny web. En aquest article compartim les eines i l'enfocament que fem servir en projectes reals.
Markdown: el format universal
Markdown és un llenguatge de marcatge lleuger que s'ha convertit en l'estàndard de facto per escriure documentació tècnica. La seva sintaxi és tan simple que qualsevol persona de l'equip pot contribuir sense coneixements d'HTML ni eines especials.
L'avantatge principal de Markdown és la seva portabilitat. Un fitxer .md és text pla que funciona a qualsevol editor, es versiona amb Git, es renderitza a GitHub, GitLab, Notion i desenes de plataformes, i es converteix a HTML, PDF o qualsevol format de sortida que necessitis.
Sintaxi que cobreix el 90% dels casos
Amb unes poques regles bàsiques ja pots documentar pràcticament qualsevol cosa. Encapçalaments amb #, negreta amb **text**, cursiva amb *text*, codi inline amb backticks, llistes amb -, enllaços amb [text](url), imatges amb , cites amb > i taules amb pipes |.
Un exemple senzill de documentació en Markdown:
# Guia d'instal·lació
Requisits previs per instal·lar la plataforma al teu servidor.
## Requisits del sistema
- **PHP** 8.2 o superior
- **MySQL** 8.0 o superior
- **Node.js** 18+ per compilar assets
- Mínim **2GB de RAM** al servidor
## Passos d'instal·lació
1. Clona el repositori: `git clone https://github.com/la-teva-org/el-teu-projecte.git`
2. Instal·la dependències: `composer install && npm install`
3. Configura el fitxer `.env` amb les teves credencials
4. Executa les migracions: `php artisan migrate`
> **Nota:** assegura't que l'usuari de MySQL té permisos CREATE i ALTER.
| Variable | Valor per defecte | Descripció |
|----------|-------------------|------------|
| DB_HOST | 127.0.0.1 | Host de la base de dades |
| DB_PORT | 3306 | Port de MySQL |
| DB_NAME | la_meva_app | Nom de la base de dades |
Markdown estès: taules, alertes i diagrames
L'especificació base de Markdown és deliberadament simple, però les extensions com GitHub Flavored Markdown (GFM) afegeixen funcionalitats crítiques per a documentació tècnica: taules, llistes de tasques, blocs d'alerta, ressaltat de sintaxi en blocs de codi i autolinks.
Eines com Docusaurus i Next.js van un pas més enllà amb MDX, que permet incrustar components React directament dins del Markdown. Això obre possibilitats com gràfics interactius, demos en viu o components d'UI personalitzats dins de la documentació.
Andie recomana
Si el teu equip no té experiència amb Markdown, la corba d'aprenentatge és de menys d'una hora. És molt més productiu que editar HTML a mà o barallar-se amb editors WYSIWYG que generen markup inconsistent. Aquí tens un tutorial complet per començar.
Docusaurus: documentació llesta per a producció
Docusaurus és el framework de documentació creat per Meta (Facebook). El fan servir projectes com React Native, Jest, Babel, Redux i centenars de projectes open source. El seu enfocament és clar: escrius Markdown, obtens un lloc de documentació professional.
Per què Docusaurus i no un lloc custom
Muntar un lloc de documentació des de zero amb Next.js o Laravel és possible, però Docusaurus et dóna gratis funcionalitats que d'altra manera tardaries setmanes a implementar:
- Versionat de docs: mantenir documentació per a v1, v2 i v3 simultàniament
- Cerca integrada: cerca full-text amb Algolia DocSearch o cerca local
- Sidebar automàtic: genera la navegació lateral a partir de l'estructura de carpetes
- Mode fosc: toggle automàtic sense configuració
- i18n natiu: suport per a múltiples idiomes amb fitxers de traducció
- Blog integrat: secció de blog amb feed RSS i paginació
- MDX: components React dins de Markdown per a documentació interactiva
Estructura d'un projecte Docusaurus
La configuració és mínima. Un fitxer docusaurus.config.js defineix el lloc, i el contingut viu en carpetes de Markdown. La carpeta docs/ conté els fitxers .md organitzats per seccions (api, avançat, guies), blog/ per a entrades del blog, src/pages/ per a pàgines custom en React, i a l'arrel els fitxers de configuració docusaurus.config.js i sidebars.js.
Tot el contingut és Markdown pur. Docusaurus genera automàticament la navegació lateral, la taula de continguts de cada pàgina, el versionat i la cerca sense que hagis d'escriure una línia de JavaScript.
Exemple real: documentar una API
Un fitxer Markdown a Docusaurus per documentar un endpoint inclou un front matter YAML amb sidebar_position, title i description. El cos del document usa encapçalaments per estructurar les seccions (autenticació, endpoints, errors), blocs de codi amb ressaltat de sintaxi per mostrar peticions cURL i respostes JSON, i blocs d'alerta amb la sintaxi :::tip i :::warning pròpia de Docusaurus.
El resultat és una pàgina amb navegació lateral, taula de continguts, ressaltat de sintaxi, blocs d'alerta i cerca, tot sense escriure una línia de CSS o JavaScript.
Quan usar Docusaurus
Docusaurus és la millor opció quan la documentació és el producte principal del lloc. Si necessites un portal de documentació dedicat amb versionat, cerca i navegació estructurada, no hi ha opció més ràpida ni més robusta.
Ideal per a:
- Documentació d'APIs públiques
- Guies d'integració per a partners
- Bases de coneixement internes
- Documentació de SDKs i llibreries
- Manuals d'usuari de productes SaaS
Next.js + MDX: documentació integrada al teu producte
Quan la documentació no és un lloc independent sinó que viu dins de la teva aplicació web, Next.js amb MDX és la combinació perfecta. Escrius en Markdown, incrustes components React quan necessites interactivitat, i tot es genera com a pàgines estàtiques amb rendiment òptim.
L'avantatge del contingut estàtic
Next.js genera pàgines estàtiques en temps de build (SSG). Això vol dir que la teva documentació es serveix com a HTML pur des d'un CDN: càrrega instantània, SEO perfecte i cost d'hosting quasi nul. Per a una empresa a Andorra que necessita documentar el seu producte per a clients a Europa, la velocitat de càrrega des de qualsevol punt del continent és crítica.
Estructura amb App Router
Amb l'App Router de Next.js, cada fitxer .mdx dins de la carpeta app/docs/ es converteix automàticament en una ruta. Organitzes les seccions en subcarpetes (getting-started, api-reference, guides) i cadascuna amb el seu page.mdx. Un fitxer layout.tsx a l'arrel de docs/ defineix el sidebar i la navegació compartida. L'estructura és neta, escalable i fàcil de mantenir per a qualsevol membre de l'equip.
Components interactius dins de Markdown
La màgia de MDX és que pots barrejar Markdown amb components React. Això permet crear documentació amb demos en viu, selectors de llenguatge de codi, formularis de prova d'API o qualsevol component interactiu que necessitis. Imagina un <CodeTabs> que mostra el mateix exemple en cURL, JavaScript i Python, o un <ApiPlayground> on el lector pot provar l'endpoint directament des de la documentació sense sortir de la pàgina.
Quan usar Next.js per a documentació
Next.js és la millor opció quan la documentació forma part del mateix projecte web (mateixa navegació, mateix domini, mateix disseny) o quan necessites control total sobre el disseny i l'experiència d'usuari.
Ideal per a:
- Documentació integrada en un producte web existent
- Landing pages amb secció de docs (mateix domini, mateix branding)
- Projectes que ja usen Next.js i volen afegir documentació sense una altra eina
- Llocs on el disseny de la documentació ha de seguir un design system propi
- Intranets i portals interns amb base de coneixement integrada
Andie recomana
Si ja tens un projecte Next.js, no muntis un Docusaurus a part: usa MDX dins del teu App Router. Un sol deploy, un sol domini, un sol lloc. Si la documentació és el producte principal (portal d'API, SDK docs), Docusaurus t'estalvia setmanes de feina.
Docusaurus vs Next.js: quin triar
La decisió depèn del context, no de quin és "millor":
| Criteri | Docusaurus | Next.js + MDX |
|---|---|---|
| Setup | 5 minuts, llest per a producció | Requereix configuració de MDX, layout, sidebar |
| Versionat | Integrat nativament | Manual (carpetes o branches) |
| Cerca | Algolia DocSearch o local | Implementació custom |
| Personalització | Limitada al sistema de temes | Control total, és el teu codi |
| Integració | Lloc independent | Dins de la teva app existent |
| Rendiment | Excel·lent (estàtic) | Excel·lent (SSG/ISR) |
| Multiidioma | i18n natiu | next-intl o similar |
| Corba d'aprenentatge | Baixa | Mitjana (si ja coneixes Next.js, baixa) |
Resum ràpid:
- Portal de documentació dedicat: Docusaurus
- Docs dins d'una web existent: Next.js + MDX
- Projecte nou sense preferències: Docusaurus (més ràpid d'arrencar)
- Necessites disseny totalment custom: Next.js + MDX
Bones pràctiques per a documentació tècnica
Independentment de l'eina que triïs, aquestes pràctiques marquen la diferència entre documentació que es fa servir i documentació que s'ignora:
Estructura clara i predictible
Organitza el contingut en nivells: guia ràpida per començar en 5 minuts, tutorials pas a pas per a casos d'ús concrets, referència d'API exhaustiva per a desenvolupadors, i guies avançades per a configuracions específiques. El lector ha de poder trobar el que busca en menys de 3 clics.
Exemples reals, no teòrics
Cada endpoint, cada funció, cada configuració ha de tenir un exemple que funcioni. No fragments de pseudocodi, sinó codi que el lector pugui copiar, enganxar i executar. Inclou la petició completa amb headers, body i la resposta esperada.
Actualització contínua
La documentació desactualitzada és pitjor que no tenir documentació: genera falsa confiança. Integra l'actualització de docs al flux de desenvolupament. Si un PR canvia l'API, el mateix PR ha d'actualitzar els docs. Amb Markdown al mateix repositori que el codi, això és trivial.
SEO per a documentació pública
Si la teva documentació és pública (docs d'API, guies d'integració), el SEO importa. Els desenvolupadors busquen a Google, no al teu sidebar. Assegura't que cada pàgina tingui un title descriptiu, una meta description útil i URLs netes. Docusaurus i Next.js ho faciliten amb els seus sistemes de metadata.
El nostre enfocament en projectes de documentació
A AndorraDev creem llocs de documentació com a part dels projectes de desenvolupament. No és un entregable separat ni un afterthought: la documentació es construeix en paral·lel amb el producte.
Per a startups i empreses a Andorra que necessiten documentar les seves APIs, productes SaaS, plataformes de reserves o eines internes, muntem el lloc de documentació amb Docusaurus o Next.js segons el cas, configurem el deploy automàtic i formem l'equip perquè pugui mantenir i ampliar la documentació de forma autònoma.
El resultat és un actiu digital que escala amb la teva empresa: quan incorpores nous desenvolupadors, partners o clients, la documentació és allà per rebre'ls sense que ningú hagi d'explicar les coses dues vegades.
Contacta'ns si necessites documentació tècnica professional per al teu producte o empresa.
