# Agile Speccing: Het schrijven van eigenschappen die echt werken # Inleiding Gedurende de jaren heb ik ' honderden kenmerkenspecificaties geschreven, sommige waren briljant, de meeste verschrikkelijk, . Het verschil tussen een goede en een slechte spec is niet over lengte of formaaliteit, maar over het feit dat het ontwikkelaars helpt om het juiste ding te bouwen zonder ze in het proces te verwarren. Hier is iets wat ik bij Microsoft geleerd heb dat mijn mening veranderde over specs. **Een gespesif is geen bijbel.** Zoals elke tool, gebruik je het om een werk gedaan te krijgen.1 Je voegt zoveel detail toe als jij.2 De belanghebbenden en ontwikkelaars moeten verdergaan.4 Dan pas je het aan.5 Verander het.6 Dateer het op terwijl de functie zich ontwikkelt.7 Beschouw een sleutel als een heilige document en je bouwt het verkeerde ding perfect op. (', het loopt heel erg snel in de verkeerde richting.')., Beschouw het als een levend gereedschap en je build iets dat echt problemen oplost. Deze agile aanpak van specs creëert een specifiek probleem: als de eigenschap kan evolueren terwijl je leert, hoe de hel je het schatt ? Hoe weet je wanneer je klaar bent? In het algemeen is een principe waar ik mee heb geleefd in mijn carrière; Alle processen, of het nu specs zijn / het invulen van rapporten / zelfs codebeoordelen etc. **In principe is een eigenschapsspeciek een gespreksmiddel om het eigenschap beter te maken NICHT een dogmatisch.** [TOC] ## Waarom Agile ( en wat dat eigenlijk betekent Agile is: ‘’’, ‘-’ en ‘sticky notes’. **Economische strategie om het juiste ding te bouwen onder onzekerheid.**. Species leven in die onzekerheid , Dus ze moeten ook agil zijn. [Agile Manifesto](https://agilemanifesto.org/), laat het worden hoe je denkt over het bouwen van EVERYTHING . Denk ernaar als een ontwerppatroon voor de ontwikkeling van een product. ### Eerste principes * **Verandering is de verstek, niet de uitzondering.** De markten bewegen, gebruikers verbazen je, afhankelijkheden glijpen, ., een spec dat niet flexibel kan zijn, wordt fictie. * **Leren beatt voorspellen.** Je ontdekt de echte behoeften pas nadat mensen het ding aanraken. Agile maakt leren *goedkoop en snel.*. * **Flow over heroïek.** Kleine, continue bewegingen verslaan grote, onvoldoende M SK2 grote klapMSC3 dabbels . ### De economie (Waarom bespaart dit je geld? * **Minimeer de kosten van fouten maken.** Korte cyclus + lichtgewichtsspecifieken betekenen dat slechte ideeën snel sterven in plaats van na een zes-weekse bouw * **Vertraagbare beslissingen.** Hou de opties open tot het laatste verantwoordelijke moment; stuur als de informatie het hoogst is en het risico het laagst is * **Inventaris verminderen.** De helft van de -geschreven epieken en massale “toekomsten”onderdelen zijn werkM SK3in,-progressieve schulden. schip dunne snijdenMNK6 bank de waardeMRK7 ### Feedback-loops zijn het product. Elke loop verkort de afstand tussen “idee” en “bruikbaarM SK3. * **Spec ⇄ Dev:** Onmogelijkheden te vangen voordat code ze cementeert. * **Dev ⇄ QA:** De acceptatiekriterien omzetten in uitvoerbare controles. * **Intern hondenvoedsel ⇄ Gebruikers:** Bewijzen dat het een echt probleem oplost. > Dateer de spec op na elke loop. De verandering log is de *Het verhaal van wat je geleerd hebt.*. # Wat maakt een goede eigenschapsspeciek ## Het probleem-Solution Pattern Het belangrijkste principe voor het schrijven van specs: **Begin altijd met het probleem, niet de oplossing.** Dit patroon is eenvoudig: 1. **Probleem** - Wat is het? 2. **Oplossing** Hier is hoe we het willen herstellen. 3. **In scope** - Wat doen we in deze spec? 4. **Uit de scope** - Wat wij, ', expliciet niet doen, , even belangrijk,;, leidt tot toekomstige planning en stopt de vraag "Waarom doen we het niet?" I' heb ontelbare specs gezien die recht in "User klikt op de X-knop, die API Y roept, zonder ooit te verklaren wat de gebruiker eigenlijk probeert te bereiken. Vergeet niet dat ontwikkelaars eigenschappen bouwen machines echt (code is het gereedschap om eigenschappen te leveren); zeg hen wat *Er is veel aan te doen.* Niet hoe het te doen. als je een UX persoon hebt die voor de UX-specific verantwoordelijk is, dan moet de dev en zij samenwerken. Het punt is om de beste eigenschap te maken. *voor de gebruiker.* Dat kan veranderen en iedereen heeft de macht om de verandering te dwingen (in het spec ) en dat hersieningsproces te laten testen op het idee. ```mermaid flowchart TD A[Feature Idea] --> B[Spec / Proposal] B --> C[Visuals: Flowcharts, Figma, UI Mockups] C --> D[Implementation] D --> E[Internal Testing] E --> F[Feedback Loop] F -->|Refine| B F -->|Ship| G[Release to Users] G --> H[User Feedback] H -->|Iterate| B ``` ## helderheid van doel Voor je een woord over de implementatie schrijft, moet je één vraag beantwoorden **Waarom?** Waarom bouwen we dit? Een goede spec begint met: 1. **De probleemstelling** - Wat 2. **De invloed van de gebruiker** - Wie geeft er om en waarom? 3. **Succeskritieken** - Hoe weten we dat we het hebben opgelost? 4. **Geen-Goelen** - Wat doen we expliciet niet? ## De juiste niveau van detail Dit is waar de meeste specs naartoe gaan. De truc is om te bepalen hoe het werkt. **Wat?** Het moet zonder voorschrift gebeuren. **Hoe?** Het gebeurt. **Goed.**Als een gebruiker probeert een formulier te versturen met ongeldige gegevens, moet hij onmiddellijk feedback krijgen om aan te geven welke velden een correctie nodig hebben. **Slechts.**: "Op vormsubmissie, moet de submit-knopM SK3s opClick-handhakker validateForm callenMSC4 die door het formaat herhaaltFields array elke veld controleertMST5waarde tegen zijn validatieMst6regex-eigenschap en als er een fout is, moet showError callnM ST7 met het veldM st8naam en validatie~M st9~message parameters~M ST10~ De eerste vertelt me wat de gebruikerservaring zou moeten zijn; Ik kan het implementeren in React, VueM SK2 vanilla JavaScript , of carrier pigeon voor alles wat er aan toe doetMSC4 De tweede veronderstelt implementatiedetails die helemaal verkeerd kunnen zijn voor de technische stapel of onnecessaire beperkingen introduceren. ## Gebruik foto's / stromingendiagrammen; Het punt overstijgen Denk aan jou, ', je probeert mensen te laten begrijpen wat jij suggereert.', je suggereert ., sommige teams hebben Figma-documenten, (, een verhaalbord, ux, ', specificaties of beelden van de UI die de ontwerper heeft gebouwd, ., zoals alles anders, maar dit zijn: ', tot we het proberen, M SK9, suggesties tot ze ', een feedback loop doorlopen, MSC11, Het is allemaal over *We zorgen dat je, ', begrepen wordt.*. Gebruik alle gereedschappen die je nodig hebt [In een Wiki-zeemeermin zijn diagrammen GREAT voor dit. ](https://www.mostlylucid.net/blog/category/Mermaid); onthoud AI is GREAT in het genereren van deze ook met een textuele beschrijving Sommige mensen kunnen geschreven beschrijvingen analyseren, sommigen hebben foto's en films nodig ```mermaid flowchart LR A[User on Profile Page] --> B[Click 'Add Profile Picture'] B --> C[Upload Dialog Opens] C --> D[Select Image File] D --> E[Preview + Crop Options] E --> F{User Confirms?} F -->|Yes| G[Profile Updated with New Picture] F -->|No| C G --> H[User Sees Updated Profile] ``` ## Randgevallen en foutenbehandeling Als er één ding is, heb ik het geleerd. **Gebruikers zullen manieren vinden om je shit te breken die je nooit had gedacht.** Een goede spec beschrijft niet alleen de gelukkige weg, maar ook ;. - Wat gebeurt er als het netwerk in het midden mislukt? - Wat als de gebruiker geen toestemming heeft? - Hoe zit het met concurrente veranderingen? - Hoe omgaan met gedeeltelijke falen in verspreide operaties? Je hoeft dit allemaal niet in de spec op te lossen, maar je moet erkennen dat het bestaat. Voor velen is het ' Waarschijnlijk niet bruikbaar voor deze specificatie . Je hebt misschien 'technische specificaties' die de details van de implementatie en de technische oplossingen van M'technicieke kwesties detailliëren. ## Bedenkingen over veiligheid en prestaties Deze zouden niet moeten worden nagedacht tijdens de code-overprüfung. Als er specifieke beveiligingsbehoeften zijn (beanthenticatieniveausM SK3data-encryptie ,audit-loggingMSC5 ze uitschrijven in het specMske6 Als er performance beperkingen zijn die belangrijk zijn, moet deze zoekopdracht onder 200ms voltooid worden voor datasets van tot aan 1 miljoenen opnames. # De structuur van een goede soort Hier is het werkvoorbeeld dat ik gebruik om de eigenschappen te bepalen. ## 1. Overview Een paar regels om samen te vatten wat we bouwen en waarom het belangrijk is. ## 2. Agtergrond/Context Wat is de huidige stand van zaken?What prompted this feature?What have users been asking for?What would help us make more money?This helps developers understand the problem space without having been in every product meeting. Got it—let’s vergroot je sectie op **Gebruikerverhalen** Met personages gevouwen in,, zodat het niet alleen een checklist is maar ook een levende kaart van hoe verschillende soorten gebruikers met het systeem communiceren. --- ## 3. Gebruikersverhalen (met personages) Gebruikersverhalen zijn niet alleen een doos, maar ook een oefening. **Echte mensen belichamen.** en hun doelen. Jullie kennen, jullie gebruikers **Het hele punt van dit sjaap bouwen.**. Door elk verhaal aan een persoon vast te leggen, dwing je jezelf om na te denken over echte gebruikspatronen, motivaties en beperkingen. Uiteindelijk zijn mensen een leuke manier om te bepalen hoe je software kan dienen aan verschillende typen van gebruikers. Misschien heeft Alex een dashboard nodig om de veiligheidsproblemen in jouw functie te bekijken, misschien heeft Morgan zijn vergunningen beperkt om hem niet meer te laten breken. **Als een [persoon / gebruikertype] Ik wil [om iets te doen. [Ik bereik een bepaald doel].** De gemeenschappelijke wetgeving van het land. **“zodat”** De clause is de beveiliging tegen bouwfuncties die niemand nodig heeft. --- ### Voorbeeld Personas - **Alex de Administrateur** – geeft om de controle, oversightM SK2 en efficiëntie . - **Jamie de gewone gebruiker** – waarden eenvoud en snelle wins. - **Priya de machtig gebruiker** – duwt het systeem tot zijn limieten, wil geavanceerde aanpassingM SK2 - **Morgan de Newcomer** – behoefte aan begeleiding, aan boordlanding , en veiligheidsmaatregelen - **Taylor de Stakeholder** – maakt geen gebruik van het systeem elke dag, maar heeft zichtbaarheid nodig in de resultaten. --- ### Voorbeeld gebruikersverhalen | Persoon | Geschiedenis | Waarom het belangrijk is M| |---------|-------|----------------| | Alex **Administrateur**, Ik wil rollen en toestemming geven. **Zodat** Ik kan de data-veiligheid en -compliëntie verzekeren. | Behoedt onautoriseerde toegang tot het systeem en houdt het betrouwbaar. | Jamie ( Gewone gebruiker **Gewone gebruiker**, Ik wil een eenvoudig dashboard. **Zodat** Ik kan snel de belangrijkste informatie zien zonder overweldigd te worden.. | Verlaagt frictie en verhoogt adoptie. | Priya (Gebruiker van elektriciteit) | Als een **Kraggebruiker**, Ik wil custom workflows maken. **Zodat** Ik kan repetitieve taken automatiseren en tijd sparen. | Morgan **Nieuwkomer**, Ik wil begeleide tutorialen en gereedschaptips. **Zodat** Ik kan het systeem leren zonder te voelen dat ik verloren ben. | verbetert aan- en opbehoeftingsvermogen | Taylor **Stakeholders**, Ik wil regulare rapportjes per e-mail. **Zodat** Ik kan de vooruitgang volgen zonder in te loggen. --- ### Waarom Personas + verhalen samenwerken - **Persona's humaniseren het abstracte.** In plaats van “, "gebruikers" en ,”, denk je aan Alex, ,, Jamie and Taylor. - **Verhalen verbinden functies met doelen.** De “ zodat de clause ” helderheid dwingt : elke eigenschap een doel moet dienen. - **Patronen ontstaan.** Als je meerdere verhalen samenvoegt, zie je overlappingen, conflicten en prioriteiten tussen personen. ## 4. Gedetailleerde vereisten Dit is je vlees en aardappelen. Breek het op volgens functionaliteitsgebieden . Gebruik subheadings vrijelijk. Sluit er kopieën of draadframes in als je ze hebtM SK3 een foto is duizend woorden waard om te beschrijven Voor elke vereiste , spesifiseer : - Het verwachte gedrag - Beperkingen of Validatieregels - Foutbehoeften in het handhaken - Hoe het omgaat met bestaande kenmerken ## 5. Niet-Functionele vereisten Performance-doelen, veiligheidsbehoeften, toegankelijkheidsstandaardgevingenM SK2 browser / toediening van de apparatuur . Doe niet aannemen dat dit duidelijk isMSC6 Maar in sommige teams zijn het wel alle andere TEAMS... maar doe nietMska8 verlies je focusM Ska9 Als een deel van je fiets een waterval wordt, dan ben jij volgens definitie agiliteit kwijtgeraakt. ## 6. Uit de scope Deze afdeling is net zo belangrijk als wat je doet. Waarom dit belangrijk is: - **Behoeft Scope Creep** - "Maar zouden we niet kunnen, ' zouden de gesprekken snel verdwijnen als je naar het 'Out of Scope'-gedeelte kunt wijzen. - **Stel verwachtingen** - Stakeholders weten wat **won't** Geleverd worden ( deze keer) - **Aktiveer toekomstige werk** - Items hier kunnen later hun eigen spec worden. - **Fokust het team.** - Iedereen kent de grenzen van dit werk Voorbeelden van goede Items uit de scope: - "Mobile ondersteuning ( zal in aparte specificaties worden aangevraagd - "Migration van bestaande data (het huidige spec behandelt alleen nieuwe gegevens)" - "Admin UI voor de konfiguratie ( zal eerst config-bestanden gebruiken)" - "Integratie met System X (afhankelijkheid nog niet beschikbaar Als iemand betoogt dat een item buiten de scope van -, - en , in scope moet zitten, dan is ' een gesprek die het waard is voordat de ontwikkeling begint, ,, niet halverwege de implementatie. ## 7. Open vragen Wees eerlijk over wat je niet weet. ## 8. Afhangingen Welke andere systemen afhankelijk zijn van deze eigenschappen? ## 9. Aanvaardingskriterien Hoe zal QA dit testen?? Deze zouden concreet moeten zijnM SK1 toetsbare uitspraken. Bonuspunten als ze ' in een formaat zijn geschreven dat automatiseerde tests zou kunnen worden. # Het probleem van Spec Bugs Hier is iets waar niet genoeg over wordt gesproken. **Specs kan ook fouten hebben.** Een specifiek fout is wanneer de specificatie zelf verkeerd is. ## Hoe Spec Bugs gebeuren 1. **Onvolledig begrip** - De persoon die de spec schreef, had het probleem of het bestaande systeem niet helemaal begrepen. 2. **Conflicterende vereisten** - Verschillende belanghebbenden willen verschillende dingen en niemand heeft het conflict opgelost. 3. **Technische Onmogelijkheid** - De spec vraagt om iets dat niet echt kan worden gedaan. 4. **Verandering van vereisten** - De wereld ging verder, maar de spec werd niet opgedateerd. ## Handhaving van Specific Bugs Als je een specifiek fout vindt als ontwikkelaar, heb je een paar opties: ### Optie 1: Steek het onmiddellijk op Dit is bijna altijd het juiste antwoord. Stuur een duidelijke boodschap aan de eigenaar van het spec: - Wat zegt de spec? - Waarom is het problematisch? - Wat denk je dat er in plaats daarvan zou moeten gebeuren? Doe dit op schrift. ### Optie 2: Implementeer het hoe dan ook Soms heb je de neiging om gewoon te bouwen wat je specifiek hebt, hoewel je het weet. **Doe dit.** Ik heb ontwikkelaars gezien die specs implementeren, waarvan ze wisten dat ze fout waren omdat "dat'is wat het zei om te doen " en dan verbaasd zijn als QA het verwerpt of gebruikers klagen. De uitzondering is als je de kwestie hebt opgelost, zei dat je er toch mee zou gaan, en dat in het schrift had gekregen. ### Optie 3: Fix It Yourself Als je' zeker bent dat je weet wat de specificatie moet zeggen, zou je misschien verleid worden om het zelf te corrigeren.. Dit is prima voor duidelijke typo's of formateringsproblemen, maar voor substantieve veranderingen moet je een akkoord van de belanghebbenden krijgen. Moet je nooit stilletjes de eisen veranderen. Dat is hoe je bouwfuncties bouwt die niemand heeft gevraagd. ## Spec fouten voorkomen De beste aanpak is het voorkomen van spec bugs in de eerste plaats: 1. **Involve Developers Early** - Heb een technische beoordeling van de specs voordat ze worden voltooid'We zullen onmogelijkheden en randgevallen zien die mensen bij het product kunnen missen. 2. **EerstQA betrekken** - Als het niet kan beprobeerd worden, kan het niet gebouwd worden. 3. **Gebruik voorbeelden vrijelijk** - Abstraktische beschrijvingen zijn gemakkelijk te misinterpreteren. Concrete voorbeelden "Gebruiker John heeft toestemming XM SK3 probeert YMSC4 te doen en ziet Z 4. **Bevestig tegen het bestaande systeem** - Maakt de spec aannames over hoe dingen nu werken? 5. **Herhaal op Specs** - Behandel de spec als een levend document. Terwijl je meer leert tijdens de implementatieM SK2 Dateer het opMSC3 Toekomstige ontwikkelaars zullen jullie bedanken . # Gewone Spec Pitfalls ## De roman-Longth Spec Sommige mensen denken dat meer detail altijd beter is. Als je spec verandert in oorlog en vrede, dan ben jij ofwel: - Je moet het in meerdere functies breken. - Ze speciferen implementatiedetails die aan ontwikkelaars overgelaten moeten worden. - We lossen het verkeerde probleem op en moeten teruggaan. ## De vage handgolf Het tegenovergestelde probleem: Build een rapportsysteem. Als je spec in één zin volledig kan worden vastgelegd. ## De oplossing-First Spec "We hebben een dashboard nodig " is het niet' is geen vereiste ; het is een voorgedachte oplossing M SK5 Misschien heb je wel een dashboard, maar misschien heb je iets heel anders nodig. ## Het bewegende doel Bedingingen die elke dag veranderen zijn't-behoeften; zeM SK2het is chaos . Als dingen zo snel veranderenMST4 snap je het probleem nog niet goed genoegM ST6 Stop en meer ontdekkingen doen voordat je specs schrijftM st7 ## De keukendus "Als we in ' zijn, kunnen we ook naar ,..." Nee. NeeWe zouden het niet kunnen,'t\. Elke functie heeft een prijs. # Het behandelen van soorten zoals broncode Dit is de mindsetsverschuiving die veranderde hoe ik specs schreef. **Behandel je spec precies zoals je sourcecode behandelt.** ## Verbindingscontrole Je specs zouden in versiecontrole moeten leven naast je code. Bevestig ze in. Veranderingen volgenM SK2 betekenisvolle commit-berichten schrijven als je ze aanpast . Dit creëert een geschiedenis van hoe de evolutionaire behoeften evolueerden. Bij Microsoft , hielden we specs in dezelfde repositories als code . Als een specifiek veranderd was, ging het door hetzelfde beoordelingsproces als code\ . Dit was niet de bureaucratie van '~;~ Het zorgde ervoor dat iedereen begreep wat er aan de hand was en waarom. ## Specs herfactoren Net zoals code refactoring nodig heeft, zo doen ook specs. Terwijl je meer leert tijdens de implementatie , moet het spec evolueren om dat leren te weerspiegelen. We vonden een betere manier om het probleem op te lossen? Dateer de spec op om de nieuwe aanpak weer te geven en te verklaren waarom je de richting veranderde. Ik ontdekte een randgeval dat je niet had gevondenM SK2 heb het niet beschouwd De spec na de ontwikkeling moet verfijnd zijn dan de spec voor de ontwikkeling.. Als het niet ' is, maar ,, heb je de kans vermist om te documenteren wat je geleerd hebt. ## Het levensdoelprincipe Een specificus is: 't "" is gedaan, "", wanneer de ontwikkeling begint.,, het is ', maar ', klaar voor die fase.., Het is gedaan als de functie schip en het onderhoudsmodus wordt. . Tot dan toe is het een levend document dat evolueert met je begrip van het probleem. Dit betekent niet' dat de specificatie elke dag moet veranderen. Grote veranderingen in de eisen moeten onderhandeld worden en onderhandelt worden . Maar clarificatiesM SK3 bijgevoegde voorbeeldenMSC4 nieuw ontdekte randgevallen moeten allemaal teruggevouwen worden naar de specificaties als je ze vindtMska5 Denk er zo over na: als je het niet zou doen. ## Waarom specs heden moeten blijven Hier is iets dat niet genoeg wordt besproken. **Je spec wordt de basis voor alles wat na . komt.** **Toetsplans**: QA schrijft testcases op basis van de spec. Als de spec verouderd isM SK2 testen ze het verkeerde dingMSC3 Je krijgt valse positieven ( testen voorbij, maar het kenmerk is gebrokenMST5 of valse negatieven | MST6 testen mislukken, maar de kenmerk werkt goedMst7 **Dokumentatie**: Gebruiker-documentatie, API docsM SK2 hulpsystemen , je fantastische RAG AI-ondersteuneragent | - ze beginnen allemaal van de spec |. Als het spec kenmerken beschrijft die niet bestaan |' | of features misses die doen | , | jouw docs zijn fout vanaf dag één | **Toekomstige ontwikkeling**: Als iemand zes maanden later de functie moet uitbreiden, zal hij het spec lezen om te begrijpen hoe het werkt. **Opboarden**: Nieuwe teamleden leren het systeem deels door specs te lezen. Daarom moet de spec aanpast blijven.. Het is niet alleen de eerste implementatie, maar het is ook fundamenteel voor alles. Bij Microsoft , behandelden we spec-updates met dezelfde belang als code-updaten . Spec-wijzigingen werden nageboekt | . Ze werden naast de code geversioneerd |. Als een eigenschap veranderd was ♫ , het update van de spec ♫' ♫ niet optioneel ♫ Als je de code verandert, maar niet het spec opdateert, heb je TECHNICAL DEBT gecreëerd. # De relatie tussen spec en implementatie Dit is iets dat junior ontwikkelaars vaak niet begrijpen. **De spec is niet de bron van waarheid.** De spec vertelt je wat je probeert te bouwen. Dit betekent: 1. **Species moeten evolueren** - Terwijl je dingen ontdekt tijdens de implementatie , het specifiek opdateer . Het document van wat je aan het bouwen bent. 2. **Implementatiedetails Don't behoort tot de specificaties** - Na het implementeren van ', documenteert de code zelf hoe op sommige plaatsen een '-Technische Speciek is, maar deze zijn zeldzaam en vaak een product van slechte '-Agile Frameworks'--- een huisdierhaat.-Verschrijven van een inherent adaptieve praktijk zoals Agile maakt me wat barf maken. 3. **Tests overbruggen de kloof** - Goede testtests bevestigen dat de implementatie overeenkomt met de eisen . ZeM SK2 zijn de uitvoerbare vorm van het spec. # Spezifikationen schrijven voor verschillende toeschouwers Verschillende mensen hebben verschillende dingen nodig van specs: **Uitvoerders** - Je wil de bedrijfswaarde en de ruwe tijdslijn kennen. **Product Managers** - Je moet begrijpen hoe het past in de bredere productstrategie en roadmap. **Ontwikkelaars** - Behoeft genoeg detail om correct te implementeren zonder te worden verteld hoe ze hun werk moeten doen. **QA** - Moeten weten hoe het werkt te verifiëren . Geef ze de aanvaardingskritieken **Ontwerpers** - Je moet weten wat de gebruikerservaring zou moeten zijn . Geef hen de gebruikersverhalen en interactiestromen. Het is nog beter dat ze een UX-speciek ontwikkelen / verhaalborden in parallel terwijl ze met de dev werken. Een goede spec bedient al deze publieken zonder te worden opgeblazen.. Gebruik delen en structuur zodat mensen kunnen lezen wat voor hen belangrijk is. # Je spec testen Voordat je een spec doet roepen, vraag jezelf af. 1. **Zou een ontwikkelaar die dit feature nooit gezien heeft, het kunnen bouwen van deze spec?** Als niet, heb je'mist details . Heb je nooit stukjes zoals M SK3 dit werkt als functie x in het huidige systeemMSC4 Eerst datMST5 zijn lui AFMst6 tweedeM st7 die functie zou kunnen veranderen of moeilijk te begrijpen zijn om randgevallen te zienMSt8 2. **Kunnen QA toetscases schrijven van deze spec?** Als het niet zo is, zijn jullie aanvaardingskritieken niet goed genoeg' niet duidelijk genoeg . 3. **Kun je iets volledig onbruikbaars bouwen dat nog steeds met deze spec overeenkomt?** Als dat zo is, , heb je de werkelijke eisen niet goed opgevangen. 4. **Beschrijft deze spec hoe te implementeren of wat te bereiken?** Als het de eerste is, dan heb je micromanagement. # De agile aanpak voor soorten Maar we zijn agile. We hebben geen specs nodig. Ik hoor dit vaak. Het is nonsens. Agile betekent niet: ' geen planning, " of " geen dokumentatie, ." Het betekent het reageren op verandering in plaats van een plan te volgen. **Specificaties zijn gereedschap, geen contracten.** Je creëert ze met enkel genoeg detail om te beginnen, dan ontwikkel je ze zoals je leertM SK1 Mijn 'Agile reis ' was nog extreemderMSC4 als je super goed bent in specs, zelfs die worden nog agilerMST5 je wil aanpassen en verbeteren op basis van wat je team wil | MST6 | behoeften |MST7 ## Hoe Agile Specs verschillen van Waterfall De fundamentele verschillen zijn het format of de lengte van ;, het denken en het proces. **Watervalspecies**: - Helemaal voorop geschreven voor elke ontwikkeling. - Het doel is compleetheid vanaf dag één. - Veranderingen hebben formele veranderingscontroleprocessen nodig. - Spec is "gesluit" zodra goedgekeurd. - Alssumptie: We kunnen alles weten voordat we beginnen. - Lineair: Spec → Bouw → Test → Verplooi **Agile Specs**: - Begin met minimale levensvatbare details om te beginnen. - Aanvankelijk onvolledigheid te verwachten aan het begin ( en dat's fineM SK2 - Veranderingen zijn verwacht en welkom. - Spec evolueert continu met de eigenschap. - Alssumptie: wij' zullen leren terwijl we bouwen - Cyclic: Draft → Bouw → Leer → Dateer op Spec → Bou meer → Leer meer De waterval-aanpak veronderstelt dat je alles perfect kunt bepalen voordat je een lijn code schrijft. Dat'is een mooie fantasieM SK2 In werkelijkheidMSC3 ontdek je de helft van de eisen als de gebruikers het feature daadwerkelijk uitproberen . Plan voor dat,, omarm het,. Gebruikers zijn de ULTIMATE testersMST7 Ze kunnen spul breken die je niet had,MST8 niet eens weten dat je bent,Mst9 is gemaakt met een tempo dat de causaliteit lijkt te overtreden,MSt10 verwacht het, MST11 plan het,mST12 registreer en repareer het, mst13 en voeg het toe aan een toekomstige spec Mst14 deze, als jeMst15 nog steeds in de spec zit,Mstr16s, Mst17 levensduur,M st18 ## Feedback Loops zijn alles In agile specting, feedback-loops zijn je beste vriend. JeM SK2 verzamelt voortdurend input en aktualiseert de specMSC3 **Ontwikkelaar Feedback**: "De eerste aanpak won't werkt niet vanwege XM SK3 IMSC4m stelt Y in plaats van ." ♫→ Dateer spec op om de nieuwe aanpak te weerspiegelen en waarom het veranderde ♫ . Uiteindelijk ben je ♫ **Gebruikerfeedback**: Probeer de functie met echte gebruikers te gebruiken. **Pivot** de spec gebaseerd op wat je leert. **Implementatiefeedback**: Terwijl je bouwt, ontdek je randgevallen , technische beperkingen , of betere benaderingen **QA-Feedback**: "De spec zegt X, maar niet'keek geen Y-scenario aan Elk van deze feedback-loops maakt de spec beter. Dit is waarom watervalspecifieken vaak falen: ze overslaan de terugkoppelingsloops. Tegen de tijd dat je ontdekt dat het spec verkeerd wasMSC2 heb jeM SK3 het verkeerde ding gebouwd en MST4 het spec veranderenMst5 betekent massaal herwerkenMSt6 **Big thing, feedback AS VEARLY AS FEASIBLE . It' is waarom ik bouwde [LLMApi](https://www.mostlylucid.net/blog/llmapi) Het helpt je een BIT te bouwen, dan gebruik je valse data om nuttig feedback te krijgen.** ## Onvoldoendeheid omarmen (Op de eerste keer) Dit is iets dat traditionele projectmanagers zenuwachtig maakt. **het' is helemaal oké als de eerste spec gaten heeft.** Merk delen als "TBD" als je het nog niet weet ' weet het nog steeds niet Dit is niet', "t sloppiness," ;, maar ', "de eerlijkheid," ., "Je weet het niet, '", "ik weet niet alles voor ogen", ., "Dat je het doet, betekent gewoon dat je', "een overtuigende specificaties zal schrijven voor de verkeerde oplossing." Begin met: - Maak het probleem duidelijk (you must know this) - Voorgestelde oplossingsmethode (mogelijke veranderingen) - Ruw "done" criteria ( zal verfijnd wordenM SK3 - Onbekende gemerkt als open vragen Dan vul je de gaten in terwijl je leert. ## De spec zal veranderen. Aanvaar dit nu: **Je spec verandert tijdens de ontwikkeling.** Als het niet werkt, heb je ofwel ongelooflijk veel geluk gehad, ofwel heb je niets geleerd. Veranderingen die je zou moeten verwachten: - De technische aanpak verschuift als je beperkingen ontdekt. - Afmetingsmaatregelen als je beseft dat je teveel bouwt (of te weinig ) - "Doe de criteria verfijnen als je het probleem beter begrijpt. - Nieuwe randgevallen ontdekt tijdens de implementatie - Betere oplossingen gevonden door experimenten Elke verandering moet zijn: 1. **Gedocumenteerd** - Dateer de spec op, donM SK2 verander niet alleen de code. 2. **Communicated** - Vertel aan de belanghebbenden wat er veranderd is en waarom 3. **Rationale** - Vertel wat je geleerd hebt dat de verandering heeft veroorzaakt De versiegeschiedenis van de spec' wordt een opname van wat je geleerd hebt. ## Wanneer Agile Speccing verkeerd gaat De agile aanpak kan falen als je één cruciale ding vergeet: **" zal veranderen " betekent niet' betekent geen grenzen** Slechte agile spectering: - Spec verandert elke dag zonder duidelijke reden. - Geen definitie van "done", dus het kenmerk blijft groeien. - De veranderingen zijn niet communicatief. De spec-updates zullen direct naar je collega's hersenen springen. - "Agile" gebruikt als excuus om dingen niet door te denken. - Stakeholders waren verbaasd door de scopeverschuivingen omdat niemand ze vertelde. Goede agile spectering: - Veranderingen gebeuren om duidelijke redenen gebaseerd op leren. - De criteria zijn duidelijk, zelfs als andere details niet zijn. - De veranderingen worden besproken en gedocumenteerd. - Agile zijn betekent niet ' sloppy zijn. - Stakeholders maken deel uit van de feedback-lus. De spec is een levend document, maar het is geen chaos. Het evolueert op basis van leren. 'AGILE' doet nooit wat je wilt en roept het 'AGile'. Het is een dynamisch proces met de SOLE GOAL om het beste materiaal zo snel mogelijk te bouwen. [Agile Manifesto ](https://agilemanifesto.org/principles.html) Het eerste principe van ' is: .. > " Onze hoogste prioriteit is de klant te bevredigen. > Door vroege en continue levering. > van waardevolle software." Het is niet om de code uit te spinnen omdat je het gevoel leuk vindt. ## Nog genoeg detail om te beginnen De vraag is: "Hoe gedetailleerd moet de spec zijn?" Voor sommige functies die kunnen zijn: - Een paragraf die het probleem beschrijft. - Drie boelpunten die de oplossing schatten. - Een duidelijke definitie van hoe "done" eruit ziet. Voor anderen kan het zijn:: - Gedetailleerde gebruikerstromen met spiegels - Prestatiebehoeften ondersteund door gegevens - Integratiespecificaties voor meerdere systemen **Voeg details toe waar onzekerheid bestaat.** Als iedereen het eens is over hoe iets moet werken, hoef je het niet in ongrijpelijke details op te schrijven. Maar uiteindelijk is er genoeg detail om de terugkoppelingslus te starten. ## Templates en AI: snel beginnen Denk niet over het beginspectief na. De bedoeling in het begin is genoeg te hebben om je onmiddellijke behoeften aan te kunnen voldoen. - Een ruwe schatting ( Zelfs een SWAG - Shitty Wild-Gehad Gedacht - is beter dan nietsM SK4 - Invoer voor discussies over prioriteit. - Gewoon genoeg voor jou persoonlijk om te beginnen met coderen. **Gebruik werkvoorbeelden**: Heb een basis-template met de sleutelsequenties. Een eenvoudige werkvoorbeeld zou kunnen zijn: ``` # [Feature Name] ## Problem [What's broken? What pain exists?] ## Proposed Solution [High-level approach] ## What "Done" Looks Like - [ ] Specific, testable criterion 1 - [ ] Specific, testable criterion 2 - [ ] Specific, testable criterion 3 ## In Scope - - ## Out of Scope - - ## Open Questions - - ``` Dat is het. 5 minuten om dat in te vullen en je hebt genoeg om te praten of zelfs te bouwen. **AI gebruiken voor het tekenen van specs**: gereedschappen als Claude of ChatGPT kunnen briljant zijn om een eerste tekening te krijgen . Voeg het het probleem en een bepaalde context toe , vraag het om een spec te schetsen M SK3 Maar - en dit is cruciaal - **Laat de AI's grondigheid je verleiden om alles te toevoegen.** AI houdt ervan om uitgebreid te zijn. Het' zal je delen geven over veiligheidsbeoordelingen , Performentiebehoeften , Toegankelijkheid M SK4 Internationalisering Mske5 Foutbewerking M Ske6 LoggingMske7 Monitoring Msche8 Deployment Strategy M Schepback Plans Msko10 en zeventien andere dingen die je nodig zou kunnen hebben. Strip de meeste daarvan uit. Hou wat je nu nodig hebt. De rest kan later toegevoegd worden als je het echt nodig hebt Denk aan de AI-gegenereerde spec als een menu. Kies de bits die ertoe doen dat je begint te beginnen. Het doel is: ' is geen volledige spec, maar ;, het is genoeg spec om te beginnen met werken, ., of dat een snelle schatting is, ,, een beslissing over prioriteit, or gewoon duidelijkheid over wat je zelf bouwt. ## Het Collaboratieve Model Hier is wat er verandert in agile. **Je schrijft geen spec en gooit hem over de muur naar ontwikkelaars.** De spec is een samenwerkingswerk. De beste aanpak die ik gezien heb. 1. **Product/PM schets het probleem** - Wat moet worden opgelost en waarom 2. **Ontwikkelaars bijdragen aan een technische aanpak.** - Hoe kunnen we het oplossen? 3. **Ontwerpers bijdragen aan UX-behoeften.** - Wat de gebruikerservaring zou moeten zijn 4. **QA bijdraagt aan testscenarios.** - Edge-gevallen en validatiemethoden Iedereen draagt bij aan de spec. Nog belangrijker: , betekent dat de spec weerspiegelt wat ' werkelijk mogelijk is, niet wat iemand alleen maar wilde. ## Evolutie tijdens ontwikkeling Hier' waar agile specs verschillen van traditionele specs **Het kenmerk kan evolueren terwijl je het bouwt.** Je ontdekt dat je oorspronkelijke aanpak won' niet werkt? Dateer de spec op om de nieuwe aanpak te weerspiegelenM SK2 Je probeert het feature en realiseert je dat het het probleem niet oplost. Gebruikerfeedback toont aan een betere oplossing? Inkorporeren en de verandering verklaren Deze evolutie is een eigenschap. Maar dit creëert een probleem. ## De schattingsvraag Dit is het vuile geheim van agile: **Evalueren is bloederig moeilijk als eigenschappen kunnen evolueren.** Traditionele schatting stelt voor dat je weet wat je bouwt. Agile schatting erkent dat je het niet weet. **Je schat de afstanden, geen absolutes.** In plaats van " zal dit 3 weken duren", zeg je ", ergens tussen 2 en 5 weken afhankelijk van wat we ontdekken. **Je schat in iteraties.** We zullen een sprint doorbrengen om dit te onderzoeken en terug te geven wat we geleerd hebben. Dan kunnen we de rest nauwkeuriger beoordelen. **Je tijd-box in plaats van scope-boxingM SK2** We zullen er 2 weken aan besteden. Maar al deze benaderingen hebben één cruciale vereiste: : **Je moet weten wat " betekent.** Zonder een duidelijke definitie van gedaan, kan een eigenschap eeuwig metastaseren. Het is een gemeenschappelijke kritiek op Agile vergeleken met Waterfall-aanpakken. Zonder een concrete specificatie kunnen er geen goede schattingen zijn. # Definiëren van "Doe" (Of hoe je functiemetastas stoptM SK3 Dit is waar veel agile specs uit elkaar vallen. Zonder een duidelijke definitie van gedaan , featuren doen het niet af' ze meten niet af, ; ze metastasiseren, MSC3 ze verspreiden zich, . ze groeien naar andere delen van het systeem, . Voordat je het weet,, je " eenvoudige commentaarsysteem, " is veranderd in een volledig sociaal netwerk met boodschappen, msc9 profielen, m sc10 en vriendelijke verzoeken. ## Het probleem met vage "Done" I' heb specs gezien met aanvaardingskriterien zoals: - "Gebruikers kunnen commenteren op posten" - "De dashboard toont relevante informatie" - "De zoekopdracht werkt goed" Dit zijn geen definities van gedaan, maar vage ambities. De ontwikkelaar moet het weten: **Wat betekent het dat ik niet meer aan deze functie kan werken?** ## Beton schrijven "Doen" Criteria Goede "doneM SK1 criteria zijn: - **Testbaar** - Je kunt verifiëren of het - **Spesifiek** - Geen vage woorden zoals "goed" of "belangrijk - **Begrensd** - Ze betekenen geen oneindige omvang. **Slechts.**: "Comments should be moderatedM SK2 **Goed.**: "Admin-gebruikers kunnen de opmerkingen goedkeurenMSC2 afwijzen, of uit het adminpanel verwijderenM SK4 NietMST5Geapproofde opmerkingen zijn niet zichtbaar voor gewone gebruikersM ST6 E-mail-notification gestuurd aan admin wanneer een nieuw commentaar wordt gestuurtM st7 **Slechts.**: "De zoekopdracht moet snel zijn" **Goed.**: "De zoekopdracht gee terug resultaten binnen 200ms voor het m95ste percentiel van vragen in vergelijking met een dataset van M100,000posities. De resultaten worden rangschikt volgens relevantie. **Slechts.**: "Dashboard toont nuttige metingen" **Goed.**: "Dashboard-displays: totale pagina-aansigten |( laatste | 30 dagenM SK5 unieke bezoekers |( |last | 30 | dagen ), bovenste |M5 posten per aansigte ♫( | laatste ♫ 7 ♫ dagen |МSK12 | en visioenverdeling per land |m. | Alle metingen worden één keer per uur opgedateer | Let op het verschil? De goede voorbeelden vertellen je precies wat er moet zijn en wanneer je dingen kan stoppen te toevoegen. ## De niet-toegankelijke afdeling is je vriend Herinner je nog eens dat ik zei dat de 'Out of Scope'- sectie net zo belangrijk is als wat ' in het bereik heeft. Voor elke functie is er tientallen dingen die je zou kunnen toevoegen. De 'Out of Scope'- sectie roept expliciet uit wat jij niet doet' Dit voorkomt de M SK4 terwijl wij in de ruimte zijn, en ook de gesprekken die de metastase van een functie veroorzaken. **In scope**: Ingebedde opmerkingen (een niveau van antwoorden) **Uit de scope**: Onbegrensde commentaarstrooiing, commentaar stemmenM SK2 commentairstrooien , beste commentaarsorteringMSC4 commentaren permalinks Als iemand nu suggereert dat "shouldn't commentaties een upvote hebben ?", kun je naar de spec wijzen en zeggen: \""\"dat\" '\" buiten het bereik is voor deze iteratie\".\"Laten we dit als een aparte eigenschap bespreken zodra de basiscommentaties werken\". Oh en de volgende spec? Nou, je hebt al een hoop ongebruikte goede ideeën vastgevangen. ## Time-Boxen als een laatste resort Soms weet je echt niet hoe het eruit ziet als je begint. We zullen 2 weken ( of tot het backend klaar is ) verschillende benaderingen van de recommendedie-algoritme prototyperen. Maar let op, je hebt nog steeds een betonnen "gediend"conditie (2 wekenM SK4 en dan beoordeelt je ). Je ' bouwt niet zomaar onbepaald . Deze verkenningen worden vaak gedaan in een context zoals een Sprint in SCRUM ### Spikes & Sprints. Een Spike is een van deze 'ga een spelletje spelen en uitzoeken hoe deze technologie werkt' het kan zo lang duren als een Sprint ( of langer ) maar het duurt meestal slechts een paar dagenM SK4 Als ik dit devs heb, vraag ik meestal naar een mail aan het einde Een Sprint moet aan het eind deliverables hebben. (iets dat iemand anders dan de persoon die erin betrokken is, kan testen voor de loop. Ze zijn ook leuk voor werknemers en helpen het team Ik verzamel vaak Spike-ideeën tijdens een project en als er ' een tijdje is, laat ik de werknemer één kiezen om te verkennen. ## Voorbehoeften van schaalvergroting tijdens ontwikkeling Zelfs met een duidelijke "doneM SK1 criteria , kan de schaal glijpen. Je ontdekt randgevallenMSC4 Je realiseert je dat gebruikers iets nodig hebben wat je niet had gehadMST5 niet beschouwdMst6 Hoe kan je dit aanpakken zonder je definitie van gedaan te breken? **Dokumenteer het.** Als je iets nieuws ontdekt dat moet worden toegevoegd, Dateer het spec op. Laat duidelijk zijn dat de scope veranderd is . Besloten van belanghebbendenM SK3 Dit dient twee doelen: 1. **Onzichtbaarheid** - Iedereen weet dat de scope veranderd is en waarom. 2. **Kostbewustzijn** - Stakeholders zien dat dingen toevoegen de tijdlijn beïnvloedt Als je spec blijft groeien, dan is dat een signaal. Ofwel bouw je het verkeerde ding, ofwel moet je terugkijken en opnieuw nadenken, of dit meerdere functies moeten zijn, of je moet de scope verkleinen om iets nuttigs sneller te verzenden. ## Wanneer het gedaan moet worden Op een bepaald moment moet je het verzenden. Een goede test: **Kunnen gebruikers waarde van deze functie krijgen zoals ze standt?** Als ja, stuur het naartoe. Je kan altijd herhalen in de volgende versieM SK2 Klaar is niet ' betekent geen verbetering van ♫" zal nooit worden verbeterd ♫ ." Het betekent dat ♫" het probleem goed genoeg oplost zodat de gebruikers er baat bij hebben en we kunnen verdergaan met andere werk ♫ Als nee, uM SK1 is nog niet klaar, ongeacht wat je specifiek zegt . Het moeilijkste deel van agile is: ', 't beginnen met het werk', ;, 'het stoppen met het werken' en ., 'onduidelijk'. Maar onthoud dat je moet weighen of je het aan iedereen laat vrijgeven, een nauwe groep voor A has/B M SK2 UAT ( gebruiker aanvaardingstestsMska4 DatMske5 vaak een zakelijke beslissing is om risico's te beoordelenMsek6 Soms is het publiek gek en ziet een gedeeltelijk klaar voorskou als de GOSPEL voor jouw systeemkwaliteitMsku7 Als dat een probleem is, is een gecontroleerde groep veiligerMsko9 # Het proces van spec-beoordeling Een spec is niet gedaan wanneer je het klaar hebt te schrijven. ## Behandel Spec Reviews zoals Code Reviews De beste praktijk die ik geleerd heb bij Microsoft: **spec reviews werken precies zoals code reviews.** Ze zijn samenwerkend, niet tegenstrijdig, hoewel de jongensclub van Microsoft vaak de spec-beoordelingen als gladiatoriaal gevecht maakten als iemand een kerel was. Bij het herzien van specs: - **Vra vragen** Wat gebeurt er als X voorkomt? - **Voorstel alternatieven** - "Heb je een Y-aanpak bedacht? - **Vermisde gevallen aanwijzen** - "Dat doet het niet'ontdekt geen Z-scenarioM SK3 helpt het beeld te completeren - **Aannames over uitdagingen** Waarom lossen we het op deze manier? ?" zou betere benaderingen kunnen laten zien. Wanneer je spec wordt bekeken: - **Vragen zijn kansen.** Ze laten zien wat onduidelijk is en wat je misst. - **Suggestionen verbeteren de spec.** - Beschouw ze serieus zelfs als je ze niet accepteert. - **Het is niet persoonlijk.** - Net als code-bespreking, het gaat om het verbeteren van het werk. - **De criticus kan het fout hebben.** - Vertel waarom je aanpak zinvol is. De beste spec-beoordelingen zijn gesprekken. Je gaat heen en weer. Je leert van elkaarM SK2 De spec die ontstaat is beter dan wat een of andere persoon alleen zou kunnen hebben geschreven. ## Wie zou moeten herzien? Kry recensies van alle relevante perspectieven: **Ontwikkelaar Review** - Gaat dit echt werken ? Zijn er technische beperkingen die we nog niet hebben overwogen ' niet beschouwd M SK3 Is er genoeg detail om te implementeren MSC4 Welke vragen zou je hebben als je deze bouwde? **Product Review** - Heeft dit het juiste probleem opgelost ? alignt het zich op de productstrategie ? Wat is er mis met '? **Design Review** - Makt het gebruikerervaring zinvol? Hebben we de toegankelijkheid in beschouwing genomenM SK2 Wat is met mobiels ? Behandelen we het probleem van de gebruiker of bouwen we alleen functies op? **QA-bespreking** - Kunnen we dit testen? Zijn de aanvaardingskriterien duidelijk genoeg ? Hoe zit het met randgevallen? Je hebt geen formaliteit nodig'we hebben geen formele tekens nodig -uit iedereen af te trekkenM SK2Je hebt hun input nodig om de spec beter te maken. Zie het als MSC4op verzoek tot opmerkingenMska5 niet mska6op vraag naar goedkeuringMske7 ## Gemeengoede hersieningsvragen Goede reviewers stellen vragen die het spec verbeteren: - "Wat gebeurt er als de gebruiker X doet? - "Hoe interacteert dit met de bestaande eigenschap YM SK1 (integratie) - Wat is ons terugval als de afhankelijkheid Z niet klaar is? - "Kunnen we dit vereenvoudigen door W te doen in plaats van ?" - "Hoe weten we of dit succesvol is? - "Wat doen we niet? Geen van deze vragen zijn geprobeerd. Ze zijn echte vragen die het spec helpen uit te vissen. ## Incorporatie van feedback Je wint niet elke suggestie te accepteren. 1. **Beschouw het eerlijk.** - Doe het niet af omdat ze het niet begrijpen. 2. **Als je het accepteert.** - Dateer de spec op, dank de criticus 3. **Als je het niet accepteert** - Vertel waarom 4. **Als het ' buiten de scope is.** - Voeg het toe aan de sectie "Gezonderlijk scope" of "Future EnhancementsM SK4 De spec zou beter moeten worden met elke ronde van de beoordeling. Als het niet klopt't , ben je niet aan het luisteren of zijn jullie beoordelaars niet betrokkenM SK4. Kry een overzicht van al deze perspectieven voordat je de implementatie begint. Problemen vinden in de speckostenminutes; ze vinden in productiekosten wekenM SK2 # Een concrete voorbeeld: Markdown Translation Service Om dit allemaal minder abstract te maken, zie je hier ,' hoe een spec eruit zou kunnen zien voor de automatische markdown-overdrachtsfunctie die ik heb gebouwd voor deze blog. ## Probleemverklaring Blogposts die in het Engels zijn geschreven, sluiten alleen niet uit-English-sprekende lezers. Handmatige vertaling van elke post naar meerdere talen is tijdM SK2 Beperkt en vertraagt de publicatie . We hebben een automatiseerde oplossing nodig om markdown-blogposts te vertalen naar meerdere doeltalige talen zonder de manuelle interventie voor elke post te hoeven te betrekken. ## Oplossing Implementeer een achtergronddienst die automatisch markerdown-bestanden vertaalt naar geconfigureerde targettalige talen met behulp van de EasyNMT machine-overdrachtsdienst. - Monitor merkdown-bestanden voor veranderingen - Trek vertaalbaar tekst uit terwijl je de markdown-structuur en codeblokken bewaart. - Batch-overdrachten voor efficiëntie - Genereer vertaalde markerdown-files met de juiste taal-aanhangsels ## Succeskriterien (Wat is het? Deze criteria vertellen ons precies wanneer we kunnen stoppen met werken aan deze feature: - Nieuwe blogposts worden automatisch vertaald naar alle geconfigureerde talen. (initieel: SpaansM SK2 FransMST3 DuitsMst4 ItaliaansM ST5 PortugeseM st6 ChineesM St7 ArabischMstr8 HindiMSt9 JapansMsl10 KoreaanM str11 HollandseMsv12 Russisch Mstr13 - De vertaalde lêers behouden dezelfde markdownstructuur als de originelen. - Kodeblokken, beeld URLs, en formatering blijven onveranderd - De vertaling is binnen 15 minuten klaar voor een typische blogpost. - Het systeem vertaalt alleen - bestanden die veranderd zijn. - De dienst begint succesvol zelfs als de vertalings-API tijdelijk niet beschikbaar is. - Fouten tijdens de vertaling worden gelogd, maar don' crasht de applicatie niet. Let op dat ze specifiek en testbaar zijn. We kunnen elk ervan verifiëren. Als alle overeenkomsten zijn bereikt , weMSC3 zijn klaarM SK4 We blijven niet toepassen van functies als Mska6vertalingkwaliteitscoreringMske7 of mska8bewerking van de handmatige vertalingMsek9 tenzij we de scope expliciet uitbreiden. ## In scope - Agtergronddienst om markdown-bestanden te verwerken - Integratie met EasyNMT-vertaling API - Hash-gebaseerde veranderingsdetectie om onnecessaire hertranslaties te voorkomen. - Batchverwerking om EasyNMT's woordbeperking aan te pakken - Round-robin-laad evenwicht tussen meerdere EasyNMT voorbeelden - Behoeften van markdown syntax, codeblocks, en beelden tijdens de vertaling ## Uit de scope - Gebruiksinterface voor manueel vertalingsbewerking (toekomstige verbetering) - Vertaling geheugen of glossaire management (moet toevoegen als kwaliteitsproblemen opduiken - Echte-tijdsvertaling (ondergrondbewerking is aanvaardbaar - Vertaling van code-observaties in codeblokken (intentioneel uitgesloten) - Automatische kwaliteitsbeoordeling van vertalingen (initieel vereist handmatige beoordeling) ## Technische beperkingen - EasyNMT heeft een ~500 woordbeperking per verzoek. [Meest duidelijk-nmt](/blog/mostlylucid-nmt-complete-guide) Die kan de verdomde BOOKS nemen) ; moeten according batch maken. - De vertalingsdienst kan langzaam zijn. - Veel EasyNMT-instances nodig voor redelijke prestaties (nope meestal duidelijk-nmt 😜) - Lêersysteem I/O moet geen hoofdtoepassing blokkeren. ## Open vragen op Spec-tijd - ~~ Moeten we de vertalingen cacheren om te voorkomen dat we onveranderde lêers opnieuw vertalen? **Opgelost: Ja, met het gebruik van file hashvergelijking** - ~~Hoe gaan we om met EasyNMT-dienstfalen? **Opgelost: Log fout en file overslaan; zal herproberen op de volgende dienst herbeginning M SK2 een circuitbreker ( misschien een spikeMSC4** - Welke kwaliteitsproblemen kunnen we zien met technische inhoud? **Bevestiging: Ship en beoordelen; handmatige hersiening van de afvangproblemen** ## Wat we geleerd hebben tijdens de implementatie Er ontstonden verschillende dingen tijdens de ontwikkeling die het spec verfijnden. **Batch grootte aanpassing**: Gestart met 20-lijnenblokkies, maar vond dat 10 lijnen betrouwbaarder waren om onder EasyNMT te blijvenM SK4s woordlimiet te houden terwijl je de context bijhoudt **Beeld Ontdekking**: In het begin, werden beeld-filenames in markdown naar de vertalingsdienst gestuurd , fragbrekende zinsverwerkingM SK3 Lêerverlengingherkenning toegevoegd om beeldpaadjes te overslaanMSC4 **Beskikbaarheid van de dienst**: EasyNMT kan temperamentaal zijn bij het opstarten. Gevoegde gezondheidscontrole die de `/model_name` Endpunt voor het proberen van vertalingen. **Hash-opslag**: Oorspronkelijk gepland databasisopslag voor file hashes, maar op lêersysteemM SK2 gebaseerd `.hash` Lêers werden eenvoudiger en database-afhankelijkheid voor deze dienst werd vermijden. Deze lessen werden teruggevouwen in documentatie en later geïnformeerd met vergelijkbare kenmerken. ## Waarom dit speek werkte Deze specificatie volgde de besproken principes: - **Problem-first**: Gestart met het echte probleem (menselijke vertaling is langzaam) is niet de oplossing - **Maak de omvang duidelijk**: Ze zeiden expliciet wat we niet deden. - **Regterkant detailniveau**: Gespecificeerd wat nodig was om te gebeuren (bewaren de markdown-structuur) zonder de exacte implementatie te voorschrijven - **Levend document**: Open vragen werden opgelost en beslissingen werden gedocumenteerd naarmate de implementatie progresseerde. - **Collaboratief**: Opgeroepen tijdens implementatieproblemen ( zoals de handling van beeld-lêernames) werden besproken en opgelost Het resultaat was::, een functie die al maanden in productie is, ', die elke blogpost automatisch vertaalt met minimale interventie. # Gemeengoede vragen over Agile Specs Op basis van wat we hebben behandeld, zijn hier vaak gestelde vragen. ## "Hoe heb ik echt een spec nodig voor een kleine functie? Het hangt af van: "small." Als het' echt triviaal is. - Evalueer hoe lang het zal duren. - Besloten van belanghebbenden - Bevestig dat QA weet wat te testen. - Dokumenteer wat je hebt gebouwd voor toekomstige referenties. Dan ja, zelfs een snelle spec helpt. Het is niet nodigM SK2 het hoeft niet formeel te zijn . Een paar buletpoints in een kaartje die het probleem bedekt ProblemMST4 oplossingMst5 en Klaardoende criteria zijn vaak genoegMSt6 De test : als je kan ' niet uitleggen hoe het eruit ziet in twee zinnen. ## "Hoe ga ik om met belanghebbenden die alles in de scope willen? Point to the Out of Scope section. Vertel dat 1. **Meer verhoogde tijdlijn toevoegen** - Willen ze functie A in 2 weken of functies A, BMSC3 CM SK4 en D in \ 3 maandenMST6 2. **We kunnen het volgende doen.** Dat is een geweldig idee. Laten we de kern eerst laten werken. 3. **Time-box drijft prioriteiten aan** We hebben 2 weken. Welke van deze is het belangrijkste? Als ze beweren dat alles even kritisch is, suggereren ze om te kiezen welke andere werk dan te vertragen. ## "Wat als de spec zo veel verandert dat ' onherkenbaar is vanaf het begin Dat's fine, zo lang alsM SK2 - De veranderingen zijn gedocumenteerd (update de spec, donM SK2 niet alleen de code veranderen ) - De veranderingen worden gecommunicat (De belanghebbenden weten wat en waarom het veranderd is. - Je hebt iets geleerd. (de veranderingen weerspiegelen het leren. Als de spec onherkenbaar is omdat je het probleem in het begin helemaal verkeerd begrepen hebt, dan is dat een teken om meer ontdekkingen te doen voordat je de volgende keer begint. De versiegeschiedenis van de spec' moet je vertellen wat je geleerd hebt. In Startups heet dit een 'Pivot' waar je begint met het bouwen van een spel en uiteindelijk een verbazingwekkend messagingsysteem bouwt. Don' niet te verstopt in de . Als er ' kansen zijn door om te draaien, neem ze. ## " Moet ik specs schrijven voor bugfixes? Voor kritische bugs: nee, stel ze gewoon op. Voor complexe bugs die veelvuldige systemen beïnvloeden of architecturale veranderingen nodig hebben.: ja, . Behandel het als een eigenschap.. Wat?' is gebroken. Voor alles tussenin:: gebruik je oordeel. Als de oplossing niet duidelijk is, of als er bijwerkingen kunnen zijn. Dit geldt vooral voor beveiligingsbugs. Je moet EXACT weten wat je fixeert en hoe je het zal verifiëren. ## "Hoe formeel zou het spec moeten zijn? Zo formeel als je team nodig heeft. Sommige teams zijn goed met gedetailleerde JIRA-tickets. Anderen willen goede documenten in versiecontroleM SK2 De formaliteit is minder belangrijk dan de inhoud: - Maak een probleemverklaring duidelijk - Voorgestelde oplossing - Definitie van gedaan - Maak de scopegrenzen duidelijk Je kunt dat in Markdown schrijven. Dit is de vaak onbenoemde Sleutel tot agile ontwikkeling; en waarom ik Agile Frameworks haat (en SCRUMM SK2 Het hele punt is dat je proces, net als een agile spec, ook aanpassingsvermogen moet hebben. Als 5 dagcycli voor één team werken, maar 2 weeksprinten voor een ander, dan doen ze dat. Het hele idee is om het beste product te maken; je team is de machine die dat product maakt Als manager kijk je naar wat je uitgaven zijn; als het bord een verbrand grafiek nodig heeft, hoe kan je dan de huidige data gebruiken om er één te bouwen. Als je de impact op het team kunt verminderen, dan is dat jouw deel. ## "Wat als ik de enige ontwikkelaar op het project ben? Je hebt nog steeds specs nodig, misschien meer dan dat. In zes maanden tijd wanneer je deze functie moet uitbreiden , won jeM SK3 je herinnert je niet waarom je bepaalde beslissingen hebt genomen\. De spec is je verleden zelf die met je toekomstige zelf praat\. Plus je moet nog steeds: - Evalueer het werk voor wie je betaalt. - Definieer wat "done" betekent zodat je kunt afsluiten. - Dokumenteer wat je hebt gebouwd voor anderen die er later bij kunnen komen. Spezifikationen schrijven voor jezelf is net als het schrijven van eenheidstests: het voelt trager nu, maar het spaart later tijd ( zoals ik , IM SK3m in mijn 50s MSC5 Ik vergaat heutzutage SHITMスク6 schrijven ze op zodat het gedaan wordtMska7 zelfs als hetM Ska8 alleen een github-uitdaglijst isMske9 ## "Hoe moet ik omgaan met scope creep vermomd als 'beperking van de eisen Als iemand zegt: " Oh, ,", vergeet ik te vermelden dat het ook zou moeten doen. Antwoord: M SK1Dat'is een goede vereisteMST3 maar hetMst4 is niet wat we in de specificatie hadden toegekendMSt5Laten we dit nu toevoegen aan de Afzonderlijk bereik sectie en discussiëren of het inbegrepen moet worden, of het voor versies bewaard moet worden. Als het echt een vereiste is (niet een mooi-toM SK2haveMSC3 danMST4 1. Dateer de spec op om ze in te sluiten. 2. Dateer de schatting op 3. Bespreken over de nieuwe tijdlijn of wat te knippen om de oorspronkelijke tijdlijn in te passen. Moet nooit stil de schaalkraep absorberen. Het' zal je schattingen en geloofwaardigheid vernietigen ## "Kan ik beginnen met coderen voordat de spec klaar is? Ja, als je' een prototype maakt om open vragen te beantwoorden. Prototyperen om te leren, is goed: "We hebben drie benaderingen . Laat me elk uitsplitsen om te zien welke het beste werkt ." Dat informeert de spec Het bouwen van productiecode voordat de spec klaar is, betekent dat je'we raden naar de eisen. JeM SK2 zal waarschijnlijk het verkeerde ding bouwen. Uitsondering: als jeM SK1 de producteigenaar en ontwikkelaar bent (soloproject), kan je tegelijkertijd specificeren en coderenMSC4 Maar documenteer toch je beslissingen terwijl je verdergaat. De ' tot de spec klaar is ' is een GREAT manier om de werknemers te laten opladen voor het begin . Evaluatie van technologie-aanpakkingen M SK3 schrijven van een gemeenschappelijke boilerplaat etc. ## "Wat als mijn team de specificaties niet leest? Zoek uit waarom: - **Te lang?** Maak ze korter, meer scanbaar - **Te formeel?** Gebruik een lichtere formaat - **Niet relevant?** Maak er zeker van dat ze echt het detail nodig hebben dat je voorstelt. - **Slechte gewoonte?** Begin spec-overprüfung te eisen voordat ontwikkeling begint. Als mensen spec-beoordelingen overslaan en dan het verkeerde ding bouwen, maakt de pijn zichtbaar. Als ze in een obscure wiki begraven zijn, zal niemand ze lezen. ## "Hoeveel tijd moet ik besteden aan een spec? Duimregel: 5-10% van de ontwikkelingstijdM SK2 Voor een 2-weeksfunctieM SK1 1-2 dagen op de spec. Voor een 1-weeks-functie: een halve dag op de specM SK2 Voor een 2-dag-functie: een uur of twee op de specM SK2 Maar wees er niet religieus over. Sommige kenmerken hebben meer nodig.-, voorzichtig denken.., andere zijn duidelijk en het spec duurt maar een paar minuten. Als je' meer tijd besteedt aan het spec dan aan de implementatie ,, denk je erover teveel over na. ## "Waarom zijn schattingen altijd verkeerd? Omdat software-estimatie fundamenteel moeilijk is. **schattingen werken alleen als je EXACT die taak eerder gedaan hebt in die omgeving.** Wat bijna nooit gebeurt. Elke keer als je schatt,,, heb je met ' te maken. - **Onbekend onbekend** - Probleems die je niet kent' bestaan nog niet - **Onbekende** - Problemen waarvan je weet dat ze bestaan maar geen idee hebben hoe ze op te lossen. - **Veranderde eisen** - De spec evolueert naarmate je bouwt. - **Milieuverschillen** - Die bibliotheek werkte in je laatste project, maar deze heeft verschillende afhangingen. - **Tooling-problemen** - Het bouwsysteemM SK1 deploymentpijplijn, of de testomgeving gedragen zich anders. - **Integratie verrassingen** - De API die je belt, ', werkt niet helemaal zoals gedocumenteerd. - **Menselijke factoren** - JijM SK1 bent onderbroken, ziek , of bezig met productieproblemen. - **Financiën** - soms is een kleinere versie eerder nodig omdat *Anders zouden we niet meer geld hebben.^, ', COMMON in startups, ., (, I', zullen een artikel hebben over ', Startup dev, ' en hoe het verschilt van ', normale dev en ' in de toekomst. Dit is waarom: - **Ranges beat point schattingen** - "2-5 dagen" bevestigt onzekerheid - **Spikes help** - Spend een dag onderzoeken voordat je het volledige werk schat; is deze techniek moeilijker of makkelijker dan ik dachtM SK2 waar kan het tijdsparen, etc. - **Time-boxing werken** We zullen 2 weken doorbrengen en zien wat we krijgen. - **Geschiedenisgegevens** - Opvolg hoe lang vergelijkbare taken er daadwerkelijk waren - **Padding is eerlijk.** Als je denkt: 3 dagen ,, zeg dan: Hoe nieuwsgieriger het werk is, hoe slechter je schattingen zijn.. Het bouwen van dezelfde CRUD-vorm die jij hebt gemaakt, ' heb je gebouwd, 50 keer,? Je zal dichtbij zijn, ' Integratie met een nieuw service met behulp van een onbekend protocol. Daarom hebben specs een duidelijke "doen"kritieken . Je kuntM SK3 geen nauwkeurige schatting makenMSC4 maar je kan bepalen wanneer je moet stoppen. ## "Wat dacht je van specs voor onderzoeks- of ontdekkingstakken? Deze hebben verschillende criteria nodig. "done" criteriaM SK2 In plaats van "functie X werktMST4 het isMst5s mst6 wijMSt7we hebben de vraag beantwoord YM st8 Voorbeeldspectief voor verkenning: - **Probleem**We weten niet of benadering A of benadering B beter is voor de aanbevelingsmachine. - **Oplossing**: Spend 1 week prototyperen van beide benaderingen - **Klaardoende criteria**: We hebben werkprototypes van elke performance metriek voor beide , en een richtlijn om te volgen. - **Gezonder bereik**: Produktie-implementatie (komt nadat we beslissen Tijd-boxen is essentieel voor de verkenning. Zonder het zou onderzoek nooit eindigen. ## "Hoe moet ik specs schrijven voor functies die ik niet ken' nog niet helemaal begrijpen ?" Begin met wat je weet: - Probleemverklaring (you should know this) - Voorgestelde aanpak (je beste gok) - Open vragen (alles wat je niet kent - Klaar gestelde criteria (albehalve ruw ≥) Merk delen als "TBD." Wees eerlijk over onzekerheid Gebruik dan het spec-beoordelingsproces om gaten te vullen. De gesprekken tijdens de beoordeling verklaren vaak wat je niet verstandigde. Onthoud: onvolledig-maar -honest beats completeM SK3maardMSC4 verkeerdMST5 ## "Kan GitHub uitgaven/JIRA-tickets de spec zijn? Absoluut. De spec hoeft geen aparte document te zijn ' Een goed geschreven GitHub-uitgave of JIRA-ticket kan als spec perfect goed dienen. Wat er aan de hand is, is de inhoud. - **Maak een probleemverklaring duidelijk** - Wat lossen we op en waarom? - **Voorgestelde oplossing** - Hoe gaan we het aanpakken? - **Klaardoende criteria** - Spesifieke, toetsbare aanvaardingskritieken - **Omvangsgrenzen** - Wat is in en buiten de scope van 'gebruik labels als "uit-van-scopeM SK6 voor dingen die je expressieel niet doet. - **Open vragen** - Merk deze met een label of iets dergelijks. De voordelen van het gebruik van uitgaven: - **Alles op één plek.** - KodeM SK1 spec, discussie , en taakvolging samen - **Makkelijk koppelen** - Verwysingsbezogene kwesties - **Gebouwd-inversieering** - De geschiedenis van de uitgave beschrijft hoe de behoeften evolueerden. - **Gefaamte werkstromen** - Team weet het al hoe te gebruiken Tips om problemen als specs te gebruiken: - Gebruik de probleembeschrijving voor het spec, niet begraven in opmerkingen (mensen lezen de beschrijvingM SK2 - Dateer de beschrijving op terwijl het spec evolueert ( voeg toe " Redigeer:" delen om veranderingen te laten zien - Gebruik etiketten om de staat te aantonen. - Pin belangrijke spec-discussies zodat ze niet verloren gaan in 100 opmerkingen. - Link naar ondersteunende documenten (diagrammen, mockupsM SK2 als nodig De test: zou iemand het probleem kunnen lezen en weten wat hij moet bouwen, wat "doeM SK3 betekent , en wat' buiten de scope isMSC6 Als ja, , is het een goed spec, ongeacht het formaat. ## "Wat dacht je van specs in gereguleerde industrieën? Als je in de gezondheidszorg bent, ,, financiën, ,, lucht- en ruimtevaart,,, of andere gereguleerde gebieden, ,, dan heb je misschien meer formele specificaties nodig voor conformiteit. - Begin met het probleem. - Definieer duidelijk gedaan. - Evolueer als je leert. - Hou specs nutteloos Maar je zal ook moeten. - Volg de documentatienormen van je industrie'. - Oorweeg de benodigde secties (veiligheidsanalyse, regelgevingsaanvaardingM SK2 audit trails ) - Bevestig een formeel teken, -, waar nodig. - Behou meer gedetailleerde versiegeschiedenis - Hou specs na het einde van het project ( voor audities) Zelfs in gereguleerde omgevingen. # In slotting: Goede eigenschapsspecifieken schrijven in een agile omgeving is een vaardigheid die met de praktijk verbetert.. Het doel is niet perfect specs te schrijven voorhanden. De belangrijkste principes: - **Specs zijn gereedschap, geen contracten.** - Voeg details toe waar je het nodig hebt - **Begin met het probleem, niet de oplossing** - Implementatie komt voort uit het begrijpen van het probleem. - **Collaborate, don't dictaat** - Iedereen helpt bij het verbeteren van de spec - **Definieer "done" duidelijk** - Voorbewaren van eigenschapsmetastase met beton, toetsbare criteria - **Afzonderlijke zaken** - Wat je niet doet is net zo belangrijk als wat je bent. - **Verwacht evolutie** - Funkties veranderen als je ze bouwt; vastleggen dat leren - **Hou specs nutteloos** - Ze worden de basis voor tests, docsM SK2 en toekomstige ontwikkeling. Het moeilijkste deel is:"', niet het eerste spec schrijven, ., het weten wanneer je moet stoppen met werken aan een functie, ., zonder duidelijke criteria. Daarom is het zo moeilijk om 'agile' te schatten.. U' schat niet alleen de implementatietijd, maar ook de leertijd. Het beste wat je kunt doen, is: : duidelijk zijn over wat "doe, " betekent,, tijd,-box oncertainty en het spec opdateer zoals je leert. Een goede spec geeft ontwikkelaars de macht om problemen intelligent op te lossen terwijl ze precies weten wanneer ze kunnen stoppen. Als je een ontwikkelaar bent die een spec leest dat geen zin heeft of geen duidelijke criteria heeft, dan is het beter om het nu te sorteren dan een eigenschap te bouwen die blijft groeien tot het de hele toepassing overneemt.