El teu projecte està desplegat, provat, mesurat i vigilat. I tanmateix hi ha un fet incòmode que convé dir sense embuts: ningú no ho sap, ningú no entén quines decisions hi ha al darrere, i tu encara no has practicat com explicar-ho. Una feina que no es pot ensenyar ni defensar val molt menys del que és — i no per injustícia, sinó perquè qui l'avalua té deu minuts i cap manera d'endevinar el que vas fer bé. Aquesta lliçó converteix el que has construït en alguna cosa que es pot ensenyar, defensar i millorar. Veuràs com escriure un README que faci que algú entengui el projecte en dos minuts, amb plantilla completa i comentada; com documentar les decisions d'arquitectura amb registres breus (ADR), i per què documentar el perquè val molt més que documentar el què; com preparar una demostració de cinc minuts amb el seu guió, el seu ordre narratiu, les seves dades preparades i el seu pla B; com parlar del projecte en una entrevista tècnica —inclosa la pregunta que et faran segur, «per què no vas fer servir React?»—, com reconèixer una limitació sense sonar insegur i com explicar un bug difícil; com autoavaluar-te amb una rúbrica completa per dimensions; com revisar-te el codi a tu mateix i buscar revisió externa sense enfonsar-te amb la crítica; com publicar el projecte amb un repositori endreçat, un historial net i una llicència; i com iterar després del lliurament, que és el que distingeix un exercici acabat d'un producte viu.

1. Per què presentar és part de la feina
2. El README que s'entén en dos minuts
3. La plantilla completa, comentada
4. Captures, GIF i demo
5. Documentar decisions: els ADR
6. La plantilla d'ADR i cinc exemples reals
7. Per què el perquè val més que el què
8. La demostració de cinc minuts
9. El guió i l'ordre de la narració
10. Dades d'exemple preparades i pla B
11. Parlar del projecte en una entrevista tècnica
12. «Per què no vas fer servir React?»
13. Reconèixer una limitació sense sonar insegur
14. Explicar un bug difícil
15. L'autoavaluació amb rúbrica per dimensions
16. La revisió de codi a un mateix
17. Buscar revisió externa i rebre crítica
18. Publicar: repositori, historial i llicència
19. El portafoli
20. Iterar després del lliurament
21. Errors Habituals i Consells
22. Exercicis
23. Conclusió

Hi ha una creença estesa i falsa: que la bona feina parla per si sola. No ho fa. El que passa a la realitat és això:

Cap dels quatre no llegirà 4.000 línies de codi per descobrir que la teva detecció de cicles a l'arbre cobreix els tres casos. Això s'ha d'explicar.

I hi ha un argument que va més enllà del portafoli: explicar és una habilitat professional de primer ordre. A la feina real passaràs una part considerable del temps justificant decisions, escrivint documentació, explicant a algú per què una cosa trigarà més del que sembla, i defensant un enfocament davant d'un altre. Qui construeix bé però no ho sap explicar té un sostre professional molt concret, i no és tècnic.

La bona notícia és que aquesta lliçó no demana inventar res: tot el que cal explicar ja ho has fet. Es tracta d'endreçar-ho.

El README.md és la portada del teu projecte. Es llegeix més que qualsevol altra cosa que hagis escrit, inclòs el codi.

La prova dels dos minuts: dona'l a algú que no sàpiga res del projecte i cronometra. Als dos minuts hauria de poder respondre:

1. Què és això i per a qui?
2. Funciona? El puc veure?
3. Què té d'interessant tècnicament?
4. Com l'executo?

Si no pot, el README falla — per molt ben escrit que estigui.

Els quatre errors que fan fallar la prova:

L'estructura que funciona, en ordre estricte d'interès decreixent:

Els tres blocs destacats són els que més pes tenen: la frase inicial decideix si continuen llegint, les decisions tècniques són el que diferencia el teu projecte d'uns altres deu iguals, i les limitacions són el que demostra maduresa.

git clone https://github.com/usuari/orbita.git cd orbita npm install npm run dev # http://localhost:5173

npm test # 251 proves unitàries i d'integració npm run test:cov # amb informe de cobertura npm run e2e # 3 recorreguts d'extrem a extrem (Cypress) npm run verificar # lint + format + proves + build

src/domini/ Entitats i regles R1-R15. Sense dependències. Es prova a Node. src/dades/ Persistència i xarxa. Un contracte, tres implementacions. src/vista/ DOM, esdeveniments i accessibilitat. No sap d'on vénen les dades. src/aplicacio/ Casos d'ús i estat. Uneix les tres anteriors.

Les insígnies del principi no són decoració: comuniquen d'una ullada que hi ha CI, que hi ha proves i que hi ha llicència. Són de les poques coses que un reclutador tècnic interpreta en dos segons.

La taula de rendiment amb la seva metodologia és un detall poc comú i molt valorat: demostra que vas mesurar amb mètode, no que vas executar Lighthouse una vegada amb sort.

La imatge és el que més es mira i el que menys cura acostuma a rebre.

Les set regles del GIF del README:

1. Mostra el flux principal complet, no un clic solt.
2. Dades realistes. Res de «tasca 1», «prova», «asdf». Fes servir les teves fictícies però versemblants.
3. Moviment del ratolí lent i deliberat. Els moviments ràpids maregen.
4. Sense barres d'eines ni pestanyes del navegador: només l'aplicació.
5. Menys de 3 MB, o GitHub trigarà a carregar-lo i molts hi veuran un buit.
6. Comença i acaba en un estat net, perquè el bucle no faci salts.
7. 10–15 segons. Més llarg, ningú no l'acaba.

La demo en viu necessita dades preparades. Una aplicació buida no demostra res, i demanar a qui la visita que creï sis tasques per entendre el producte és demanar-li massa. Dues opcions:

• Llavor automàtica la primera vegada, amb un botó «Començar de zero».
• Mode demostració per URL (?demo=1) que carrega un conjunt d'exemple.

I en qualsevol dels dos casos, un avís clar: «Dades d'exemple. Tot es desa només al teu navegador».

Un ADR (Architecture Decision Record, registre de decisió d'arquitectura) és un document curt que registra una decisió important, el seu context i les seves conseqüències. Neix d'una observació simple: el codi diu què es va fer, però mai per què, ni quines alternatives es van descartar, ni què caldria revisar si canviés el context.

Quan escriure'n un. No per a cada decisió: només per a les que compleixen alguna d'aquestes condicions:

Per a un projecte d'aquesta mida, entre 5 i 10 ADR és el nombre correcte. Menys de 3 suggereix que no hi va haver decisions —cosa improbable— i més de 20 suggereix que estàs documentant detalls d'implementació.

On viuen: a docs/adr/, numerats, al repositori, versionats amb el codi. Mai en un servei extern: es desincronitzen.

Les cinc seccions són obligatòries i no en sobra cap:

Els cinc ADR mínims d'aquest projecte:

I dos d'opcionals que queden molt bé si el teu projecte els té: actualització optimista amb reversió i historial immutable append-only amb anonimització en lloc d'esborrat.

Compara aquestes dues maneres de documentar exactament el mateix:

El primer comentari és soroll: diu el que ja es llegeix. El segon conté informació que no existeix en cap altre lloc i que evita que algú —tu— esborri aquella línia d'aquí a sis mesos pensant que sobra.

La regla general:

Aquesta última fila mereix èmfasi. Les alternatives descartades són la informació més valuosa i la que més ràpid es perd. Sense ella, qui arribi després proposarà exactament el que tu ja vas avaluar i rebutjar, gastarà una setmana descobrint-ho, i arribarà a la teva mateixa conclusió.

Hauràs d'ensenyar el teu projecte: en una entrevista, a un company, en una presentació. Cinc minuts és la durada típica, i cal preparar-los i assajar-los.

Per què cinc minuts són difícils. Perquè coneixes el projecte sencer i el vols explicar sencer. La disciplina de la demostració consisteix a triar què no explicar.

L'error més comú, amb nom: el recorregut guiat per la interfície. «Aquí hi ha el tauler, aquí el botó de filtre, si premo aquí surt això, i aquí tenim un altre botó…». És avorrit, no té tensió narrativa, i no diu res de tu. Ningú no recorda un recorregut per botons.

L'ordre que funciona té estructura d'història:

Un guió literal per a Òrbita, cronometrat. Adapta'l paraula per paraula al teu projecte:

Cinc regles d'execució de la demostració:

1. Assaja-la en veu alta almenys tres vegades, amb cronòmetre. Es triga entre un 30 % i un 50 % més del que un es pensa.
2. No llegeixis el guió. Aprèn-te l'estructura, improvisa les paraules.
3. No ensenyis codi tret que t'ho demanin, i si ho ofereixes tu, que sigui un fragment curt i preparat.
4. No demanis perdó per res. «Això està una mica lleig», «no vaig tenir temps de…» resta sense aportar. Les limitacions van al pas 5, dites amb seguretat.
5. Acaba amb el que ve, no amb «i ja està». Deixa la sensació de projecte viu.

Les dades són la meitat de la demostració. Amb «tasca 1», «tasca 2» i «prova asdf», el teu producte sembla un exercici. Amb dades versemblants, sembla un producte.

Què ha de contenir el teu conjunt de demostració, i per què cada element:

Totes les dades fictícies, sempre. No facis servir mai noms reals de companys, clients o coneguts en una demostració pública o en un repositori. És una qüestió de respecte i, si el projecte es publica, de protecció de dades. Taller Nómada i el seu equip són ficticis; els teus també ho han de ser.

El pla B, que cal tenir preparat abans i no improvisat:

Una precaució tècnica que ha salvat moltes demostracions: tingues un enregistrament de vídeo de 90 segons del flux principal. Si tot falla —xarxa, portàtil, projector—, continues tenint alguna cosa per ensenyar. Costa mitja hora enregistrar-lo i és una assegurança barata.

En una entrevista, el teu projecte és la millor eina que tens: és l'única cosa de la qual en saps més que qui t'entrevista.

El que s'avalua quan en parles no és el que la majoria es pensa:

L'estructura de resposta que funciona per a «parla'm d'un projecte teu», en uns 90 segons:

El pas 5 és el que converteix un monòleg en una conversa: dones a triar, i qui entrevista pregunta pel que li interessa. Això sempre va millor que continuar parlant.

Les preguntes que et faran, amb la clau de cadascuna:

I la resposta a «com escalaria?» mereix un apunt, perquè gairebé tothom la contesta malament improvisant optimitzacions. La resposta bona comença per mesurar:

«Primer mesuraria. La meva línia base està amb 500 tasques: render() en 44 ms i 1.380 nodes. Amb 10.000, el primer que es trencaria és el DOM, així que virtualitzaria la llista, que ja està preparada perquè el render i l'actualització estan separats. El segon seria localStorage, que a aquest volum es queda curt: passaria a IndexedDB, i això només toca un fitxer perquè el repositori és una frontera amb contracte provat. El tercer seria l'informe, que avui recalcula sencer; allà memoïtzaria el selector.»

Aquesta resposta demostra tres coses alhora: que mesures abans d'optimitzar, que coneixes els teus propis números, i que la teva arquitectura estava pensada per a això.

Te la faran. És la pregunta més probable de totes si el teu projecte és JavaScript pur, i no és un parany: volen veure si vas triar o si simplement no saps React.

Les tres pitjors respostes:

La resposta bona té tres parts: criteri, honestedat i coneixement de l'altre costat.

«Va ser una decisió, i en tinc els números. El producte és una única aplicació amb molta lògica de domini —quinze regles de negoci— i poca superfície d'interfície: set pantalles. L'equip soc jo. Amb aquest context, la infraestructura pròpia que necessito són unes dues-centes línies: un magatzem amb subscripcions, reconciliació per data-id i delegació d'esdeveniments. Això és menys que el cost d'aprendre i mantenir les convencions d'un framework per a aquest cas concret.

I la xifra que més em va convèncer: a la comparació que vaig fer, el fitxer de regles del domini era idèntic en JavaScript pur, React, Vue i Angular. L'única cosa que canviava era la vista. Com que el valor d'aquest projecte és al domini, el framework hi aportava poc.

Ara bé, sé perfectament quan canviaria d'opinió: amb tres o més persones a l'equip, o amb més de quinze o vint pantalles, aquelles dues-centes línies pròpies passen a ser un problema, perquè ningú més no les coneix i no hi ha documentació ni comunitat al darrere. Allà React o Vue compensen clarament. De fet vaig reescriure la pantalla principal en els quatre enfocaments per poder comparar: 210 línies i 18 kB en JavaScript pur, 130 línies i 63 kB en React.»

Per què aquesta resposta funciona:

1. Comença afirmant que va ser una decisió, no una limitació.
2. Dona el context concret que la justifica: producte, equip, superfície.
3. Aporta una dada, no una opinió.
4. Declara quan canviaria d'opinió, que és la marca del criteri davant del dogma.
5. Demostra que coneixes l'alternativa amb números propis.

I la variant honesta si no has fet aquesta comparació: no te la inventis. Digues el que sí que pots defensar: «Va ser una decisió pel context —un producte amb molta lògica de domini i una persona—, i conec React prou per saber que amb un equip de tres o amb quinze pantalles la balança s'invertiria. El que no et puc donar són números propis de la comparació; em vaig quedar en el raonament.» Això és infinitament millor que fingir.

El mateix esquema serveix per a qualsevol «per què no X?»: TypeScript, Tailwind, una base de dades concreta. Context → decisió → dada → quan canviaries.

Hi ha tres maneres de parlar d'un defecte del teu projecte, i només una funciona:

La fórmula de tres parts, que funciona sempre:

Tres exemples aplicats:

Limitació per decisió d'abast:

«No hi ha vista de calendari. La vaig descartar del MVP perquè la llista ordenada per data cobria la necessitat principal i el calendari eren dotze hores per a alguna cosa secundària. És al full de ruta com a v1.1, i el model ja ho admet: només falta la vista.»

Limitació tècnica reconeguda:

«Amb més de dues mil tasques el rendiment es degradaria: la meva línia base està mesurada amb cinc-centes. Ho sé perquè ho vaig mesurar, no perquè ho suposi. La solució seria virtualitzar la llista, i la vista ja separa render d'actualització precisament per poder fer-ho sense reescriure res.»

Alguna cosa que faries diferent:

«Vaig començar a escriure la vista abans de tenir el domini tancat i vaig perdre dos dies refent. Així que ho vaig reordenar —domini primer, després un tall vertical— el ritme va canviar completament. És el primer que faria diferent.»

Els tres exemples comparteixen el mateix: són concrets, tenen dada o raó, i acaben en una acció. Cap no demana perdó, i cap no amaga res.

Un matís sobre les limitacions del README, perquè acostuma a preocupar: declarar-les no fa el teu projecte pitjor als ulls de qui l'avalua. Fa el contrari. Un projecte sense limitacions declarades transmet una de dues coses: o no les has buscat, o les amagues. Totes dues són pitjors que tenir limitacions.

És una de les preguntes més freqüents en entrevistes tècniques, i la millor oportunitat que tens per demostrar com penses en lloc de què saps.

El format SAR —situació, acció, resultat— estructura la resposta:

L'error clàssic és dedicar el 80 % a la situació («era molt rar, no hi havia manera de…») i el 20 % a l'acció. Justament al revés: l'acció és el que avaluen.

Un exemple complet, amb l'errada de la condició de cursa de 11-04:

Situació. «Amb la xarxa lenta, de vegades —no sempre— en marcar una tasca com a feta, tornava a aparèixer com a pendent un segon després. A la meva màquina no passava mai, i no hi havia cap error a consola.»

Acció. «El primer va ser no tocar res fins a poder reproduir-ho a voluntat, perquè una errada intermitent no es pot depurar. Vaig estrangular la xarxa i sortia una de cada tres vegades, cosa que continuava sense ser prou, així que vaig embolcallar fetch per retardar tres segons només les peticions PUT. Amb això passava sempre.

Amb la seqüència al davant vaig veure que hi havia dues operacions asíncrones: el PUT optimista, que trigava tres segons, i un refresc de la llista que es llançava mig segon després i arribava abans. El refresc substituïa la llista sencera amb dades que el servidor havia generat abans del meu canvi.

Vaig escriure primer la prova que fallava, amb temporitzadors falsos per controlar l'ordre exacte, i només llavors vaig tocar el codi. Vaig avaluar tres solucions: bloquejar els refrescs mentre hi hagués enviaments en vol —fràgil—, versionar cada tasca i descartar l'antic —el més robust però depenia de l'API—, i fusionar respectant els identificadors pendents. Vaig triar la tercera.»

Resultat. «L'errada va desaparèixer i la prova es va quedar a la suite com a regressió. El que vaig aprendre i aplico des de llavors són dues coses: que una errada intermitent gairebé sempre és una cursa entre dues operacions asíncrones, i que qualsevol codi que substitueix un estat sencer és sospitós, perquè descarta informació que pot ser més recent. Vaig revisar la resta de l'aplicació buscant aquest patró i vaig trobar un altre lloc igual.»

Els sis elements que fan bona aquesta resposta:

1. Símptoma concret, amb el detall que era intermitent.
2. Reproduir primer, dit explícitament com a principi.
3. Una tècnica concreta: retardar només un tipus de petició.
4. La prova abans de la correcció.
5. Alternatives avaluades, amb el criteri d'elecció.
6. Un aprenentatge generalitzable, aplicat després. Aquest és el que més pes té.

Prepara dues històries abans de qualsevol entrevista: una d'una errada tècnica difícil i una altra d'una decisió de disseny complicada. Escriu-les, cronometra-les en dos minuts, i assaja-les en veu alta. No és fer trampa: és no dependre de la memòria sota pressió.

Abans d'ensenyar el projecte, avalua't tu. Amb honestedat, perquè l'objectiu no és la nota: és saber què diràs quan et preguntin pel pitjor.

Vuit dimensions, 0 a 4 punts cadascuna. Màxim 32.

La regla de l'equilibri, que importa més que el total: és millor un 3 a les vuit dimensions (24) que un 4 a quatre i un 0 a les altres quatre (16… o fins i tot 32 mal repartit). Un projecte brillant sense proves ni accessibilitat transmet un perfil desequilibrat; un projecte sòlid en tot transmet algú amb qui es pot treballar.

La pregunta obligatòria de l'autoavaluació, i la més útil de totes:

Quina és la teva dimensió més baixa, i què diries si te'n pregunten?

Prepara aquesta resposta amb la fórmula de l'apartat 13. Te la demanaran, i tenir-la llesta és la diferència entre semblar conscient i semblar enxampat.

Abans de publicar, revisa el teu propi codi com si fos d'una altra persona. És incòmode i hi troba coses.

El procediment que fa possible el canvi de perspectiva:

1. Deixa passar temps. Un dia com a mínim. El teu cervell omple buits al codi recent.
2. Llegeix el diff complet del projecte a la interfície web de GitHub, no al teu editor. El canvi de context visual funciona sorprenentment bé.
3. Ves fitxer per fitxer, de baix cap a dalt de l'arquitectura: domini, dades, aplicació, vista.
4. Anota, no arreglis. Primer la llista completa; després les correccions. Si arregles mentre llegeixes, perds el fil i la perspectiva.
5. Classifica el que has anotat en tres caixes: arreglar ara, arreglar després (al full de ruta), i acceptar (amb el seu perquè anotat).

La llista de comprovació completa:

Els punts 12 i 13 es comproven sempre abans de publicar un repositori, sense excepció.

La teva revisió té un límit infranquejable: no pots veure el que no saps que existeix. Per a això calen altres ulls.

On demanar-la, amb expectatives realistes:

Com demanar una revisió que serveixi. Les peticions vagues obtenen respostes vagues:

Afegeix-hi sempre: què és el projecte en una frase, què has intentat, i quina pregunta concreta tens. I enllaça un fitxer, no el repositori sencer.

Com rebre la crítica, que és la part difícil:

I la regla que més ajuda: una crítica al teu codi no és una crítica a tu. És difícil de sentir així al principi, i s'aprèn amb la pràctica. La drecera mental que funciona: la persona que assenyala una errada al teu codi t'està regalant informació que no tenies. És la reacció de gratitud, no la de defensa, la que fa que et tornin a revisar.

I no totes les crítiques s'accepten. «Hauries de fer servir React» sense conèixer el teu context no és una crítica accionable. Escolta, valora, i si no s'aplica, agraeix-ho i continua. Acceptar tot el que et diuen és tan dolent com no acceptar res.

Abans de fer públic el repositori, una revisió final:

El punt 1 té un matís que sorprèn molta gent: esborrar un secret en un commit posterior no l'elimina de l'historial. Continua allà, accessible amb git log -p. Si algun cop en vas confirmar un, l'única resposta correcta és rotar-lo (canviar la clau al servei); reescriure l'historial és opcional i no n'hi ha prou per si sol.

L'historial net. Un git log llegible és un senyal de professionalitat que qui revisa mira més del que et penses:

Si el teu historial és un desastre, tens tres opcions honestes: deixar-lo i aprendre per al següent (perfectament acceptable), netejar només el més recent, o començar un repositori nou amb un historial cuidat si ets al principi. El que no s'ha de fer és reescriure l'historial d'una branca compartida.

La llicència, amb el que cal saber:

Aquest últim punt sorprèn molta gent: un repositori públic sense llicència no és de domini públic. Per defecte, s'apliquen tots els drets d'autor, i ningú no el pot copiar, modificar ni fer servir legalment. Si vols que el teu projecte serveixi de portafoli i que algú s'hi pugui inspirar, afegeix-hi una llicència.

I dos avisos:

• Comprova les llicències de les teves dependències. La majoria són MIT o similars i no donen problema, però convé mirar-ho (npx license-checker --summary).
• Res d'això no és assessorament legal. Per a un projecte personal de portafoli, MIT és una elecció segura i habitual. Per a un producte comercial, consulta-ho.

El teu projecte ha d'aparèixer on la gent el busqui:

Al currículum, el format que funciona:

Què fa bo aquest bloc: hi ha números concrets (15 regles, 251 proves, 96 %), hi ha conceptes que demostren nivell (arquitectura per capes, pressupost a la CI, idempotència), i hi ha enllaços. No hi ha adjectius buits: ni «robust», ni «escalable», ni «modern».

Un projecte ben explicat val més que tres a mitges. Si en tens diversos, tria el millor, explica'l sencer, i esmenta els altres en una línia.

Aquí hi ha la diferència entre un exercici i un producte: l'exercici es lliura i s'acaba; el producte té una versió següent.

Com aconseguir comentaris reals, que és el més valuós i el que menys es fa:

La tècnica d'observar algú fent-lo servir mereix detall perquè és brutalment eficaç i gairebé ningú no l'aplica: li dones una tasca («crea una tasca amb dues subtasques i esbrina qui està més carregat aquesta setmana»), calles, i observes. La regla és no ajudar mai. Cada vegada que sentis l'impuls de dir «has de prémer allà», això és una errada de disseny que acabes de trobar. Amb tres persones descobreixes el 80 % dels problemes d'usabilitat.

Com prioritzar el que arriba. No tot es fa, i decidir és l'habilitat:

Amb un filtre previ de tres preguntes per a cada petició:

1. Quantes persones ho han demanat? Una petició apassionada d'una persona no és una tendència.
2. Encaixa amb la frase del producte (11-01)? Si no, probablement sigui un altre producte.
3. Què es trenca si ho faig? Tota funcionalitat nova afegeix superfície per mantenir.

Planificar la versió següent és repetir el cicle de 11-01 en petit: tria tres o quatre coses, escriu-les com a històries amb criteris, estima amb el teu factor de correcció ja calibrat pel projecte anterior —que ara és real i no una suposició—, i posa't una data.

I una nota sobre quan parar. No tots els projectes han de continuar eternament. Un projecte pot estar acabat en el sentit que compleix el que prometia. Si decideixes no continuar, digues-ho al README:

Això és molt més honest que un repositori amb l'última activitat fa dos anys i un full de ruta ple de caselles sense marcar.

Un README que comença per la instal·lació. A qui hi arriba no li interessa instal·lar res fins que sàpiga què és i per a què serveix. Nom, frase, imatge, demo, problema — i després la resta.

No posar cap imatge. És l'errada més cara del README, perquè el 90 % de la gent que l'obre mira si hi ha imatge abans de llegir ni una paraula. Un GIF de dotze segons val més que tres paràgrafs.

Llistar tecnologies en lloc de dir què fa el producte. «React, Redux, Tailwind, Vite» no diu si és un gestor de tasques o un joc. Les tecnologies van a la secció de decisions, amb el seu perquè.

Amagar les limitacions. Es descobreixen soles, i llavors sembla que les amagaves. Declarar-les és el que més credibilitat dona, i és el que gairebé ningú no fa.

Documentar el què en lloc del perquè. Un comentari que repeteix el que el codi diu és soroll que a més es desactualitza. El perquè, les alternatives descartades i el context són l'única cosa que el codi no et pot explicar.

Una demostració que és un recorregut per botons. Sense problema al principi, no hi ha tensió narrativa i ningú no recorda res. Problema, solució, un flux complet, un detall tècnic, limitacions.

Demostrar amb dades de prova. «Tasca 1», «asdf», «prova prova» fan que el teu producte sembli un exercici de classe. Prepara un conjunt versemblant i fictici.

No assajar la demostració. Es triga un 30–50 % més del que un es pensa, i sense assaig s'arriba al minut cinc per la meitat. Tres passades en veu alta amb cronòmetre.

Respondre «no sé React» a «per què no vas fer servir React?». Converteix una decisió en una limitació. Context, decisió, dada, i quan canviaries d'opinió.

Demanar perdó pel teu projecte. «Està una mica lleig», «no vaig tenir temps». Resta, no aporta, i convida a mirar justament on no vols. Les limitacions van emmarcades, no disculpades.

Publicar sense revisar l'historial. Un secret confirmat fa tres mesos continua accessible amb git log -p. Si va passar, la resposta és rotar la clau, no només esborrar-la.

Publicar sense llicència. Un repositori públic sense llicència no el pot fer servir legalment ningú. Si és portafoli, MIT i llestos.

Consell · Escriu el README com si fos per a algú amb pressa i sense context. Perquè ho és. Frases curtes, taules, llistes, i l'important a dalt.

Consell · Desa el GIF i les captures al repositori, a docs/imatges/. Els serveis externs d'imatges caduquen i deixen buits al teu README d'aquí a dos anys.

Consell · Escriu els ADR el mateix dia que prens la decisió. Reconstruir el raonament un mes després és impossible: recordaràs la conclusió, no les alternatives ni el perquè.

Consell · Assaja la demostració enregistrant-te. És incòmode veure's, i és la manera més ràpida de detectar crosses, presses i les parts on et perds.

Consell · Tingues preparades dues històries, un bug difícil i una decisió de disseny, escrites i cronometrades en dos minuts. Te les demanaran, i no voldràs improvisar-les.

Aquests exercicis tanquen la fita H6 del teu projecte: README, ADR, guió de demostració i autoavaluació emplenada.

Exercici 1 — El README i els ADR.

1. Escriu el README.md complet amb la plantilla de l'apartat 3, adaptada al teu projecte: identitat amb insígnies, imatge, demo, problema, funcionalitats, taula de decisions tècniques amb enllaços a ADR, execució, proves amb números reals, arquitectura, limitacions conegudes, taula de rendiment amb metodologia, full de ruta i llicència.
2. Enregistra un GIF de 10–15 segons del flux principal complint les set regles de l'apartat 4, desat al repositori, de menys de 3 MB.
3. Prepara les dades de demostració amb els set elements de la taula de l'apartat 10, totes fictícies, i afegeix el mode demo o la llavor automàtica.
4. Escriu almenys cinc ADR amb la plantilla completa de l'apartat 6, amb les seves cinc seccions —incloses les conseqüències negatives i el «quan revisar»— i amb almenys dues alternatives avaluades a cadascun.
5. Fes la prova dels dos minuts: dona el README a algú que no conegui el projecte, cronometra, i demana-li que respongui les quatre preguntes. Anota què no va saber contestar i corregeix el README.

Exercici 2 — La demostració i les respostes d'entrevista.

1. Escriu el guió de cinc minuts amb l'estructura de cinc passos, amb els temps anotats i el que diràs a cadascun.
2. Assaja'l tres vegades en veu alta amb cronòmetre i ajusta'l fins a cabre en cinc minuts amb marge.
3. Enregistra't fent-lo i revisa'l. Anota tres coses a millorar.
4. Prepara el pla B complet: la taula de sis situacions adaptada al teu context, més un enregistrament de 90 segons del flux principal com a últim recurs.
5. Escriu i assaja les respostes a aquestes sis preguntes, cadascuna en menys de dos minuts:
   • «Parla'm d'aquest projecte» (estructura de cinc passos de l'apartat 11).
   • «Per què no vas fer servir React?» (o el framework que correspongui), amb context, decisió, dada i quan canviaries d'opinió.
   • «Què és el pitjor del teu projecte?» (fórmula de tres parts de l'apartat 13).
   • «Explica'm un bug difícil» (format SAR, amb aprenentatge generalitzable).
   • «Com escalaria a 10.000 elements?» (començant per mesurar).
   • «Què faries diferent?» (concret i tècnic).

Exercici 3 — Autoavaluació, revisió i publicació.

1. Emplena la rúbrica de vuit dimensions de l'apartat 15, amb una justificació d'una frase per cada puntuació. Res de puntuar-te de memòria: obre el projecte i comprova-ho.
2. Identifica les teves dues dimensions més baixes i escriu un pla concret per pujar-les, amb l'esforç estimat.
3. Prepara la resposta a «quin és el teu punt més feble?» amb la fórmula de tres parts.
4. Fes la revisió de codi a tu mateix amb les 16 comprovacions de l'apartat 16, deixant passar almenys un dia. Documenta les troballes classificades en les tres caixes: arreglar ara, després, i acceptar amb el seu perquè.
5. Demana una revisió externa amb una pregunta concreta sobre una part concreta. Documenta què et van dir, què vas acceptar i què vas descartar amb la seva raó.
6. Fes que almenys una persona faci servir la teva aplicació mentre l'observes, sense ajudar. Anota cada moment de dubte: cadascun és una errada de disseny.
7. Executa les 10 comprovacions prèvies a la publicació de l'apartat 18, inclosa la de l'historial de Git. Afegeix-hi llicència, descripció, temes i enllaç a la demo.
8. Afegeix-lo al teu portafoli: repositori fixat, README del perfil, i el bloc de currículum amb números concrets.
9. Planifica la versió següent: tres o quatre millores prioritzades amb la matriu impacte/esforç, escrites com a històries amb criteris, i amb data.

Rúbrica de l'exercici 1 — README i ADR (24 punts)

Llindar: 17/24, amb obligatòriament ≥ 2 a «Prova dels dos minuts» i a «ADR: qualitat».

Criteris d'acceptació de l'exercici 1

Criteris d'acceptació de l'exercici 2 — Demostració

Rúbrica de l'exercici 3 — Revisió i publicació (21 punts)

Llindar: 14/21. Amb una condició que no es compensa: zero secrets i zero dades personals reals, ni al codi ni a l'historial ni a les captures.

L'autoavaluació final del projecte. Abans de donar la fita per tancada:

Has convertit un projecte que funcionava en un projecte que es pot ensenyar, defensar i millorar — i aquesta diferència val tant com el codi.

Saps per què presentar és part de la feina: perquè ningú no llegirà 4.000 línies per descobrir el que vas fer bé, perquè qui t'avalua té entre 90 segons i 15 minuts, i perquè explicar decisions és una habilitat professional de primer ordre amb la qual topa qualsevol que construeixi bé i no ho sàpiga explicar.

Tens un README que passa la prova dels dos minuts, amb l'ordre d'interès decreixent que funciona: identitat, imatge, demo, problema, funcionalitats, decisions tècniques —la secció que et diferencia d'uns altres deu projectes iguals— i limitacions conegudes, que és la secció que més credibilitat dona i que gairebé ningú no escriu. Amb insígnies que comuniquen en dos segons, amb la taula de rendiment acompanyada de la seva metodologia, i amb instruccions que funcionen copiades i enganxades. I amb un GIF que compleix les set regles, perquè la imatge és el primer que es mira i el que menys cura acostuma a rebre.

Tens ADR per a les cinc decisions que ho mereixen, amb les cinc seccions obligatòries —context, alternatives avaluades, decisió, conseqüències incloses les negatives, i quan revisar-la— i saps per què el perquè val més que el què: el codi diu què es va fer, els noms i les proves diuen com, però només un ADR diu per què no es va fer de l'altra manera. Aquesta és la informació més valuosa i la que més ràpid es perd, i sense ella qui arribi després gastarà una setmana a arribar a la teva mateixa conclusió.

Tens una demostració de cinc minuts amb estructura d'història en lloc de recorregut per botons: problema, solució, un flux complet, un detall tècnic explicat bé, i limitacions amb full de ruta. Amb les cinc regles d'execució —assajar tres vegades amb cronòmetre, no llegir, no ensenyar codi tret que t'ho demanin, no demanar perdó per res, i acabar amb el que ve—, amb dades fictícies i versemblants que contenen els set elements que fan que el producte s'expliqui sol, i amb un pla B per a sis situacions més un enregistrament de 90 segons que és l'assegurança més barata que existeix.

Saps parlar del projecte en una entrevista entenent què s'avalua de debò: no quantes tecnologies vas fer servir sinó per què; no si és gran sinó si està acabat; no si és perfecte sinó si en coneixes els defectes. Tens l'estructura de cinc passos que acaba en un ganxo —«si vols t'ensenyo…»— que converteix un monòleg en conversa. I tens preparada la pregunta que et faran segur, «per què no vas fer servir React?», amb les tres pitjors respostes identificades i una de bona construïda sobre context, decisió, una dada pròpia i —el que separa el criteri del dogma— quan canviaries d'opinió. Amb la variant honesta per quan no tens la dada, perquè inventar-la sempre surt pitjor.

Saps reconèixer una limitació sense sonar insegur amb la fórmula de tres parts —què falta, per què està així, què faries— que converteix un defecte en una demostració de criteri. I saps explicar un bug difícil amb el format SAR dedicant la meitat a l'acció i no a com de rar era, amb els sis elements que la fan bona i, sobretot, amb un aprenentatge generalitzable que vas aplicar després.

T'has autoavaluat amb una rúbrica de vuit dimensions i 32 punts, sabent que l'equilibri importa més que el total —un 3 a les vuit val més que un 4 a quatre i un 0 a la resta— i amb la pregunta obligatòria contestada: quina és la teva dimensió més baixa i què diràs quan te'n preguntin.

Saps revisar-te el codi a tu mateix amb distància, a la interfície web, de baix cap a dalt de l'arquitectura, anotant abans d'arreglar i classificant en tres caixes. I saps buscar revisió externa amb peticions concretes en lloc de vagues, i rebre la crítica amb la regla que ho canvia tot: qui assenyala una errada al teu codi t'està regalant informació que no tenies. Amb el matís que no totes les crítiques s'accepten, i que acceptar-ho tot és tan dolent com no acceptar res.

Saps publicar amb les deu comprovacions prèvies, inclosa la que sorprèn —que esborrar un secret no el treu de l'historial, i que l'única resposta correcta és rotar la clau—, amb un historial llegible, i amb llicència, perquè un repositori públic sense llicència no el pot fer servir ningú legalment. I el saps posar al portafoli amb números concrets i sense adjectius buits.

I saps iterar després del lliurament, que és la diferència entre un exercici i un producte: observar algú fent-lo servir sense ajudar mai —cada impuls d'ajudar és una errada de disseny trobada—, prioritzar amb la matriu d'impacte i esforç i les tres preguntes de filtre, i planificar la versió següent repetint el cicle de 11-01 amb un factor d'estimació que ja no és una suposició sinó una dada del teu propi projecte. O declarar honestament que està acabat, que també és una resposta vàlida i molt millor que un full de ruta abandonat.

La fita H6 està tancada, i amb ella el projecte: planificat, construït, persistit, provat, desplegat, documentat i defensable. Queda una sola lliçó, i no és de projecte: és el balanç de tot el que saps ara, el mapa del que ve després —TypeScript, Node.js, un framework en profunditat, la plataforma web, la carrera— i com se segueix aprenent quan ja no hi ha un curs que et digui què toca. És Següents Passos: TypeScript, Node.js i la teva Carrera.