Durant els últims 15 anys he treballat en desenes de projectes de programari, i gairebé cada vegada la documentació era terrible. Els desenvolupadors subestimen la necessitat de documentació perquè creuen que ja ho entenen tot. Els gerents ho subestimen perquè suposen que els desenvolupadors poden simplement llegir el codi i entendre el projecte en unes hores. Fins i tot quan la gent no subestima la documentació, sovint li falta el temps i la capacitat per fer-ho.La visió general precisa i actualitzada sol estar en el cap dels desenvolupadors superiors, que ja porten moltes responsabilitats. Els desenvolupadors sovint afegeixen comentaris per a funcions trivials o descriuen paràmetres quan noms o tipus de variables més clars haguessin resolt el problema. Potser la documentació és obsoleta? Només , indicant que molts equips tracten la documentació com una "formalitat opcional" El 4% de les empreses sempre documenta els seus processos https://www.bptrends.com/bpt/wp-content/uploads/2015-BPT-Survey-Report.pdf/ Al mateix temps, tenim fortes proves que sense una bona documentació el negoci només perd una gran quantitat de temps i diners: “Documentació insuficient” citada pel 41% dels desenvolupadors com a principal causa de pèrdua de temps, amb el 69% dels desenvolupadors perdent més de 8 hores per setmana a aquestes ineficiències (suposant fins a ~ $ 18.5M en productivitat perduda anual per 1.000 desenvolupadors) https://newsletter.getdx.com/p/state-of-developer-experience-2024 La incorporació d'un nou enginyer triga de 3 a 9 mesos, molt depenent de la documentació https://stripe.com/files/reports/the-developer-coefficient.pdf La falta de documentació és un component important del deute tècnic (https://www.informit.com/store/economics-of-software-quality-9780132582209) Un experiment amb més de 30 programadors va mostrar que la falta de documentació va causar aproximadament un 21% més de temps dedicat a comprendre el codi durant les tasques de manteniment https://hci.com.au/get-documentation-budget/ Quina és la barrera real que hi ha darrere d’una manca tan generalitzada de documentació? En el brillant treball d'Andrew Forward "Documentació de programari - Construcció i manteniment d'artefactes de comunicació" han fet una bona investigació sobre les raons reals. External Factors Influencing Documentation Quality Com podeu veure, la manca de temps i pressupost es correlaciona amb la frustració que l’esforç de documentació pugui esdevenir inútil i ràpidament obsolet. Així que si reduïm l’esforç manual i resolem el problema de la documentació que s’està quedant obsoleta, podem fer un pas important cap endavant. La comunitat de desenvolupadors ja ha introduït enfocaments com Javadoc i eines similars que generen documentació automàticament a partir de signatures de codi. Per tant, encara necessitem documentació ben escrita, actualitzada i llegible per l’home. El veritable desafiament és que la documentació no és un lliurament d'una vegada, sinó un Fins i tot si un equip escriu bons documents al principi, el codi evoluciona més ràpid que els hàbits de documentació. Artífex viu Això vol dir que el botxí no és La documentació, però . Escriure Mantenir-la correcta Solucions que En realitat, l'IA és bo en combinar patrons simples entre el codi i els documents. Hi ha algunes bones solucions on es pot automatitzar la documentació a través de l'IA: Merge request rules, pointing agent to existing documentation and changed code base Claude Code documentation agent that keeps project docs up to date with Docusaurus. npx claude-code-templates@latest --agent=documentation/docusaurus-expert --yes Aquest mètode funciona bé per: Actualització de descripcions d'alt nivell Resum de la intenció de codi Reescriure frases obsoletes Recuperar el context narratiu perdut No obstant això, l'AI té limitacions clares: Té dificultats per detectar inconsistències estructurals (per exemple, entrades env indocumentades, ports, banderes CLI, banderes de característiques). Pot al·lucinar, especialment quan els documents són incomplets o ambigus. No produeix controls deterministes rastreables: cada execució pot generar un resultat lleugerament diferent. No es pot dir de manera fiable què és important i què és soroll sense coneixement del domini. En altres paraules, AI pot ajudar No obstant això, no és fiable com a . rewrite and improve text source of truth validator Comprovació estàtica Eines com Aborda aquest problema tractant la documentació com una cosa que ha de ser monitoritzada contínuament, igual que la qualitat del codi o la deriva de la infraestructura. treballa purament algorítmicament perquè no estigui afectat per al·lucinacions, tot i que, per descomptat, encara són possibles falsos positius. Ducà Ducku funciona mitjançant l'extracció de senyals estructurals del vostre repositori - variables ambientals, rutes d'API, punts d'entrada de serveis, importacions de mòduls, estructura de directori, claus de configuració - i comparant-los amb el que es refereix a les vostres READMEs i wiki. Capacitat actual Verificació de la presència d'entitats: Detecta quan les variables ambientals, les claus de configuració, les portes, les rutes de l'API o els noms de guió apareixen en la documentació, però no en el codi (i viceversa). Cobertura d'entitats paral·leles: identifica grups d'elements similars (serveis, treballs ETL, manipuladors de lambda, comandes CLI) i marca addicions no documentades. Anàlisi de mòduls morts: Detecta arxius que no s'importen / s'utilitzen en cap lloc, ja sigui punts d'entrada que mereixen una explicació o artefactes obsolets. Verificació d'integritat d'URL: Detecta enllaços trencats o obsolets a recursos interns o externs. Consistència en l'encanteri i l'estil: higiene bàsica que normalment s'ignora. Això ja és suficient per reduir una gran part de la deriva de documentació silenciosa en projectes reals. Conclusió La documentació no falla perquè els enginyers són descuidats. que el manté alineat amb el sistema que descriu. El codi té proves. La infraestructura té detecció de deriva. CI té portes de política. La documentació, en la majoria dels equips, no té res. no feedback loop L'IA pot millorar la expressió i restaurar el context, però no pot dir de manera fiable si la documentació és correcta. Els controls estàtics, d'altra banda, poden validar l'alineació factual, però no poden explicar la intenció o la lògica del domini. correct Ambdós junts poden portar el que necessiteu.
