Inleiding

Under åren har jag läst: "/", skrivet hundratals egenskapernas specifikationer, . , några var lysande och andra fruktansvärda. De flesta var fruktansvärt.." Skillnaden mellan en bra specifikation och en dålig är inte om längd eller formalitet, utan om det verkligen hjälper utvecklare att bygga rätt utan att få dem att bli galna i processen.

Här är något jag lärde mig från Microsoft som förändrade hur jag tänker på specifikationer. En specifikation är inte en bibel. Som vilket verktyg som helst, så använder du det för att få jobbet gjort.1 Du lägger till lika mycket detaljer som du.2 Stakeholderna.3 och utvecklarna behöver komma igång.4 Sedan anpassar du den.5 ändrar den.6 och uppdaterar den så fort funktionen utvecklas.7

Betraktera en specifikation som en helig dokument och du sätter ihop det felaktiga perfekt. (' kör väldigt snabbt i fel riktning, '). Betrakta den som ett levande verktyg och du ' sätter upp något som faktiskt löser problem

Den här agilla tillvägagångssätten till specifikationer skapar en särskild utmaning : om egenskaperna kan utvecklas när du lär dig dem, hur fan ska du bedöma det?

I allmänhet är det en princip som jag har levt i min karriär.;. Alla processer, oavsett om de är specifikationer. /. Att fylla i rapporter.

I grunden är en egenskap Spec ett konversationsverktyg för att göra egenskapen bättre, inte en dogmatisk egenskap

Varför Agile ( och vad det egentligen betyder

Agile är "’t stand, -' -anteckningar och klibbiga grejer. ekonomisk strategi för att bygga på det rätta under osäkerheten. Speker lever inuti den osäkerheten , så de måste vara agiler också . läsa Agile Manifesto, låt det bli hur du tänker på att bygga ALLES ♫ ♫ . ♫ Tänk på det som ett designmönster för produktutveckling ♫

Första principerna

Variationen är standardinställningen, inte undantaget. Markerna rör sig, användarna överraskar dig, beroenden slippar, . Spec som kan, ’, inte vara flexibel blir fiktion.
Att lära sig slår förutsäga. Du upptäcker de riktiga kraven först när människor rör vid sakerna. Agile gör lärande billigt och snabbt.
Flow over heroics. Små, kontinuerliga rörelser slå stora , sällsynta M SK2 storslagna ” fall

Ekonomin. Varför sparar det pengar?

Minimeera kostnaden för att vara felaktig Korta cyklar + lättviktiga specifikationer innebär att dåliga idéer dör snabbt istället för efter sex veckors byggande
Fördröjning av oundvikliga beslut. Håll möjligheterna öppna fram till den sista ansvariga punkten; lovar när informationen är den största och risken den minstaM SK1
Reda uppsättningen. Hälften, -, skrivna epiker och massiva sektioner, “, framtida ”, är arbete.

Feedback-loop är produkten

Varje kretsling kortar avståndet mellan “idea” och “användbarM SK3

Spec ⇄ Dev: att fånga omöjligheter innan koden cementerar dem.
Dev ⇄ QAM SK1 omvandla acceptanskriterien till utförbara kontroller.
Inre föda ⇄ Användare : bevisa att det löser ett riktigt problem

uppdatera specifikationen efter varje kretslopp. Veranderingenslog är berättelsen om vad du lärde dig.

Vad gör en bra dragspecifik

Problemet-lösningsmönster

Det viktigaste principet för att skriva specifikationer: Börja alltid med problemet, inte lösningen

Detta mönster är enkelt:

Problemet - Vad är det som är riktigt dåligt på ', vad är smärtan som användaren upplever, och vad är möjligheten den skulle skapa
Lösningen - Här är vad vi föreslår att fixa det. / utnyttjar den möjligheten
I scope - Vad vi gör i den här specifikationen
Utan omfattning - Vad vi m.in. gör inte ', m.i.n. gör , som är lika viktigt, ;, får in i framtidens planering och hindrar

Kom ihåg att utvecklare är verkliga byggnadsmaskiner. Verkligen. (kod är verktyget för att leverera egenskaper behöver göra Inte hur man gör det, men om du har en UX-person som är ansvarig för UX: s specifikation så borde dev och dem arbeta tillsammans. för användaren som kan förändras, och vem som helst har makten att pressa för förändringen i specifikationen, ), och få den omvärderingsprocessen att testa idén.

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

Uppenbarhet av syfte

Innan du skriver ett enda ord om implementering, måste du svara på en fråga. Varför?

Varför bygger vi den här?

En bra spec börjar med:

Problemets uttalande - Vad
Användarens påverkan - Vem bryr sig och varför?
Framgångskriterien - Hur vet vi att vi löser det?
Inte - Vad gör vi inte uppenbarligen

Den rätta nivån av detaljer

Det är här som de flesta specifikationer går till.

Tricket är att specifyra THAT måste ske utan att prescribira Hur det händer. Till exempel

Bra: ♫ " ♫ När en användare försöker skicka ett Formular med ofullständiga data ♫ should de få omedelbart feedback som visar vilka fält som behöver korrigeras ♫

Dålig: " När man lägger upp ett Formular, så ska den skicka-knappenM SK3s påKlickbehandlaren klocka validateFormetMska4 som upprepar sig genom formFelds rutnätet som kontrollerar varje fältMka5värde mot dess valideringMkka6regex egenskap och om något misslyckas klockar showErrorM Ska7 med fältet Mska8 namn och validering

Den första talar om för mig vad användarupplevelsen borde vara; Jag kan implementera den i React, Vue , vanilla JavaScriptMska3 eller bärbar duva för allt det som spelar rollMske4 Den andra antar implementeringsdetailer som kan vara helt fel för teknikskivan eller introducera onödiga begränsningarM Ska5 Skillnade människor har olika styrkor ofta är personen som skriver specifikationen inte den person som är gjord som gjord.

## Använd bilder / flowcharts ; Ta punkten över

Kom ihåg att du, ', försöker få folk att förstå vad du föreslår. för att du ska bli förstådd. Använd alla verktyg du behöver

I en Wiki sjöjungfru är diagrammet GREAT för detta! ; kom ihåg att AI är jättebra på att generera dessa också med en textbeschreibung

Vissa människor kan analysera skrivnabeskrivningar , vissa behöver bilder och filmer!

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]

Randfall och felbehandling

Om det finns en sak som jag har lärt mig, Användare hittar sätt att bryta din skit som du aldrig hade föreställt dig

En bra specifikation beskriver inte bara den lyckliga vägen, den tar hänsyn till

Vad händer när nätverket misslyckas i mitten?
Tänk om användaren inte har några rättigheter?
Vad sägs om samtida förändringar?
Hur hanterar vi partiella misslyckanden i fördelade operationer?

Du behöver inte lösa alla dessa i specifikationen, men du måste erkänna att de existerar. Nothing irritates developers more than discovering halfway through implementation that nobody thought about what happens when the external API is down

För MANYK är det troligt att de inte är relevanta för den här specifikationen.

säkerhets- och effektivitetsbegränsningar

Dessa bör inte vara efterthoughts i kodbevakning... Om det finns specifika säkerhetsbehov, (, autentiseringsnivåer ,, data-enkriptioner ,, audit-loggning

På samma sätt, om det finns drivkraftsbegränsningar som spelar roll ("Det här söket måste göras under 200 ms för datamängder med upp till МSK3 miljoner rekord M SK4 lägga dem i spec

Strukturen av en bra art

Här är templaten som jag använder för egenskaperna.

1. Übersicht

Ett eller två paragrafer som summerar vad vi bygger och varför det är viktigt. Din VD borde kunna läsa just den här sektionen och förstå värdet.

2. bakgrund

Vad' är den nuvarande situationen ? Vad som fick igång den här funktionen ? Vad har användaren frågat efter M SK3 Vad skulle hjälpa oss tjäna mer pengar MSC4 Det hjälper utvecklare att förstå problemet utan att ha varit på varje produktmöte

Got it—let’s expand your section on Användarhistorier med persons woven in , så det är inte bara en kontrolllista utan en levande karta över hur olika typer av användare interagerar med systemet.

3. Användarberättelser

Användarhistorier är inte bara en låda, de är ett sätt att omkroppsliga riktiga människor och deras mål hela poängen med att bygga den här skiten. Genom att ankar varje berättelse till en person, tvingar du dig tänka på faktiska beteendemönster, motivationer och begränsningar. Formatet är enkelt men kraftfullt.

I slutändan är personer ett välsignat sätt att identifiera hur din mjukvara kan tjäna olika typer av användare. Kanske behöver Alex en datapanel för att se sicherheitsfrågorna i din egenskap, kanske behöver Morgan sina tillstånd begränsade för att stoppa honom från att bryta skräp etc

Som en [person / typ av användare] jag vill [att göra något [Jag har nått ett mål

Den “ så att klauzula är skyddet mot byggande drag som ingen behöver

exempel Personas

Alex Administratoren – bryr sig om kontroll
Jamie den vardagliga användaren – värderar enkelhet och snabba vinster
Priya den kraftfulla användaren – pressar systemet till sin gränser , vill utvecklas
Morgan den nykomman – behöver vägledning , an Bordbording M SK2 och säkerhetsåtgärden .
Taylor som intressenter – använder inte systemet dagligen, men behöver synbarhet i resultat

Till exempel användarberättelser

Persona	Historien	Varför är det viktigt
Alex (Administrator Administrator, Jag vill ge mig roller och rättigheter så att Jag kan se till att datasäkerhet och -observation sker.
Jamie Vanligt användare, Jag vill ha ett enkelt dashboard så att Jag kan snabbt se den viktigaste informationen utan att bli överväldigad.
Priya (Stromanvändare Leistungsanvändare, Jag vill skapa egna arbetsflöden så att Jag kan automatisera repetitiva uppgifter och spara tid
Morgan Nykomman, Jag vill ha guidade instruktioner och verktygstips så att Jag kan lära mig systemet utan att känna att jag förlorar mig.
Taylor Stakeholder, Jag vill ha regelbundet rapporter e-postade till mig så att Jag kan följa framsteg utan att logga in

Varför Personas + berättelser fungerar tillsammans

Personer humanisera abstraktionen Istället för “, användare , ",”, du tänker på Alex, ,, Jamie och Priya, M SK5, Morgan och Taylor.
Historier kopplar egenskaper till mål Clausen "“", så att varje egenskap ska tjäna sitt syfte .
Patroner dyker upp. När du lägger upp flera berättelser, ser du överlappar, konflikter och prioriteringar mellan personer.

4. detaljerade krav

Det här är din kött och potatis.

För varje krav, specifikera

Det förväntade beteendet
Alla begränsningar eller valideringsregler
Błędbehandlingsbehov
Hur det interagerar med existerande egenskaper

5. icke-Funktionala krav

Leistungsmålen, säkerhetsanforderungerM SK1 tillgänglighetsstandarder , webblader/ utrustningen supportar . Antag inte att de är uppenbara. Men i vissa lag kan det vara ALLE andra lag, men antag inte, ' tappa fokus,. Om en del av din cykel blir ett vattenfall så har du, M SK10, förlorat agility per definition.

6. ute ur volymen

Denna sektion är precis lika viktig som vad

Varför är detta viktigt:

Försämrar scopekreep - " Men skulle vi inte kunna, ' skulle vi bara, ..." konversationer dö snabbt när man kan peka till "" Out of Scope "" -sektionen
ställer upp förväntningar - Stakeholder vet vad won't levereras (den här gången )
Aktiverar framtida arbete - Artiklar här kan bli sina egna specifikationer senare
Fokuserar teamet - Alla känner till gränserna för det här arbetet

exempel på bra Avlägsna föremål:

"Mobilt stöd ( kommer att adresseras i separat specifikation
"Migration av existerande data (aktuelle specifikation hanterar bara nya data M SK2
"Admin UI för konfiguration ( kommer att använda konfigurationsfiler i början
"Integration med System X ( beroende ännu inte tillgängligt

Om någon hävdar att en sak utanför - av - borde vara inom , så är ' ett samtal som är värt att ha innan utvecklingen börjar , inte halvvägs genom att implementera .

7. öppna frågor

Var ärlig om vad du inte vet.. Markera dessa tydligt och se till att de får svaret innan utvecklingen börjar.. Nothing worse than blocking development because nobody decided whether we

8. beroenden

Vilka andra system som krävs för att kunna utvecklas? What other systems/teams/features does this rely onM SK2 What needs to be ready before development can start

9. acceptanskriterien

Hur kommer QA att testa detta? ?. Dessa ska vara konkreta. ,. Testbara deklarationer, .. Bonuspoäng om de är skrivna i en format som skulle kunna bli automatiserade tester.

Problemet med Spec-bugs

Här är något som inte pratas tillräckligt om. Spec kan ha bugs också.

En specifikation är när specifikationen själv är felaktig... Kanske motsäger den sig själv, ,. Eller så specifikerar den beteendet som är tekniskt omöjligt.,. eller så löser den felaktiga problemet helt.M SK4. Dessa är bedrägeriska eftersom utvecklare kan implementera exakt det som ' skriver och ändå få fram ett produkt som inte fungerar.

Hur Spec-bugs händer

Ofullständig förståelse - Personen som skrev specifikationen förstod inte riktigt problemet eller det existerande systemet
Konflikerande krav - Olika intressenter vill ha olika saker och ingen löste konflikten
Teknik omöjlighet - Spektionen frågar om något som inte kan göras i verkligheten
Att ändra krav - Världen gick vidare men specifikationen blev inte uppdaterad

Att hantera spec-bugs

När du hittar en specifik bug som utvecklare

Option 1: lyfta upp den omedelbart

Det här är nästan alltid det rätta svaret.

skicka ett tydligt meddelande till den som äger specifikationen:

Vad sägs i specifikationen
Varför är det problematiskt?
Vad du tror ska hända istället? (om du har ett förslag

Gör det här på skrivandet. (email, ,biljett, ,, vad som helst, M SK3, så där är ', ett rekord

Option 2: Implementera det hursomhelst

Ibland är det frestande att bara bygga vad som är specifikerat, även om du vet det. DON 'T DO THIS.

Jag har sett utvecklare implementera specifikationer som de visste var felaktiga eftersom QA avfärdar dem eller användare klagar på dem. Du är en yrkesman, det är en del av ditt jobb att tala upp när du ser problem,

Den undantag är om du' har tagit upp frågan, fått höra att gå vidare på något vis , och fick det(n) på skrivar(n).. Då är det okej(n), ;, du(n)' har gjort din rättvisa åtgärd (du due diligence)

Option 3: Fix It Yourself

Om du är övertygad om att du vet vad specifikationen ska säga, så kanske du blir besatt av att bara korrigera den själv. Detta är bra för uppenbara typo- eller formateringsproblem, men när det gäller substantiva förändringar måste du få överenskommelse från intressenter.

Ska aldrig tyst ändra krav.

Att förhindra Specific bugs

Det bästa tillvägagångssättet är att förhindra specifik bugs på första plats:

Att involvera utvecklare tidigt - Ta teknisk överprüfung av specifikationer innan de är färdiga '
Ingripa QA tidigt - Om det inte går att testa, kan det inte göras, kan den inte byggas, ,, ditt jobb är att göra något som gör det möjligt för användaren.
Använd exempel fritt - Abstraktivbeschreibunger är lätta att missförstå
Validatera mot det existerande systemet - gör specifikationen antaganden om hur saker fungerar för tillfället?
Itera på specifika - Behandla specifikationen som ett levande dokument . Då du lär dig mer under implementeringen M SK2 uppdatera den . Framtidens utvecklare kommer att tacka

vanliga fall

Novelen-Längd Spec

Vissa människor tror att mer detaljer är alltid bättre.

Om din spec omvandlas till krig och fred

Man måste bryta upp det i flera egenskaper.
Spekifierar implementeringsdetails som borde lämnas till utvecklare
löser fel problem och behöver ta ett steg tillbaka

Den vaga handvågen

Det motsatta problemet.

Om din specifikation kan fångas helt i en enda mening

Lösningen-First Spec

"Vi behöver en brädan, " är det? '? Nej, det är ett krav. ;? Det är en förutfattad lösning. .? Kanske behöver du en bänkbräda, ,? Men kanske behöver du något helt annat. M SK7? Börja med problemet.

Den rörande målet

De krav som förändras dagligen är: 't krav, ;; de är kaos. . Om saker förändras så snabbt, ,, så förstår du inte problemet tillräckligt nog..; stanna upp och göra fler upptäckter innan du skriver specifikationer.

köksbänken

" Medan vi ' är där i, skulle vi kunna göra det också ..." Nej, . Nej. Vi kunde inte göra det.

Att behandla arter som källkod

Det här är mindsets förändring som ändrade hur jag skriver specifikationer Tretera din specifikation precis som du behandlar källkod.

Versionskontroll

Din specifikation borde finnas under versionskontroll tillsammans med din kod. kolla dem i. spåra ändringar . skriva meningsfulla kommando meddelanden när du uppdaterar demM SK3 Det här skapar en historia av hur krav har utvecklats

På Microsoft ställde vi specifikationer i samma arkiv som kod.. När en specifikation ändrades, gick den igenom samma provprocess som kod, . Det här var ingen "'", det var ingen byråkrati och ; Det var för att alla skulle förstå vad som förändrades och varför.. Till och med att följa redigeringen i Word är bättre än ingenting.

Refaktorisering av specifikationer

Precis som kod behöver göras om igen , så gör också specifikationer. När du lär dig mer under implementeringen, ska specifikationerna utvecklas för att reflektera det lärande

Mötte ett bättre sätt att lösa problemet? uppdatera specifikationen för att reflektera den nya ansatsen och förklara varför du ändrade riktning . upptäckte en randfall du inte hade tänkt på ' inte tänkt på

Specen efter utveckling borde vara mer raffinerad än den innan utvecklingen.

Levande dokumentets princip

En specifikation är "'t "", " , "" gjort "". "," när utvecklingen börjar "".

Detta betyder inte att specifikationen ska ändras varje dag.

Tänk på det så här.

Varför Speker behöver vara aktuella

Här är något som inte blir tillräckligt diskuterat. din specifikation blir grunden för allt som kommer efter.

Dokumentation: Användardokumentationen , API-docs , hjälpsystemet M SK3 din fantastiska RAG AI-stödjare agentur | - | de börjar alla från specifikationen |. | Om specifikationerna beskriver egenskaper som inte finns | МSK6 | existerar inte eller missar egenskaper som gör |

Framtidens utveckling: När någon måste utöka funktionen sex månader senare , så läser de ' specifikationen för att förstå hur den fungerar . Om det inte matchar verkligheten, så börjar de med felaktiga antaganden

Påbord: Nya gruppmedlemmar lär sig systemet delvis genom att läsa specifikationer

Det är därför specifikationen måste vara aktuell.

På Microsoft så behandlade vi specifikationsaktualiseringar med samma betydelse som kodaktualiseringer... Spekförändringarna gick igenom undersökningen... De var versionerade tillsammans med kod.

Om du ändrar koden men inte uppdaterar specifikationen, så har du skapat TECHNICAL DEBT. Framtidens arbete kommer vara långsammare eftersom ingen vet vad den nuvarande tillståndet faktiskt är.

# Attityden mellan specifikation och implementation

Här är något som unga utvecklare ofta inte förstår. Spektionen är inte källan till sanningen.

Specen berättar för dig vad du ska bygga.

Detta betyder:

Specer borde utvecklas - När du upptäcker saker under implementeringen , uppdatera specifikationen. Den M SK3s dokumentation av vad du är på väg att bygga
Implementeringsdetails Don't ingår i Specs - När du ♫ ' ♫ har börjat implementera ♫, ♫ dokumenterar koden i sig själv hur | ♫ på vissa ställen en ♫ МSK4 ♫ teknisk specifikation ♫ ' ♫ men dessa är sällsynta och ofta ett produkt av otäckt ♫
Testar att överbrygga klyftan - Bra tester bekräftar att implementeringen matchar kraven . De

Att skriva specifikationer för olika publiker

Olika människor behöver olika saker från specifikationer:

Executives - Vill veta affärsvärdet och den grova tidsramen . Ge dem överblick och framgångskriterien

Produktchefer - Man måste förstå hur det passar in i den bredare produktstrategin och strategikartan

Developers - De behöver tillräckligt med detaljer för att kunna implementera korrekt utan att bli tillsagda hur de ska göra sitt jobb . Ge dem kraven

QA - De måste veta hur de ska kontrollera att det fungerar . Ge dem acceptanskriterien

Designers - Bra att veta vad användarupplevelsen borde vara. Ge dem användarhistorier och interaktionsflödenM SK2 Ännu bättre att de utvecklar en UX-spec | /| historiebord parallellt medan de arbetar med dev |& | spec skrivare |; | var det PM | МSK6 | BA etc | . | Vem skriver spec är mindre viktigt än att göra slutdelen bättre |

En bra specifikation tjänar alla dessa publiker utan att bli blödad.. Använd sektioner och struktur så att folk kan läsa vad som är viktigt för dem.

Testa din spec

Innan du ropar på en specifikation är det klart, fråga dig själv

Kan en utvecklare som aldrig sett denna egenskap bygga den från den här specifikationen? Om det inte är så, så är du: ,, ', du saknar detaljer.., du har aldrig delar som: ', det här fungerar som en egenskap x i den vanliga systemet. '., det första är: ', den lata AF, ,, det andra: ,, den egenskapen kan förändras eller det är svårt att förstå marginalfall.
Kan QA skriva testfall från denna specifikation? Om inte, så är dina acceptanskriterien inte
Kan du bygga något helt värdelöst som fortfarande matchar den här specifikationen? Om det är så, har du inte fångat de faktiska kraven ordentligt
Beskriver denna specifikation hur man ska implementera eller vad man ska åstadkomma? Om det är "'", det formera, ",", så är du "'", micromanaging , och МSK3 .

Agil-metoden mot arter

" Men vi, ', är agil, !, Vi behöver inga specifikationer. !" Jag hör det en hel del.

"" Agile "" betyder inte "'", utan att planera, " eller ", utan dokumentation. ." Det betyder att reagera på förändringar genom att följa en plan. specifikationer är verktyg, inte kontrakt Man skapar dem med tillräckligt många detaljer för att börja.

Hur agilla arter skiljer sig från Waterfall

Den grundläggande skillnaden är format eller längd

Waterfall Specs:

Den är skriven helt framifrån innan någon utveckling
Att sträva efter fullständighet från första dagen
ändringar kräver formella processer för förändringskontroll
Specen är "locked" när den har apstiprināts
Antagandet: vi kan veta allt innan vi börjar
Linjärt: Spec M SK1 bygga → testa → sätta igång

Agil Spes:

Börja med minimalt hållbart detaljerat för att börja
Förvända ofullständighet vid början ( och att ' är bra
Vi förväntar oss och välkomnar förändringar
Spec utvecklas kontinuerligt med egenskapen
Antagandet att vi ska lära oss medan vi bygger
Cycliska: Tecknall → bygga → lära sig | → uppdatera specifikationen |→ bygga mer | МSK5 lära dig mer

Waterfall-metoden antar att du kan specifikera allting perfekt innan du skriver en rad kod.., det är en underbar fantasi.., i verkligheten upptäcker du hälften av kraven när användaren verkligen prövar funktionen, ., planerar för det, ,, omfamnar det,., användaren är ULTIMATE-tester, M SK7, de kan bryta skit som du inte gjorde, MSC8, du vet inte ens vad du gör, MST9, skapat med en hastighet som verkar bryta orsakssambandet.MST10, förvänta dig det, MSST11, planera det,MSST12, skriva in och fixa det, SST13, och lägga till det till en framtida specifikation.

## Feedback-loop är allt

I agile specifikeringar, feedback loops är din bästa vän. Du 'samlar hela tiden inmatningar och uppdaterar specifikationen

Utformarens Feedback: "Initiell tillvägagångssättet vann, ' inte fungerade på grund av X, IM SK4 jag föreslår att göra Y istället,." | → | uppdatera specifikationen för att reflektera den nya tillvägangångsviisin och varför den ändrades,. | I slutändan är du ♪ ' ♪ ALWAYS den första ♪' ♪ användaren ♪

User Feedback: Försök funktionen med riktiga användare. ♫ ( ♫ även internt ♫ Pivot specifikationen baserat på vad du lär dig

Implementering Feedback: När du bygger , upptäcker du randskador , tekniska begränsningar M SK3 eller bättre angreppssätt

QA-feedback: ♫ " ♫ Specen säger X men inte tänk på Y-scenariot ♫ ♫

Var och en av dessa återkopplingsloopar gör spetsen bättre.

Det är därför vattenfallspeckor ofta misslyckas.

"En stor sak," ,, " feedback som är lika lätt att förstå." "It is why I built" LLMApi det hjälper dig att bygga ett BIT och sedan använda falska data för att få hjälpfull feedback.

Omfamna ofullständighet (

Här är något som gör traditionella projektledare nervösa. det' är helt okej om den första specifikationen har luckor

Markera sektioner som "TBD

Det här är inte "'", det är inte slämthet, ; det är "'", ärligt talat, . Du vet inte allt från början, M SK4 Vet du inte allt - . Att påstå att du gör det betyder bara du , ' och skriver självsäkra specifikationer för fellösningen.

Börja med:

Klara problembelägget ( du måste veta det här )
Försökt tillvägagångssätt (möjlig förändring
grova " gjort " bedömande | ( | kommer raffineras
Vetenskapna okända markerade som öppna frågor

Så fylla i luckorna när du lär dig.

Specen kommer att ändras

Acceptera detta nu: din specifikation förändras under utvecklingen. Om det inte gör det, så har du antingen väldigt tur eller du har inte lärt dig någonting.

ändringar du borde förvänta dig:

Tekniken skiftar när man upptäcker begränsningar
Sakjusteringar när du inser att du bygger för mycket ( eller för lite
"Filter " kriterierna eftersom du förstår problemet bättre
Nya gränsfall upptäckts under implementering
Bättre lösningar hittat genom experiment

Varje förändring bör vara:

Dokumenterad - uppdatera specifikationen , inte modifiera koden
Kommunikat - Berätta för inblandade vad som ändrats och varför
Begrundat - Berätta vad du lärde dig som ledde till förändringen

Spektionens versionshistoria blir en dokumentation av vad du lärde dig.

När Agile Speccing går fel

Agil-metoden kan misslyckas om du glömmer en viktig sak " kommer att ändras " inte, ' betyder inte

Dålig agilla spectering:

Spec-förändringar varje dag utan någon tydlig anledning
Det finns ingen definition av "done
Förändringarna är inte kommunicerade. Spekuppdateringarna ska hoppa direkt till dina kollegors hjärnor.
"Agile" användes som ursäkt för att inte tänka igenom saker
Stakeholder överraskade av omfattningsförändringar eftersom ingen sa till dem

Bra agilerspecsering:

ändringar händer av tydliga anledningar baserat på lärande
"DoneM SK1 är tydliga även om andra detaljer inte är
ändringar diskuteras och dokumenterade
Att vara agil betyder inte att man är sluppig
Stakeholder är del av feedback-loopet

Specen är ett levande dokument, men den är inte kaos. Den utvecklas baserat på lärande och inte på nycker.

älsklingen gör aldrig vad du vill och kallar det .

Det är en dynamisk process som har SOLE GOALt att bygga de bästa sakerna så snabbt som möjligt. Agile Manifesto säger ', första principen , .

" Vår högsta prioritet är att tillfredsställa kunden genom tidig och kontinuerlig levereration av värdefull mjukvara."

Det är inte att skämta runt med att spinna ut kod eftersom du gillar känslan.

Bara tillräckligt med detaljer för att börja

Frågan är: "" Hur detaljerad ska specifikationen vara? "" "?"", "" What do we need to know to start building confidently? "",

För vissa egenskaper som kan vara:

En punkt som beskriver problemet
Tre skyttpunkter som skissar lösningen
En tydlig definition av hur "done" ser ut

För andra kan det vara:

detaljerade användarströmmar med modeller
Förmågor som stöds av data
Integreringsspesifikationer för flera system

Lägg till detaljer där det finns osäkerhet. Om alla håller med om hur något ska fungera, så måste du inte skriva ner det i fruktansvärda detaljer.

Men i slutändan finns det tillräckligt med detaljer för att starta återkopplingsloopet.

## Templates och AI: Att börja snabbt

Tänk inte över det första specifikationen.

En grov uppskattning ( till och med en SWAG
Input för prioriteringsdiskussioner
Bara tillräckligt för dig personligen att börja koda

Använda Templates: Att ha en enkel szablon med de viktigaste sektionerna | ( | Problemet |, | Lösningen

En enkel template kan vara:

# [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
-
-

Det är det. Fem minuter med att fylla i och du har tillräckligt för att börja diskutera eller till och med bygga.

Att använda AI för att rita specifikationer: verktyg som Claude eller ChatGPT kan vara lysande för att få en första ritning

Men - och detta är kritiskt - Låt inte AIs noggrannhet locka dig att lägga till allt

AI älskar att vara utgripande. Det ' ger dig sektioner om säkerhetsbekymmern, LeistungsanforderungerMST3 tillgänglighetMstd.4 internationaliseringM st.5 felhanteringMstr.6 inlogningMt.7 övervakningMtt.8 utplaceringstrategyMSt.9 rollback-plänarMts.10 och sjutton andra saker du kanske behöverMs.11 slutligenM s.12

Ta bort merparten av det där. Säga vad du behöver nu. Resten kan läggas till senare när du faktiskt behöver den

Tänk på AI: s genererade specifikationer som ett menu. .. Välj de bitar som är viktiga för att börja.

Målet är att "'" inte är en komplett specifikation, ";", det är en specifikation som är tillräckligt för att börja jobba. "." oavsett om det är ett snabbt uppskattande МSK5 , ett beslut om prioriteten , , eller bara tydlighet i vad du - bygger för dig själv .

Samarbetsmodellen

Här är vad som ändras på agile Du skriver inte en specifikation och kastar den över väggen till utvecklare. Specen är ett samarbete.

Den bästa tillvägagångssättet jag sett

Produkt/PM skissar problemet - Vad behöver lösas och varför
Att utvecklare bidrar med en teknisk metod - Hur kan vi lösa det?
Designers bidrar med UX krav - Vad användarupplevelsen borde vara
QA bidrar med testscenarior - Randfall och valideringsmetoder

Alla bidrar till specifikationen.0 Ingen äger den exklusivt.1 Den här kollaborativa metoden fångar problem tidigt när de är billiga att reparera, snarare än sent när dom är dyra.4

Än viktigare, det betyder att specifikationen speglar vad som faktiskt är möjligt, inte vad någon vill ha i isolering.

Evolution under utveckling

Här' där agilla specifikationer skiljer sig från traditionella funktionen kan utvecklas när du bygger den.

Du upptäcker att din initiala angångssätt kommer att fungera' inte ? uppdatera specifikationen för att återspegla den nya ansatsen

Du prövar funktionen och inser att den inte löser problemet.

Användarens feedback visar på en bättre lösning? Inkorporera den och förklara förändringen

Den här evolutionen är en egenskap, inte en bug. Du reagerar på nya informationer. Specen borde fånga in lärandet, inte låtsas att du hade perfekt kunskap från första dagen.

Men detta skapar ett problem, om funktionen kan ändras. Hur räknar man ut det? Hur vet man när det är klart?

Utmaningen för uppskattning

Detta är den smutsiga hemligheten hos agile: uppskattning är hemskt svårt när egenskaper kan utvecklas

Den traditionella uppskattningen antar att du vet vad du bygger.

Agile beräkningar erkänner att du inte har något.

Du uppskattar intervall, inte absoluter . Istället för att svara """, så tar det "3" veckor, """, säger du "" МSK3 "", någonstans mellan "" LKS4 "" och "" lKS5 "", beroende på vad vi upptäcker.

Du uppskattar i repetitioner. " Vi ' spenderar en sprint med att utforska det här och rapporterar om vad vi lärt oss.

Du lägger tid på boxen i stället för scopen " Vi ' spenderar 2 veckor på det här ♫ . ♫ I slutet av ♫ 2 ♫ veckor har vi ♫' ♫ den bästa versionen vi kan bygga under den tiden ♫

Men alla dessa tillvägagångssätt har ett kritiskt krav du behöver veta vad Utan en klar definition av gjort, kan en egenskap fortsätta att metastasera för alltid.

Det är en vanlig kritik på Agile jämfört med Waterfall-metoder. Utan en konkret specifikation kan det inte finnas bra uppskattningar.

Definiera "Ansluta" ( Eller hur man stoppar funktionsmetastasenM SK3

Det är här som många agil-specer går sönder.. Alla är upphetsade över flexibilitet och repetition, , men ingen vill vara den som säger: "" ", rätt? ,, det är ', vi har gjort det.

Utan en klar definition av "" gjort "".Fektioner som inte är färdiga.Fektionerna som inte slutar.Fectioner som sprider sig till andra delar av systemet.Feaktioner som växer till andra del av systemet." Innan du känner igen det, ",", så har din "" ." "" -simple comment system "" omvandlats till ett komplettt socialt nätverk med meddelanden.

Problemet med vag "Done"

I' har sett specifikationer med acceptanskriterien som

"User kan kommentera meddelanden
"Dashboarden visar relevant information
"sökningen fungerar bra"

Det här är definitioner av "" gjort "". De är vaga strävan. Vad betyder "" relevant information ""? Vad innebär """?

Den utvecklaren behöver veta: vad som betyder att jag kan sluta arbeta med den här funktionen?

Att skriva konkreta "Ansökt" Kriterier

Bra Kriterier är:

Testbar - Du kan kontrollera om det
Spesifika - Inga vaga ord som "bra" eller
Avgränsad - De betyder inte

Dålig: "Comments should be moderatedM SK2 Bra: "Admin-användare kan godkänna, avfärdaM SK3 eller radera kommentarer från administrationspanelenMSC4 OtrevligMska5 de bekräftade kommentarerna är inte synliga för vanliga användareMske6 E-postmeddelanden skickat till administrationen när en ny kommentar är publiceradM Ska7

Dålig: "sökningen borde vara snabbM SK2 Bra: "sökningen återvänder resultat inom ♫ 200 ms för ♫95 fjärde procentil av queryer mot en datamängd av ♫

Dålig: "Taskbord visar användbara mätvärdenM SK2 Bra: "Dashboard-displays: totala sidoruppfattningar | ( | sista | 30 | dagar | МSK5 | unika besöker |( | slutna | мSK7 | dagarna |), | högst upp ♫ 5 | poster efter synpunkter | ( | senaste | 7 |dagar |), | och Besucherfördelning efter länder | SSK13 | Allt mätdata uppdateras en gång per timme

Notera skillnaden? De bra exemplen berättar precis vad som behöver finnas och när man kan sluta lägga till saker

Det utanför ramen är din vän

Kom ihåg att jag tidigare sa att Out of Scope -sektionen är lika viktig som vad "'" är inom området.

För varje egenskap finns det du kanske kan lägga till dussintals saker.

I scope: Inbyggda kommentarer (en nivå av svar Utan omfattning: Oändlig kommentarervärldning , kommentarerröstning, kommentarervärgning, bästa sortering av kommentarerM SK4 kommentarer permalinks | ( | dessa kan komma senare som separata egenskaper

Nu när någon föreslår "" " shouldn , "' doesn 't have upvotes,?, kan man peka på specifikationen och säga """, att "" МSK4 "" är bortom ramen för den här upprepningen. ".". Låt oss diskutera det som en separat egenskap när de grundläggande kommentarerna fungerar

Och den kommande specifikationen? Ja, du har ett antal oanvända bra idéer redan fångade

Time-Boxing as a Last Resort

Ibland kan man inte riktigt veta hur det ser ut när man börjar.

" Vi ' spenderar 2 veckor ( eller tills backend är redo ) att göra prototyper av olika tillvägagångssätt för beveelningsalgoritmen mska5 I slutet av 2 veckor kommer vi mske7 att bedöma vad vi har lärt oss och bestämma om vi ska tillverka en tillvägangångspunkt, mska9 pröva något annat, , eller överge den egenskapen.

Men lägg märke till att du fortfarande har en betong. " gör det, " tillstånd. ♫ (2 ♫ veckor, M SK4 ♫ sedan utvärdera, ). ♫ Du är inte bara uppbyggande i oändlig tid. ♪ . ♫ Dessa utforskningar görs ofta i ett sammanhang som en "" Sprint "" i SCRUM som kallas "'".

Spikes & Sprints.

En Spike är en av dessa. ' låt oss leka och ta reda på den här tekniken. ♫ ' ♫ kan hålla kvar så länge som en Sprint ♫( ♫ eller längre ♫

Ett Sprint förväntas ha levererade i slutet ( något som någon annan än personen som är inblandad i det kan testa för kretsloppet ). Ett Spike skulle kunna ha men det enda som troligen kan levereras är kunskapen för teamet

De ' är också kul för ingenjörer och hjälper teamet Jag samlar ofta Spike idéer under ett projekt, och när det finns en paus så låter jag ingenjörerna välja en för att utforska. (användbart för någon framtida ingenjör men ofta bara för att stoppa Jim, den unga ingenjören KEEP GOING ON ABOUT IT.

Förebygga scopekripp under utvecklingen

Dokumentera det. När du upptäcker något nytt som behöver lägga till , uppdatera specifikationen. Erkänna tydligt att scopen har ändratsM SK2 få överenskommelse från intressenter.

Detta tjänar två syften

Osynlighet - Alla vet att skalan har ändrats och varför
Kustmedvetenhet - Stakeholder ser att sakernas addition påverkar tidsramen

Om din specifikation fortsätter att växa, så är det så att: ' är en signal. . antingen bygger du fel, ' och måste ta ett steg tillbaka och tänka om igen.), eller så borde det vara flera olika egenskaper., eller så måste du skära ner ditt utrymme för att skicka något användbart tidigare.

När det ska hända

Vid någon tidpunkt

Ett bra test: Kan användare få nytta av den här funktionen som den är?

Om ja , skicka det. Du kan alltid upprepa i nästa version

Om nej , så är du' inte färdigt än, oavsett vad din specifikation säger

Den svåraste delen av agility är: "'t startar arbetet, ;' s, det är ' 's slutar arbetet. .' s Klara kriterierna gör det möjligt att sluta.

Men kom ihåg att man måste räkna ut om man ska släppa den till alla.,, ha en nära grupp för A, /, B, /, UAT och (, användaracceptanstestning.

# Spec-reviewprocessen

En specifikation är inte gjord när du avslutar skrivandet.

Treat Spec Reviews som Code Reviews

Den bästa praxis jag lärde mig på Microsoft: specifika recensioner fungerar precis som kodbewertningar. De är samarbetande, inte motstridiga, fast Microsofts pojkarklubb, ', ofta gjorde att spec-reviewerna kändes som gladiatoriska strider om någon var en fan.

När man tittar på specifikationer:

Fråga frågor "" Vad händer om X uppstår? "" "?"" är det inte "" criticism ""
Suggest alternativ - "Har du tänkt på Y-metoden?
Se på saknade fall - "Det här gör inte detM SK2 inte täcker Z-scenariot" hjälper till att komplettera bilden
Utmanande antaganden "Why are we solving it this way" ( Varför löser vi det på detta sätt) ?" kan avslöja bättre lösningar

När din specifikation undersöks:

Frågor är möjligheter De avslöjar vad som är oklar och vad du har missat.
Suggestioner förbättrar specifikationen - Betänk dem seriöst även om du inte accepterar dem alla
Det är inte personligt - likt kodbevakning , det är ♫ ' ♫ om att göra arbetet bättre ♪ , ♫ utan att attackera dig
Kritikern kan ha fel - Berätta varför ditt tillvägagångssätt är vettigt

De bästa specbeteckningarna är konversationer.

Vem borde överväga

få betyg från alla perspektiv som är viktiga:

Utvärdering av utvecklaren - Kommer det här verkligen att fungera ? Finns det tekniska begränsningar som vi inte har tagit hänsyn till?

Produktbedömande - Löser detta rätt problem ? Är det i balans med produktstrategin ? Vad saknas?

Designreview - Är användarupplevelsen meningsfulla ? Har vi tänkt på tillgänglighet ? Vad sägs om mobila system?

QA-review - Kan vi testa detta ? Är acceptanskriterien tydliga nog?

Du behöver inget formalt märke från alla. Du behöver deras intryck för att göra specifikationen bättre.

De vanliga frågorna

Bra kritiker ställer frågor som förbättrar specifikationen

" Vad händer om användaren gör X?" (edge casesM SK3
" Hur interagerar detta med den existerande egenskapen YM SK1 (integration
Vad är vårt fallback om beroendet Z inte är redo? ' är inte redo?
"Kan vi förenkla detta genom att göra W istället?
" Hur ska vi veta om detta lyckades?
" Vad håller vi inte på med?

Ingen av dessa är gotchas. De är riktiga frågor som hjälper till att få fram det specifika.

Inkorporation av feedback

Du kommer att acceptera alla förslag.

Tänk på det ärligt. "" Jag vill inte avfärda det eftersom de inte förstår "".
Om du accepterar det - uppdatera specifikationen, tack för kritiken
Om du inte accepterar det - Berätta varför
Om det "'" är bortom ramen - Lägg till den i sektionen "Othalb av gränserna " eller "Future Enhancements

Specen borde bli bättre med varje omgång av undersökningar.

få en överblick från alla dessa perspektiv innan du börjar implementera

Ett konkret exempel: Markdown Translation Service

För att göra allt detta mindre abstrakt, så kan en specifikation se ut som den automatiserade markerdown-översättningsfunktionen jag byggde för den här bloggen.

Förklaringen till problemet

bloggar skrivna på engelska bara utesluter icke-Engliska-talande läsare . Handöversättning av varje Beitrag till flera språk är tid- kvävdar och skjuter upp publiceringarM SK3 Vi behöver en automatiserad lösning som översätter markerdown- bloggar till flera målspråk utan att kräva manuellt ingripande för varje post

Lösningen

Implementera en bakgrundstjänst som automatiskt översätter markerdown-filer till konfigurerade målspråk med hjälp av EasyNMT maskinöversättningstjänster.

Monitora markerdown-filer för ändringar
Extrahera översättningsbar text medan man bevarar markerdown-strukturen och kodblockerna
Batchöversättningsbehov för effektivitet
Generera översatta markerdown-filer med lämpliga språks Suffixer

Framgångskriterien ( Vad är det som är så?

Dessa kriterier säger oss exakt när vi kan sluta arbeta med den här funktionen:

De nya bloggarna blir automatiskt översatta till alla konfigurerade språk ( från början : spanish , franska M SK3 tyska , italienska МSK5 portugisiska MST6 kinesiskaMST7 arabiska MrST8 Hindi M ST9 japanska LST10 koreanska M st11 holländska Mst12 ryskaM st13
De översatta lêerna upprätthåller samma markdown-struktur som originalen
Kodblocker , bildURLs, och formatering är kvar
Vertandet slutar inom 15 minuter för en typisk bloggpost.
Systemet bara omsätter - och översätter plikter som har ändrats ( som är kontrollerad via hashvergleich
Service börjar framgångsrikt även om översättningsAPI inte är tillfälligt tillgänglig
Fehler under översättningen är registrerade men don' krockar inte applikationen

Lägg märke till att de är specifika och testbara. Vi kan kontrollera varenda en av dem. När alla är uppfylldaM SK2 vi ' är färdigaMska4 Vi fortsätter inte att lägga till egenskaper som Mske6talvärdering för översättningarMskka7 eller | Mskka8 | handuttalande redigering av översättningerMskan9 om vi inte eksplicitt utökar skalan

I scope

Hintergrundtjänster för att processa markerdown-filer
Integration med EasyNMT-översättningsAPI
Hash-based förändringsdetektion för att undvika onödiga re-översättningar
Batchbehandling för att hantera EasyNMT's ordgräns
Round-robinlastbalansering över flera EasyNMT instanser
Bevarande av markerdown syntaxen, kodblocker , och bilder under översättning

Utan omfattning

User interface for manual translation editing (future enhancement)
Att översätta minnet eller glossrikshantering (kan lägga till om kvalitetproblem uppstår
Verklig-tidsöversättning ( bakgrundsbearbeitning är möjlig
T översättning av kodkommentar inom kodblock (medvetet utesluten)
Automatisk kvalitetbedömning av översättningar (manuell överprüfung krävs från början)

Teknika begränsningar

EasyNMT har ett ~500 ordgräns per fråga ( inte sant för mest tydliga-nmt som kan ta bort jäkla BOOKER) ; måste byta accordingly
Übersetzungstjänsterna kan vara långsamma. (~15 tvångstid per slag.
Flera EasyNMT-instantioner som behövs för en rimlig effekt. (oppe mest uppenbart.
Dateisystem I/O måste inte blockera huvudapplikationen

Öffna frågor vid Spectid

~~Kan vi kassera översättningar för att undvika att översätta de igen? Lösande: Ja, med hjälp av file hash comparison
~~ Hur hanterar vi EasyNMT-operationsfel Lösande: Log fel och hoppa filen ; kommer att försöka igen på nästa tjänst återstart / en kretsbrytare ( kan vara ett spöke
Vilka kvalitetproblem kan vi se med teknisk innehåll? Bestämmande : Skepp och utvärdera; handfulla övervakning av fångar

Vad vi lärde oss under implementeringen

Några saker dök upp under utvecklingen som raffinerade spektrat

Batch-storleksjustering: Började med ♫ 20- ♫ linjer i stor skala ♫ МSK2 ♫ men fann ♫10 ♫ linjer som var mer tillförlitliga för att stanna under EasyNMT ♫

Bilddetektion: Till att börja med , skickade man bildernas namn i markerdown till översättningstjänsterna, bråkförståelsetestningM SK3 Tog till fileextensionsdetektorn för att hoppa över bildervägar

Möjligheter till Service: EasyNMT kan vara temperamentell på utstartning. Hinnades hälsokontroll som frågar /model_name slutpunkt innan man försöker översätta

Hash lagring: Den ursprungligen planerade databasen för file hashes .hash plikter visade sig vara enklare och undvikade databases beroende för denna tjänst.

Dessa inlärningar foldades tillbaka i dokumentation och informerades om liknande egenskaper senare.

Varför denna specifikation fungerade

Den här specifikationen följde de principer som diskuterades

Problemet-first: Började med det faktiska problemet ♫ ( ♫ handöversättningen är långsam ♫ МSK2 ♫ inte lösningen ♫
Klara ramen: Uppenbarligen ropade ut vad vi inte gjorde
högra nivå av detaljer: Specificerade vad som behövde hända (bevara markerdown-strukturen
Levande dokument: öppna frågor löstes och beslut dokumenterade när implementering fortskridde
Samarbetande: Upplevt under implementeringsproblem | ( | liknande bild-lêer-nimen-behandling |) | diskuterades och löstes |

Resultatet – : – en egenskap som –' – har fungerat i produktion i månader – , – automatiskt översätter varje bloggpost med minimalt ingripande.

vanliga frågor om Agile Specs

Baserat på vad vi "'" har beskrivit , ",," här är frågor som ofta dyker upp

" behöver jag verkligen en specifikation för en liten sak?

Det beror på: "small." Om det är verkligt triviellt ( att byta knapp texten M SK4 att fixa en typo

Beräkna hur lång tid det kommer att ta
få överenskommelse från intressenter
Försäkra sig om att QA vet vad man ska testa
Dokumentera vad du byggt för framtida referenser

Då ja , till och med en snabb specifikation hjälper. Det behöver inte vara formelltM SK3 Några punkter i en biljett som täcker problemet , Lösning M SK5 och Klappde krav är ofta tillräckligt.

Testet, om du kan förklara vad

" Hur hanterar jag intressenter som vill ha allt inom ramverket?

Se på utom ram -sektionen.

Att lägga till mer ökade tidslinje - Vill de ha volymen A i 2 veckor eller volymer A
Vi kan göra det här: -, ", Det där är en fantastisk idé. ., Låt oss få kärnan att fungera först. ,, sedan ta det tillbaks som en separat spec.
Timmbox stärker prioriteterna - " Vi har 2 veckor . Vilket av dessa är mest viktigt

Om de insisterar på att allting är lika kritiskt, föreslår de att de väljer vilket annat jobb de ska skjuta upp istället.

" Tänk om specifikationen ändras så mycket att den är oidentifiserad från början

Det är "'", det är rättvist, , så länge som ":".

De ändringar är dokumenterade. (aktualisera specifikationen , inte ändra koden
ändringar kommuniceras ( Stakeholder vet vad som ändrats och varför
Du lärde dig något. De förändringarna reflekterar lärande.

Om specifikationen inte går att känna igen eftersom du helt missförstod problemet från början, så är det ett tecken på att göra fler upptäckter innan man börjar nästa gång. Men repetition och lärande förväntas.

Spektionens versionshistoria borde berätta historien om vad du lärde dig.

I Startups kallas det för en 'Pivot' där du börjar bygga ett spel och slutar med att bygga ett fantastiskt budskapsystem istället.

Är du inte tvungen att bli förtlockad i? .? Om det finns möjligheter med att pivota? Ta dem!

"Kan jag skriva specifikationer för bugfixer?

För kritiska bugs

För komplexa bugs som påverkar flera system eller kräver arkitektoniska ändringar.: ja, . behandla det som en egenskap.M SK2 Vad? '? är sönder.(? problem.

För allt däremellan.

Detta gäller särskilt för säkerhetsbugs.

" Hur formellt ska specifikationen vara

Så formellt som ditt lag behöver. Några lag är bra med detaljerade JIRA-biljetterM SK1 Andra vill ha korrekta dokument i versionkontrollen.

Formaliteten spelar mindre roll än innehållet

Klara problemsatsen
Föreslog lösning
Definition av gjort
Klara scopegränser

Du kan skriva det i Markdown.

Detta är den ofta omentönta nyckeln till agil utvecklingen ; och varför jag hatar Agile Frameworks ( och SCRUM ). Hela poängen är att precis som en agil specifikation måste din process vara anpassningsbar också M SK3 Om skrivande inte fungerar för ett enda lag men mycket gör det, så gör , det. Om 5 dagcyklar fungerar för ett lag men 2 veckas sprinter för ett annat Helaidén är att göra det bästa tootet ; ditt team är maskinen som tillverkar det productet. få maskinen att fungera så smidigt som möjligt

Som chef titta på vad dina utgångar är; om bordet behöver en nedbrännande graf så hur kan du använda den nuvarande datan för att bygga en

I slutändan ger du teamresultat och vad intressenter behöver

" Tänk om jag är den enda utvecklaren på projektet

Du behöver fortfarande specifikationer , kanske mer så. I sex månader när du behöver utöka den här funktionen M SK2 kommer du att vinna ' minns inte varför du fattade vissa beslut MSC4 Specen är ditt förflutna själv som talar med ditt framtida själv

Dessutom behöver du fortfarande

Beräkna arbeten för vem som betalar dig
Definiera vad "done " betyder så att du kan avsluta
Dokumentera vad du byggde för andra som skulle kunna delta senare

Att skriva specifikationer för dig själv är som att skriva ett test för enhet.

" Hur ska jag hantera scope creep som maskerats som 'förklaring till kraven

När någon säger """, glömde jag nämna att det också skulle göra "" X "", ","," "' är inte en förtydelse, ; det är ', den nya scopen."

Svaret: "Det är ett bra krav, ' men det är inte vad vi hade kommit överens om i specifikationen.

Om det verkligen är ett krav

uppdatera specifikationen för att inkludera den
uppdatera uppskattningen
få överens om den nya tidsramen eller vad som ska skäras för att passa in i den ursprungliga tidsramet

Never silently absorb scope creep. It 'll destroy your estimates and credibility.

"Kan jag börja koda innan specifikationen är slut

Ja, om du

Prototypering för att lära sig är bra : " Vi har tre tillvägagångssätt

Att bygga produktionskod innan specifikationen är redo betyder att du ', du gissar efter kraven , "., du kommer troligtvis att bygga fel .

undantag: om du ' är produktägare och utvecklare (soloprojektM SK3 kan du specifikera och koda på samma gångMSC4 Men ändå dokumentera dina beslut medan du går

' tills specifikationen är redo ' är ett bra sätt att få igång avdelningarna tills de börjar M SK2 Bedöma teknikmetoderna , skriva gemensamt boilerplate etc MSC4

" Tänk om mitt team inte läser specifikationer

Ta reda på varför

Alltför lång Gör dem kortare, mer skanningsbara
Alltför formellt? Använd ett ljusare format
Inte relevant? Var säker på att de faktiskt behöver det detaljerat du ' ger
Bad habit? Börja med att kräva specifikationer innan utvecklingen börjar

Om folk hoppar över specifikationer och sedan bygger felaktiga saker, så gör smärtan synlig. Detta var inte i specifikationen, så vi måste omarbeta den. Detta är en lärdom.

Även om de är gömda i någon obscur wiki, så kommer ingen att läsa dem.

" Hur mycket tid ska jag spendera på en specifikation

tumregler : 5-10% av utvecklingstid

För en 2-veckans förmågaM SK1 1-2 dagar på specifikationen För en 1-veckans möjlighet : en halv dag på specifikationen För en 2-dag-fenskap : en timme eller två på specifikationen

Men är inte religiösa om det. Några egenskaper behöver mer uppåt.

Om du' spenderar mer tid på specifikationer än på implementeringar , så överväger du det, ' övervägs det,

"Varför är beräkningar alltid fel?

Eftersom mjukvaraberäkningar är i grund och botten svåra bedömer bara att det fungerar om du

Vilket nästan aldrig händer

Varje gång du uppskattar

Okända okända - Problemet du inte känner till
Okända okända - Problem du vet existerar men har ingen idé om hur man ska lösa
Variationer i krav - Specen utvecklas så fort du bygger chefen har en galen idé i duschrummet .. det händer, ; Jag fick en gång ett 3sam samtal från min HUGELY DRUNK kund i duschen med en dumma ID
Miljöskillnader - Den där biblioteken fungerade i ditt senaste projekt, men den här har olika beroenden.
verktygsproblem - Konstruktionssystemet , anställningsröret , eller testmiljön beter sig annorlunda
Integrations överraskningar - Den API du ska ringa, ', fungerar inte riktigt som dokumenterat
Människa faktorer - Du, ', är avbrytnad, ,, sjuk, ,, eller hanterar produktionsproblem
Finansier - ibland behövs en mindre version tidigare eftersom *ifall vi inte får pengar kommer vi att ha ett artikel om "'", Startup dev , och hur det skiljer sig från normal dev .

Det är därför

Ramper som slår punkt beräkningar - "2-5 dagar" erkänner osäkerhet
Spikes hjälp - Spänd en dag i undersökningar innan du räknar ut det hela arbetet ; är den här tekniken svårare eller enklare än jag hade uppskattat
Time-boxningar - " Vi ' ska spendera SSK3 veckor och se vad vi får SSK4 ger oss förväntningar
Historiska fakta - Träffa hur länge liknande uppgifter faktiskt togs
Belagning är ärligt - Om du tror att

Ju nyare arbetet är, desto värre är dina prognoser.. Att bygga samma CRUD-form som du.', du har byggt 50, gånger, ?. Du kommer bli nära.M SK6. Att integrera med en ny tjänst med hjälp av en okänd protocol.

Detta är anledningen till att specifikationer behöver tydliga " gjorda " bedömande criteriM SK2 Du kan' inte uppskatta exaktMska4 men du kan definiera när man ska stannaMka5 AttMkka6 är mer värdefulltM Ska7

"Vad sägs om specifikationer för forskning eller utforskningsuppgifter?

Dessa behöver olika criteri. "doneM SK1 criteria. Istället för "feature X fungerar+,"+it='+s

exempel specifikation för utforskande:

Problemet: Vi vet inte ' om ansats A eller ansats B är bättre för den rådande motorn
Lösningen: Spänd 1 vecka prototypisering av båda angreppssätten
Klappde Kriterier: Vi har arbetande prototyper av var och en performance mätare för båda , och ett förslag som vi ska följa
Utan omfattning: Tillverkning implementering ( kommer efter att vi bestämmer

Tid-boxing är avgörande för utforskningen . Utan det

" Hur skriver jag specifikationer för egenskaper som jag inte känner till?

Börja med vad du vet:

Förklaringen till problemet ( du borde veta det här )
Företaget tillvägagångssätt ( ditt bästa gissning
fria frågor ( allt du inte känner till
Klappde kriterier ( även om grovt

Markera sektioner som "TBD

Använd sedan spec uppvärderingsprocessen för att fylla i luckor. Samtalen under uppvärderingen klarar ofta vad du inte visste

Kom ihåg

"Kan GitHub-utsläppen?/JIRA-biljetter vara spec?

Absolut. Specen behöver inte bestå av ett separat dokument . En välskriven GitHub-utgåva eller JIRA-biljett kan fungera som spec perfekt.

Vad som spelar roll är innehållet.

Klara problemsatsen - Vad löser vi och varför
Föreslog lösning - Hur ska vi
Klappde Kriterier - Spesifika ≥, accepterabla acceptanskriterien
Skoopgränser - Vad är ' i och ut ur omgivningen | | använder etiketter som " | ut från - | av - | omgivning, " | för saker du inte gör explicitt
fria frågor - Markera dessa med en "frågaM SK2 etikett eller liknande

De fördelarna med att använda problem:

Allt på en plats - Kod, ,, specifikation, ,, diskussion, M SK3 och uppföljning tillsammans
Makt att länka - Referensrelevanta frågor
Inbyggda versioneringar - Editionens redigeringshistoria visar hur krav har utvecklats
Välbekant arbetsflöde - Team vet redan hur man använder den

Tips för att använda problem som specifikationer:

Använd problembeschreibungen för specifikationen
Datera upp beskrywingn medan spec utvecklas (koda "redigeraM SK2 sektioner för att visa förändringar)
Använd etiketter för att indikera tillståndet
Pin viktiga specifikationsdiskussioner så att de inte går bort i ' kommentarer
Link till stödande dokument (diagramer, mockuper ) om nödvändigt

Testet: skulle någon kunna läsa problemet och veta vad man ska bygga, vad " gör, " vad det betyder, , och vad ' är bortom ramen

"Vad sägs om specifikationer i reglerade industrier?

Om du är inom hälsovård, ,, finansiering, ,, luft- och rymdutforskning,, eller andra reglerade områden, M SK4, så behöver du kanske fler formella specifikationer för att följa reglerna.

Börja med problemet
Definiera gjort tydligt
Utveckla när du lär dig
Håll specifikationerna aktuella

Men du måste också

Följ dina industristandarder för dokumentation
Inbegripa de åtfordrade sektionerna (säkerhetsanalys , regelmässiga inspektionen M SK2 revīzijasspår
få officiella skyltar, -, där det behövs
Håll mer detaljerad versionshistoria
Håll specifikationer efter projektets slut (för revideringarM SK1

Även i reglerade miljöer.,. Agil spektrering fungerar, .. Du har bara fler knorr att hoppa igenom... Specen är fortfarande ett verktyg.

I slutsats

Att skriva bra egenskapernas specifikationer i en agilla miljö är en förmåga som förbättras med träningen.

Huvudprinciperna:

Specs är verktyg, inte kontrakt - Lägg till detaljer där du behöver dem , utvecklas medan du lär dig
Börja med problemet, inte lösningen - Implementering kommer från att förstå problemet
Samarbeta - Alla bidrar till att göra specifikationen bättre
Definiera "done" tydligt - Förbjuda bakteriemetastas med beton.
Avgränsade frågor - Vad du inte gör är lika viktigt som vad du är
Förvända evolutionen - egenskaperna ändras när du bygger dem ; fångar lärandet
Håll specifikationerna aktuella - De blir grunden för tester , dokumentationer M SK2 och framtida utveckling

Den svåraste delen är: "'t skriver inte den ursprungliga specifikationen, . 't vet när man ska sluta arbeta med en funktion. . ' utan tydliga kriterier.

Det är därför det är så svårt att bedöma agilitet.

Det bästa du kan göra: är att vara tydlig med vad | " | gör |" | betyder | , | tid |- | lådan osäkerhet | SMK5 | och uppdatera specifikationen så fort du lär dig | SSK6 | behandla den som kod | : | version | skämt |

En bra specifikation gör att utvecklare kan lösa problem på ett smart sätt, samtidigt som de vet exakt när de kan stoppa.

Och om du är en utvecklare som läser en specifikation som inte är begriplig eller inte har någon tydlig definition, så är det bättre att sortera den nu än att bygga en egenskap som fortsätter växa tills den tar över hela applikationen.

Agile Speccing: Att skriva egenskaper som faktiskt fungerar

Inleiding

Varför Agile ( och vad det egentligen betyder

Första principerna

Ekonomin. Varför sparar det pengar?

Feedback-loop är produkten

Vad gör en bra dragspecifik

Problemet-lösningsmönster

Uppenbarhet av syfte

Den rätta nivån av detaljer

Randfall och felbehandling

säkerhets- och effektivitetsbegränsningar

Strukturen av en bra art

1. Übersicht

2. bakgrund

3. Användarberättelser

exempel Personas

Till exempel användarberättelser

Varför Personas + berättelser fungerar tillsammans

4. detaljerade krav

5. icke-Funktionala krav

6. ute ur volymen

7. öppna frågor

8. beroenden

9. acceptanskriterien

Problemet med Spec-bugs

Hur Spec-bugs händer

Att hantera spec-bugs

Option 1: lyfta upp den omedelbart

Option 2: Implementera det hursomhelst

Option 3: Fix It Yourself

Att förhindra Specific bugs

vanliga fall

Novelen-Längd Spec

Den vaga handvågen

Lösningen-First Spec

Den rörande målet

köksbänken

Att behandla arter som källkod

Versionskontroll

Refaktorisering av specifikationer

Levande dokumentets princip

Varför Speker behöver vara aktuella

Att skriva specifikationer för olika publiker

Testa din spec

Agil-metoden mot arter

Hur agilla arter skiljer sig från Waterfall

Omfamna ofullständighet (

Specen kommer att ändras

När Agile Speccing går fel

Bara tillräckligt med detaljer för att börja

Samarbetsmodellen

Evolution under utveckling

Utmaningen för uppskattning

Definiera "Ansluta" ( Eller hur man stoppar funktionsmetastasenM SK3

Problemet med vag "Done"

Att skriva konkreta "Ansökt" Kriterier

Det utanför ramen är din vän

Time-Boxing as a Last Resort

Spikes & Sprints.

Förebygga scopekripp under utvecklingen

När det ska hända

Treat Spec Reviews som Code Reviews

Vem borde överväga

De vanliga frågorna

Inkorporation av feedback

Ett konkret exempel: Markdown Translation Service

Förklaringen till problemet

Lösningen

Framgångskriterien ( Vad är det som är så?

I scope

Utan omfattning

Teknika begränsningar

Öffna frågor vid Spectid

Vad vi lärde oss under implementeringen

Varför denna specifikation fungerade

vanliga frågor om Agile Specs

" behöver jag verkligen en specifikation för en liten sak?

" Hur hanterar jag intressenter som vill ha allt inom ramverket?

" Tänk om specifikationen ändras så mycket att den är oidentifiserad från början