Kuinka kirjoittaa teknisiä eritelmiä, jotka todella laivan

Jos luet tätä, on todennäköistä, että olet katsonut puolivalmistettua teknistä spesifikaatiota 2am: ssä, yrittäen epätoivoisesti kääriä sen ennen standupia. Mutta tässä on asia: kun teet hyvin, tekniset eritelmät eivät ole kotitehtäviä tekniikkasi johdosta. Ne ovat yksi tehokkaimmista työkaluista, joita sinun täytyy ajaa ominaisuuksia ideasta tuotantoon. Aion näyttää sinulle, miten lähestyn niiden kirjoittamista, perustuen kokemukseeni Monzossa ja oppitunteihin, jotka olen ottanut AWS: n, Googlen ja Meta: n insinööreiltä. My background is software engineering, but a lot of this transfers to other technical disciplines. Let's dive in. Miksi kirjoittaa tech specs muutenkin? Asiakirjojen kirjoittaminen tuntuu busyworkin kaltaiselta, kun saatat olla lähettämällä koodia. Mutta pysy kanssani täällä, koska hyvä tekninen spesifikaatio tekee paljon enemmän kuin tyydyttää joitakin prosessivaatimuksia. Kun sitä käytetään hyvin, tekniset eritelmät auttavat sinua: — I've killed more bad ideas during the spec phase than I care to admit. Writing forces you to think through edge cases you'd otherwise discover three sprints in. Validate the idea before you waste weeks building it — Your staff engineer, your product manager, that principal engineer who's seen it all. Getting their thumbs up early means you won't be defending your approach in a contentious PR review later. Get buy-in from people who actually matter Iteroi korkean tason suunnitelman kanssa älykkäämpiä ihmisiä kuin sinä - en ole älykkäin henkilö huoneessa, ja jos olet rehellinen itsellesi, et myöskään. Jaa tietosi tiimillesi – Uuden insinöörin käyttöönotosta tulee "lue tämä spesifikaatio" sen sijaan, että "annetaan minun selittää tämä arkkitehtuuri kolmannen kerran tällä viikolla". Jaa tietoa sidosryhmien kanssa tekniikan ulkopuolella - Tuotepäällikkösi, vaatimustenmukaisuusjoukkueesi tai rahoitushenkilöt tarvitsevat ymmärtää, mitä rakennat ja miksi. Käytä validointiin, kun työ on valmis – Oletko itse ratkaissut sen, mitä olet asettanut ratkaisemaan? Spec-ohjattu kehitys ja LLM LLM: t ovat muuttaneet tapaa, jolla ajattelen teknisiä eritelmiä. LLM: t toimivat parhaiten tiukkojen teknisten eritelmien kanssa. Mitä vähemmän jätät mielikuvitukselle, sitä parempi. Hyvin määritelty spec voidaan syöttää LLM: hen automaattiseen lippujen luomiseen tai jopa tekniseen toteuttamiseen. Voit luoda testejä eritelmistäsi. Voit käyttää LLM: tä ideoimaan ehdotuksesi osia, pyytää heitä tekemään tutkimusta tai jopa auttamaan tunnistamaan logiikan puutteita. Minulla on toinen artikkeli tulevien viikkojen aikana, joka on omistettu spec-pohjaiselle kehitykselle LLM: n kanssa. Pidä silmällä sitä - olen kokeillut tätä mittakaavassa ja tulokset ovat todella vaikuttavia. Mutta vaikka et koskaan koskisi LLM: hen, kurinalaisuus kirjoittaa tiukka spec maksaa osinkoja. Hyvän teknisen ehdotuksen anatomia (osa 1) A good technical spec is well-structured, easy to understand, and actionable. It should be skimmable for executives and detailed enough for the engineer implementing it. That's a narrow tightrope to walk, but I've found a pattern that works. Tässä on anatomian ensimmäinen puoli.Tämä on mitä kirjoitat ennen kuin saat ostaa. Mitä yrität ratkaista? Ei ratkaisu – ongelma.Olen nähnyt niin monia spesifikaatioita, jotka hyppäävät suoraan Koskaan ei voi selittää, mikä on rikki. "Meidän pitäisi rakentaa mikrosivusto GraphQL:llä" Startupissani, Tandemissa, minulla on yksinkertainen testi: voiko Jack, ei-tekninen perustajani ymmärtää ongelman vain lukemalla sen? Joitakin tekniikoita, jotka toimivat: : Not but Use concrete examples "users experience latency" "users wait an average of 8 seconds for their transaction history to load, and we're seeing 23% drop-off at this screen." Näytä liiketoiminnan vaikutus: "Tämä maksaa meille noin 2,3 miljoonaa puntaa vuosittain menetetyissä muunnoksissa" on paljon vakuuttavampaa kuin "tämä on hidasta". : If you have user research, customer complaints, or monitoring data, drop it in. Evidence beats opinion. Include quotes or data What are you NOT trying to solve? Scope creep on todellinen, ja jos et nimenomaisesti kutsu esiin, mikä on ulottumattomissa, vietät seuraavan kuukauden väittelemällä edge-tapauksista, joilla ei ole väliä. Kuvittele tämä: saat alustan tiimiltä ehdotuksen päivittääkseen loistavaan uuteen jaettuun käyttöliittymän kirjastoon. Näyttää yksinkertaiselta, oikein? Vaihda vain joitakin tuontia, päivitä muutama komponentti. Mutta sitten huomaat, että uusi kirjasto käyttää täysin erilaista reititysjärjestelmää alla. Nyt sinun on uudistettava jokainen reitti sovelluksessasi. Sitten ymmärrät, että tuotejoukkueen navigointimallit eivät sovi täysin uuteen malliin, joten tarvitset räätälöityjä pakkauksia. tuotejoukkue, joka on riippuvainen tästä jaetusta kirjastosta?Ne kaikki estetään samoilla muutoksilla. Se on juuri muuttunut kuuden kuukauden maahanmuuttotyöhön, joka tukee koko organisaation toimintaa. Toinen Yksinkertainen päivitys » Yksi selkeä section could have caught this early. It gives you permission to say no. It keeps the culture of Ja se suojaa aikajana näiltä näennäisesti viattomilta ehdotuksilta, jotka ilmenevät organisatorisiin painajaisiin. ”Mitä emme ratkaise” ”Miksi uutinen” Miksi tämä ongelma pitäisi ratkaista? Not all problems need solving. Some can live with workarounds. Some aren't actually problems, just minor inconveniences. Why should this one get attention and engineering time? Tee tapaus selväksi: Vaikutus käyttäjiin: Kuinka monta ihmistä tämä vaikuttaa? Vaikutus liiketoimintaan: tuloja, säilyttämistä, muuntamista, toimintakustannuksia? Vaikutus tekniikkaan: Onko tämä tekninen velka, joka hidastaa kaikkia muita hankkeita? Vaikutus vaatimustenmukaisuuteen tai riskiin: Räjähtääkö tämä kuuden kuukauden kuluttua, jos emme korjaa sitä? Olen suuri uskovainen näyttämään työtäsi täällä. älä vain sano Olemme kerran pohjanneet ehdotuksen tekstin muuttamisesta painikkeella kokeeseen, joka osoitti 23%: n kasvun muuntamisessa, mikä kääntyi +£12k ARR: een. ”Tämä on tärkeää.” "Tämä painikkeen kopiointi voisi olla parempi." Miksi nyt? Timing merkitsee enemmän kuin ihmiset ajattelevat.Olen nähnyt täydellisesti hyviä ehdotuksia hyllyyn, koska se ei ollut oikea aika.Ja olen nähnyt keskinkertaisia ehdotuksia vihreänä, koska ajoitus oli täydellinen. Miksi nyt on paras aika ratkaista tämä ongelma? Ulkopuoliset määräajat: sääntelyn muutokset, markkinointikampanjat, konferenssin esittelyt Sisäinen valmius: Onko sinulla oikea infrastruktuuri? oikea tiimikapasiteetti? Riippuvuudet: Onko muita hankkeita, jotka täytyy lähettää ensin? Mahdollisuuksien ikkunat: Joskus on kapea ikkuna, kun jotain on helpompi ratkaista kuin se koskaan tulee uudelleen. Tässä on erityinen esimerkki. Meillä oli ehdotus käyttää paikallisia aikavyöhykkeitä pankkitilin tilinpäätöksissä UTC:n sijaan. Aikataulu oli kriittinen – halusimme tehdä sen heti, kun päivänvalon säästöt päättyivät Yhdistyneessä kuningaskunnassa. Tämä antoi meille kuusi kuukautta, kun UTC ja paikallinen aika olivat samat. Meidän oli myös pidettävä historialliset lausumat alkuperäisessä aikavyöhykkeessään oikeudellisista syistä. Aloittaminen heti kellojen muutoksen jälkeen merkitsi, että meillä oli enimmäisikkuna ennen seuraavaa siirtymää, mikä vähensi merkittävästi mahdollisuuksia, että joku tarvitsi tuottaa lausuman useilla loogisilla aikavyöhykkeen muunnoksilla. Jos olisimme tehneet sen maaliskuussa marraskuun sijaan, olisimme ottaneet käyttöön monimutkaisempia ja edullisempia tapauksia. ajoitus ei ollut vain tärkeä - se oli ero puhtaan muuttoliikkeen ja painajaisen välillä. vaatimukset Mikä on 100% ei-neuvoteltavissa? Mitkä ovat absoluuttiset alhaiset, joita ei voida sulkea pois? Think of requirements as the must-haves. Not the nice-to-haves, not the maybe-we-should-also, but the core things that must be true for this to be worth doing at all. Rakennevaatimukset testaavina lausuntoina: "Transaktiohistoria on ladattava alle 2 sekunnissa p95: ssä" Ratkaisun on oltava käyttökelpoinen iOS 14:ssä ja sitä uudemmissa versioissa "Tiedot on salattava lepo- ja kauttakulkuvaiheessa" "Ei tarvitse vaatia asiakasta todentamaan uudelleen" Huomaa, että nämä ovat erityisiä ja todennettavissa. Voit testata, oletko täyttänyt ne. tai Ei ole mitään hyötyä, laita ne alas. ”Pitää olla nopea” ”Pitäisi olla turvallista” Lintujen näkemys ratkaisusta He heti sukeltaa täytäntöönpanon yksityiskohtia - mikä tietokanta, mikä API, mikä palvelu mesh. Lintujen näkökulman pitäisi olla ymmärrettävä ei-teknisille sidosryhmille. Puhun tuotejohtajille, toiminnan ihmisille, ehkä jopa rahoitukselle. Jos et voi selittää ratkaisua jollekin, joka ei tiedä, mitä Kubernetes on, et ymmärrä sitä tarpeeksi hyvin itse. Muutamia sääntöjä tähän osaan: Ei vielä, mutta sen sijaan, että sanovat No tech talk. "Käytämme uuden mikrosivuston, jossa on Redis-välimuisti ja paljastamme sen GraphQL: n kautta." "Säilytämme usein käytettyjä tietoja lähempänä käyttäjää, jotta se ladataan välittömästi sen sijaan, että se tekisi hitaasti matkaa tietokantaan joka kerta." Mitä muutoksia käyttäjän näkökulmasta?Mitä menestys näyttää heille? Think user-centric. Start with ja sitten selittää korkealla tasolla, miten saavutat sen. Anchor on outcomes, work backwards. "Käyttäjät näkevät tapahtumahistorian latauksen alle 1 sekunnissa" Joskus on todella erilaisia lähestymistapoja. Laita kaksi tai kolme vaihtoehtoa, joilla on etuja ja haittoja. Tämä osoittaa, että olet ajatellut sitä läpi ja antaa sidosryhmille todellisen valinnan. If possible, offer multiple potential solutions. Tässä vaiheessa sinun pitäisi pysähtyä ja arvioida uudelleen. Tässä on minun tarkistuslista ennen kuin siirryt eteenpäin: [ ]Probleemailmoitus on selkeä ja konkreettinen [ ]Liiketoiminnan vaikutus on määritetty [ ]Ei-tavoitteet on ilmoitettu nimenomaisesti [ ] Vaatimukset ovat testattavissa [ ]Korkean tason ratkaisu on järkevää ei-insinöörille [ ] Olen varma, että tämä kannattaa tehdä If you can't check all these boxes, don't proceed to part 2 yet. Seriously. I've wasted weeks writing detailed implementation plans for ideas that weren't actually worth doing. Osta ja tee yhteistyötä Seuraava askel on saada palautetta keskeisiltä sidosryhmiltä. Tämä ei ole muodollisuus. Tämä on paikka, jossa spesifikaatiosi joko paranee tai hajoaa. Tässä muutamia vinkkejä onnistuneeseen pitsiin: Olen fani Notion koska reaaliaikaisia kommentteja ja yhteistyötä, mutta Google Docs toimii myös. Olen jopa nähnyt joitakin todellisia edelläkävijöitä käyttää Figma tähän kerran! Tärkeintä on, että ihmiset voivat jättää sisäisiä kommentteja ja ehdottaa muutoksia. Vältä PDF-tiedostoja tai Word-tiedostoja liitetään sähköposteja - haluat tämän olevan elävä asiakirja. Use a platform that makes collaboration easy. Jos ehdotat muutoksia käyttäjän matkaan, luo kuvakaappauksia tai langallisia kehyksiä. Jos optimoit palvelua, näytä nykyiset mittarit valvontasi kuvakaappauksilla. Suosittelen Figmaa (korkea uskollisuus) tai Excalidraa (alhainen uskollisuus) käyttäjän matkoille ja kuvakaappauksia Grafanasta tai Datadogista mittareille. Illustrate your points. Leave your ego at the door. Every piece of criticism you get now is a production issue you won't have later. I've had specs torn apart in review, and it sucks. But you know what's worse? Building something for three months only to have it fail in production because you missed something obvious. Getting feedback should be your main objective. Jos joku jättää kommentin kuten Pyydä heitä selittämään miksi ja ehdottamaan vaihtoehtoa. epämääräinen negatiivisuus ei auta ketään. Guide your contributors. "I don't like this approach," Joku kysyy You need an answer. The best answers have numbers. Se on paljon vakuuttavampaa kuin Be ready to defend your value proposition. ”Onko tämä insinöörin aika sen arvoinen?” "Tämä voi johtaa 27%: n vähenemiseen tietokannan hosting-kustannuksissa, mikä johtaa 1,5 miljoonan punnan vuotuisiin säästöihin" ”Tämä tekee asioista tehokkaampia.” Suunnitelma, joka kannattaa toteuttaa (osa 2) Käsitteletkö teknisiä eritelmiä yksin? Kirjoita se yksin, jaa se tarkastelua varten, saada kommentteja, lähetä se? Parhaat tekniset eritelmät ovat vahvan yhteistyön tulosta. Kirjoitat ensimmäisen luonnoksen, varmasti. Mutta sitten kutsut älykkäitä ihmisiä tekemään siitä paremman. Sisällytät heidän palautteensa. Sopeutat sen perusteella, mitä opit. Tämä anatomian toinen osa on dynaamisempi. Se vaihtelee yrityksesi kulttuurin, tiimin käytäntöjen ja projektityypin mukaan. Best practices and company standards Jos käytät Reactia ja Next.js:ää web-frontendejä varten, sinun pitäisi käyttää Reactia ja Next.js:ää. Jos yritykselläsi on vakio CI/CD-putki, käytä sitä. The exception is when you're explicitly proposing to change an established practice. Maybe you want to introduce a new framework or migrate to a different database. That's fine — but make your case with evidence. Kun olen ehdottanut muutoksia vakiintuneisiin käytäntöihin, sisällytän aina: : Has another company done this successfully? Show case studies. Outside proof of concept Aiempi taide naapurimaista: Olemmeko käyttäneet samanlaisia lähestymistapoja eri yhteyksissä? : Don't just say Show where the current approach fails. Clear reasoning for why the current approach doesn't work "this is better." : How do we get from here to there without breaking everything? Migration path Superbetissa johdin tiimiä, joka rakensi omistautuneen käyttöliittymän kirjaston korvaamaan jatkuvasti ongelmallisen Ant-suunnittelun, jota käytimme ennen. Teimme sen 100%: n drop-in-korvaukseksi yhteensopivuuskerroksen kautta – teknisesti täydellinen. Mutta en vieläkään onnistunut vakuuttamaan useimpia joukkueita ottamaan sen käyttöön, koska en voinut ajaa liiketoimintatapaa kotiin. Se on opetus tässä: vakiintuneen tekniikan korvaaminen on vaikeaa, vaikka ratkaisu on objektiivisesti parempi. Tarvitset numerot, tapaustutkimukset, siirtymäpolku. Prior art and alternatives considered Onko jotain samanlaista jo olemassa?Oletko aiemmin toteuttanut ominaisuuksia, joilla on samanlaisia ominaisuuksia?Kaikki tämä kannattaa mainita. Best case scenario: you discover you don't need to build anything new. You can reuse an existing solution. Attach it to the knowledge base related to the solution you found. It helps the maintainers understand who their stakeholders are and why people need this. If they want to sunset, transfer ownership, or refactor their software, they'll know who to talk to. If this happens, don't throw away your spec. I've saved months of engineering time by finding prior art. We used Statsig to ship experiments, but we'd written our own SDK on top of it instead of using the official one. Our implementation didn't support persisting allocations, which meant we couldn't run sticky experiments. I started speccing out how to add this feature — thinking I'd need to build it from scratch — and went on a bit of a wild goose chase. Then I found an existing, domain-specific service that already solved persistence for a different use case. I just copied the implementation pattern. What I thought would take weeks, only took two days. What other approaches did you evaluate? Why didn't they make the cut? This shows you've done your homework. It also prevents people from suggesting alternatives you've already considered and rejected. I usually include a short table: Approach Pros Cons Why we rejected it Use existing service X Fast, proven Doesn't support feature Y Missing critical functionality Build custom solution Perfect fit High maintenance cost Not worth the ongoing burden Third-party API Easy integration Vendor lock-in, high cost £250K annually vs £30K to build Käytä nykyistä palvelua X Nopea ja todistettu Doesn't support feature Y Missing critical functionality Rakenna tavanomainen ratkaisu Täydellinen Fit Korkeat ylläpitokustannukset Jatkuvaa taakkaa ei kannata Third-party API Easy integration Vendor lock-in, high cost £ 250K vuosittain vs £ 30K rakentaa The technical approach Now — finally — you can get into the details. This is where you explain the actual implementation, architecture decisions, and tech stack choices. Arkkitehtuurin kaavioita, sekvenssi kaavioita, tiedonkulku kaavioita. suosittelen (now ) koska se on ilmainen ja sillä on kunnollisia yhteistyöominaisuuksia. haittapuoli on, että ei ole elävää jakamista kuten Figma, joten sinun täytyy viedä ja upottaa kuvia. Use diagrams. Draw.io diagrams.net Sekvenssi kaavioita, pidän Mermaid koska voit kirjoittaa ne markdown ja ne automaattisesti useimmissa työkaluissa. sequenceDiagram User->>API: Request transaction history API->>Cache: Check cache Cache-->>API: Cache miss API->>Database: Query transactions Database-->>API: Return results API->>Cache: Store in cache API-->>User: Return results Älä vain sano Say Explain the "why" behind technical decisions, not just the "what." "we'll use Redis for caching." "we'll use Redis for caching because our access patterns are heavily read-biased (95% reads vs 5% writes) and we need sub-millisecond latency. We considered Memcached but chose Redis because we need data structures like sorted sets for timeline features." Ole rehellinen siitä, mihin tämä katkeaa. Se on paljon hyödyllisempää kuin teeskennellä, että ratkaisusi mittasuhteet ovat loputtomia. Call out performance characteristics and scalability limits. "Tämä lähestymistapa toimii jopa noin 100 000 pyyntöä sekunnissa. Näytä, miltä tiedot näyttävät. Näytä, miltä API-pyynnöt ja vastaukset näyttävät. Mention data models, API contracts, key interfaces. { "transaction_id": "tx_123", "amount": 1250, "currency": "GBP", "timestamp": "2025-01-15T14:30:00Z", "category": "groceries" } Yksi etu mallien upottamisesta siirrettävässä muodossa, kuten JSON: ssä, on se, että tämä voidaan sitten kopioida / siirtää testi- tai pilkkauspalveluun myöhemmin. Yksi etu mallien upottamisesta siirrettävässä muodossa, kuten JSON: ssä, on se, että tämä voidaan sitten kopioida / siirtää testi- tai pilkkauspalveluun myöhemmin. Jos tämä edellyttää uusien palvelujen, tietokantojen tai kolmansien osapuolten integraatioiden kiertämistä, soita se pois. Highlight any new infrastructure or services needed. Breaking down the work How do you decompose this solution into milestones and tasks that can be tracked? This is project management, but it's your job to provide the structure. Olen suuri fani MVP → MLP → Full Product progression: Split into phases that deliver incremental value. MVP (Minimum Viable Product): Absoluuttinen pienin asia, jonka voit rakentaa validoidaksesi lähestymistavan. MLP (Minimum Lovable Product): Pienin versio, joka on todella riittävän hyvä todellisille käyttäjille käyttää ja nauttia. : All the bells and whistles. Full Product Tämä on vaikea myöntää, mutta monissa tapauksissa päädyimme pitämään MLP: n lopputuloksena, koska se oli . "good enough" What must ship for this to work? What's optional? Use a prioritisation framework. I like MoSCoW (Must have, Should have, Could have, Won't have). Identify critical path items vs nice-to-haves. Voivatko backend- ja frontend-tiimit työskennellä samanaikaisesti?Vai tarvitseeko backend lähettää ensin?Riippuvuuksien selkeyttäminen auttaa suunnittelussa. Call out what can be parallelised vs must be sequential. Itse asiassa inhoan kokoa ja olen huono siihen. Mieluummin kehittäjä tuntia, kehittäjä päivää, kehittäjä viikkoja mittausyksiköinä, kun keskustellaan aikajanoja. Jos olet epävarma, mene yksi mittaus, esim.: ei ole varma, jos 3 tai 4 kehittäjä päivää? Käytä 1 kehittäjä viikko. Assign rough t-shirt sizes or story points if your team uses them. Käytä yksinkertaista riippuvuusgrafiikkaa tai vain luetella ne: Make dependencies between tasks explicit. "Tehtävä B riippuu siitä, onko Tehtävä A valmis. Tehtävä C voi alkaa rinnakkain Tehtävän B kanssa." Success metrics How will you measure if the implementation actually worked? What are the KPIs? Tässä määrittelet voiton olosuhteet, ja sinun on oltava erityinen. is not a success metric. Se on menestysmetriikka. "Make it faster" "Reduce p95 API latency from 500ms to under 200ms" Examples: Define measurable outcomes. Viiveen väheneminen: "p95 viive laskee 800 ms: stä 200 ms: iin" Virhetaso laski: ”5xx-virheet laskivat 0,3 prosentista alle 0,1 prosenttiin” Conversion improvement: "checkout completion rate increases from 73% to 80%" Cost savings: "database costs decrease by £40K annually" You need to know where you're starting. I take screenshots of dashboards showing current performance and attach them to the spec. It's way too easy to forget what things were like before you started. Set baseline metrics before implementation. Haluatko rakentaa ohjauspaneelin? Aseta hälytykset? Suorita A/B-testi? Ole selkeä mittausmenetelmistä. Specify how you'll track these metrics. Tuotepäälliköt välittävät tuloista ja sitoutumisesta. insinöörit välittävät viiveestä ja läpäisystä. Include both business metrics and technical metrics. Riskien arviointi, riippuvuudet ja lieventäminen What could go wrong? What are you worried about? What do you need from other teams? I've learned to be brutally honest in this section. Pretending risks don't exist doesn't make them go away. It just means you won't have a plan when they materialise. Do you need another team to ship something first? Do you rely on a third-party service that might have rate limits or downtime? Call it out. I've had projects delayed by weeks because of dependencies I didn't flag early enough. List external dependencies. Mitä tapahtuu, jos yksi kriittinen palvelu epäonnistuu? Jos otat käyttöön uuden tietokannan, mitä tapahtuu, jos se epäonnistuu? Call out single points of failure in your design. Are you using a technology for the first time? Is this an area of the codebase nobody really understands anymore? Are you making assumptions about user behavior that might be wrong? Identify areas with high uncertainty. Älä vain luetella riskejä - osoita, miten voit käsitellä niitä. For each major risk, propose a mitigation strategy or fallback plan. Riski: Kolmannen osapuolen API:llä voi olla pysähtymisaika Mitigation: Implement circuit breaker with exponential backoff; välimuisti vastaukset 5 minuuttia; on degraded tilassa, joka toimii ilman API Tämä luo luottamusta ja pyytää apua. Parempi kuin teeskennellä, että olet keksinyt kaiken. Be honest about what you don't know yet. "I'm not sure how we'll handle the migration of 500GB of existing data — looking for input here" Älä odota, kunnes tietoturvatarkastus havaitsee, että tarvitset koko yksityisyyden vaikutustenarvioinnin. Jos kosketat käyttäjätietoja, soita se ulos. Mention compliance, security, or data privacy concerns early. Rollout strategy How will this actually get deployed? Phased rollout? Feature flags? Canary deployments? En koskaan lähetä suuria muutoksia 100 prosenttiin käyttäjistä ensimmäisenä päivänä. Jos sinulla on vain kaksi käyttäjää, lähetä vain yhdelle. Jos sinulla on vain kaksi käyttäjää, lähetä vain yhdelle. My usual progression: 5% → 10% → 50% → 100%. At each stage, you monitor metrics and watch for issues. If something breaks, you're only affecting a small subset of users. Plan for gradual rollout. Levitä koodi tuotantoon, mutta pidä se lipun takana. Tämän avulla voit hallita, kuka näkee uuden ominaisuuden riippumatta käyttöönottoprosessistasi. Olen käyttänyt LaunchDarkly, Statsigia ja rakentanut kotimaisia ratkaisuja. Ne kaikki toimivat. Valitse yksi ja käytä sitä uskonnollisesti. Use feature flags to decouple deploy from release. Mitkä olosuhteet laukaisevat rollbackin? Define rollback criteria. Jos virhetaso ylittää 0,5 %, käänny takaisin Jos p95:n latenssi ylittää 1 sekunnin, rullaa takaisin Jos saamme yli 10 asiakkaan valitusta tunnissa, käänny takaisin Having these criteria defined in advance means you won't be making emotional decisions during an incident. Lähetä todellista liikennettä uuden koodin polun kautta, mutta älä näytä käyttäjille tuloksia. Vertaa tulosta vanhaan koodin polkuun (kutsutaan myös: varjotestaus). Tämä puhdistaa virheet ennen kuin käyttäjät näkevät ne. Consider dark launching to test in production without user impact. Miljoonien tietokantatietueiden siirtäminen on riskialtista. Tee se erillään uusien ominaisuuksien lähettämisestä. Ihannetapauksessa siirrä ensin tiedot, asenna sitten koodi, joka käyttää uutta järjestelmää, ja puhdista sitten vanha järjestelmä (laajenna-siirrä-sopimusmalli). Plan for data migrations separately from code deploys. Kuka tarvitsee tietää, milloin tämä alukset? asiakaspalvelutiimi? markkinointi? ulkoiset kumppanit? Kirjoita comms-suunnitelma spesifikaatioon. Have a communication plan for internal stakeholders and customers. Rollback -strategia What happens if you suddenly become unavailable when everything's on fire? Would your team know how to handle it? Ajattele sitä kuin lentäjien esikatseluluetteloa. Kun stressi on korkea ja adrenaliini pumppaa, et halua selvittää asioita. Kiinnitä merkki lippu X Or: roll back to commit abc123 and deploy Käynnistä tietokannan skripti Y palauttaaksesi järjestelmän muutokset Clear Cache Z poistaa pysyviä tietoja Monitor metrics A, B, C to confirm rollback successful Post in #incidents kanava, jossa on tilanne This keeps stress to a minimum in incident scenarios. Testattava lähestymistapa Yksikökokeet, integrointitestit, kuormitustestit, reunan tapaukset – miten voit vahvistaa, että tämä todella toimii? Critical paths need extensive tests. Nice-to-have features can have lighter coverage. Be explicit about what needs what level of testing. Define test coverage expectations. If this will serve millions of requests, you need to test it at scale. I use tools like k6 or Locust to simulate load. Don't wait until production to discover your database falls over at 10,000 QPS. Plan load/performance testing for high-traffic features. Tappakaa riippuvuudet. Injektoi viive. Simuloi verkko-osioita. Katso, mikä rikkoo. Netflixin Chaos Monkey on kanoninen esimerkki, mutta et tarvitse mitään, joka on hienostunut. Consider chaos engineering for critical systems. What happens when the database is slow? When the cache is empty? When a user sends malformed input? These are where bugs hide. Test edge cases and failure modes, not just happy paths. Automated tests are great, but they only catch what you thought to test for. A human clicking around can find the weird stuff. Plan for manual QA/exploratory testing where needed. Pen-testaus, OWASP Top 10 -tarkastukset, riippuvuuksien skannaus. Jos kosketat todentamista, maksuja tai henkilökohtaisia tietoja, tarvitset turvallisuusarvioinnin. Include security testing for sensitive features. Aikataulut ja välitavoitteet Realistic estimates, buffer for unknowns, key delivery dates. Tässä on epämiellyttävä totuus: alkuarviosi ovat väärässä. ne ovat aina väärässä. Jos on olemassa sääntelyvaatimus tai konferenssin demo, aloita siellä ja työskentele taaksepäin selvittääkseen, onko se toteutettavissa. Work backwards from hard deadlines if they exist. Jos työskentelet tutulla alueella tunnetulla tekniikalla, kerro laskelmat 1,2x. Jos olet tuntemattomalla alueella tai käytät uutta tekniikkaa, kerro 1.5x 2x. Tiedän, että se tuntuu liialliselta, mutta en ole koskaan katunut laskelmia ja olen aina pahoillani liian optimistisesta. Pad estimates for unknowns. Joka toinen viikko, sinun pitäisi pystyä osoittamaan jotain. se pitää vauhtia ja pintaa ongelmia aikaisin. Define clear milestones with demos or checkpoints. Lomat, konferenssi kausi, vaatimustenmukaisuus määräajat, markkinointi käynnistykset. Jos puolet tiimistä on menossa ulos viikoksi, laske se sisään. Call out external constraints. Account for on-call rotations, other commitments, the fact that nobody is productive 8 hours a day. I usually assume 6 productive hours per engineer per day, and that's being generous. Be realistic about team capacity. Initial estimates are educated guesses. As you get into implementation, you learn things. Update your timeline accordingly. A spec should be a living document, not a contract written in stone. Update estimates as you learn more. Open questions Mitä on vielä selvitettävä?Mitä on vielä selvitettävä? This section should shrink over time as you get answers, but it's crucial to have it. It shows intellectual honesty and invites collaboration. "Meidän on vahvistettava, että lähestymistapa X pystyy käsittelemään kyselytilavuuttamme" tai "Meidän pitäisi ensin prototyyppi siirtymiskirjoituksen testitietokokonaisuudessa." List unknowns that need research or prototyping before committing. "Pitää turvallisuusryhmän tarkastelua salauksen lähestymistavasta" tai "Pitää tuotteen syöttöä siitä, mikä palautuskäyttäytyminen pitäisi olla." Call out decisions that need input from specific people or teams. "Odotamme, että käyttäjät napsauttavat tätä painiketta, mutta meidän pitäisi A / B-testaus vahvistaa" tai "Uskomme, että tämä välimuisti osuma on 80%, mutta meidän pitäisi mitata todellisia liikennemalleja ensin." Highlight areas where you need to validate assumptions with data. "We could optimise for latency or throughput but not both — need to decide which matters more for this use case." Be explicit about trade-offs you haven't resolved yet. Jonkun on oltava vastuussa vastauksen saamisesta, ja on oltava määräaika. Assign owners to each open question with target resolution dates. How culture plays a role I've worked at companies where specs were treated as bureaucratic box-checking exercises, and I've worked at companies where they were genuinely valued as thinking tools. The difference is night and day. This reduces cognitive load and makes sure everyone's on the same page. You shouldn't have to reinvent the structure every time. We had a template in Notion. For Tandem, we use Google Docs templates, and at Docler, we had Confluence. The tool doesn't matter as much as the consistency. Technical specifications should be based on a standard template. Having a standard template also means reviewing specs is easier. You know where to look for the problem statement, the requirements, the risks. You're not hunting through a free-form essay trying to figure out basic information. Älä pelkää jakaa omasi laajemmalle yleisölle. Tiedän, että on pelottavaa laittaa ideasi ulos, mutta läpinäkyvyydellä on valtavia etuja. Muut joukkueet saattavat löytää, että he ratkaisevat samankaltaisia ongelmia. Joku eri pystysuorasta voi olla kriittinen konteksti, jota kaipaat. Serendipity tapahtuu, kun tieto on julkista. Make all proposals publicly available. All specs were in a shared Notion space that anyone in engineering could read. The number of times someone from a completely different squad dropped a comment that changed the whole approach was remarkable. Tämä palvelee monia tarkoituksia: se auttaa muita oppimaan, se kannustaa yhteistyöhön, se tekee ihmisistä tietoisia siitä, mitä rakennetaan koko organisaatiossa. istuntoja, joissa ihmiset esittelevät ehdotuksia ja saavat palautetta toiminnalliselta ryhmältä. Schedule regular review sessions of critical proposals. Arkkitehtuurin tarkastelu » Ylistä suuria ehdotuksia julkisesti. Tunnusta kaikki osallistujat, vaikka he olisivat jättäneet vain yhden kommentin. Tämä kannustaa yhteistyökulttuuriin. Olen nähnyt tiimejä, joissa ihmiset pelkäsivät kommentoida eritelmiä, koska he ajattelivat, että heidät nähdään estäjinä. Se on myrkkyä. Haluat ihmisten tuntevan, että heidän panoksensa arvostetaan, vaikka se olisi kriittistä palautetta. Tell people they're doing great. When someone writes a particularly good spec, I call it out in a public channel. Se kestää viisi sekuntia ja se saa ihmiset tuntemaan olonsa hyvältä tekemästään työstä. "Tämä Alexin spesifikaatio on erinomainen esimerkki monimutkaisen ehdotuksen rakenteesta - tarkista se viittaukseksi." Spektri on työtä Tässä on viimeinen ajatukseni, ja se on luultavasti tärkein asia koko artikkelissa: kirjoittaminen spec IS tekee työtä. Liian monet insinöörit käsittelevät spesifikaatiota ylipäätä ennen Se on taaksepäin. Spec on missä teet vaikein ajattelu. Se on missä löydät mitä et tiedä. Se on missä löydät tappavia vikoja ennen kuin ne tulevat tuotantotapahtumiin. ”Todellista työtä” Parhaat spesifikaatiot, jotka olen kirjoittanut, ovat olleet yhteistoiminnallisia, iteratiivisia ja joskus kiistanalaisia. Niitä on merkitty kymmeniä kommentteja. Ne ovat käyneet läpi useita tarkistuksia. He ovat pakottaneet minut harkitsemaan uudelleen oletuksia, joita en edes tiennyt tekeväni. Ja jokainen niistä teki täytäntöönpanosta sujuvampaa, nopeampaa ja onnistuneempaa kuin se olisi muuten ollut. So the next time you're tempted to skip the spec and just start coding, resist. Open up that document. Start with the problem. Work through the details. Invite smart people to poke holes in your logic. Iterate. Your future self — and your on-call rotation — will thank you. My . It captures most of the ideas discussed here. If your organisation doesn't have a technical proposal template yet, use this as a starting point. product proposal template is available on GitHub product proposal template is available on GitHub