door Angela Zhang
als software engineer besteed ik veel tijd aan het lezen en schrijven van ontwerpdocumenten. Na honderden van deze documenten te hebben doorlopen, heb ik uit de eerste hand een sterke correlatie gezien tussen goede ontwerpdocs en het uiteindelijke succes van het project.
Dit artikel is mijn poging om te beschrijven wat een design document geweldig maakt.,
het artikel is opgesplitst in 4 secties:
- waarom een ontwerpdocument schrijven
- Wat moet worden opgenomen in een ontwerpdocument
- Hoe het te schrijven
- het proces eromheen
waarom een ontwerpdocument schrijven?
een ontwerp-doc – ook bekend als een technische specificatie — is een beschrijving van hoe u van plan bent een probleem op te lossen.
er zijn al veel geschriften over waarom het belangrijk is om een ontwerp-doc te schrijven voordat je in codering duikt. Dus alles wat ik hier zal zeggen is:
een design doc is het meest bruikbare hulpmiddel om ervoor te zorgen dat het juiste werk gedaan wordt.,
het belangrijkste doel van een ontwerp doc is om u effectiever te maken door u te dwingen om na te denken over het ontwerp en feedback te verzamelen van anderen. Mensen denken vaak dat het punt van een ontwerp doc is om anderen te leren over een systeem of later dienen als documentatie. Hoewel die gunstige bijwerkingen kunnen zijn, ze zijn niet het doel in en van zichzelf.
als vuistregel geldt dat als u werkt aan een project dat 1 engineer-maand of langer kan duren, u een ontwerp-doc moet schrijven. Maar stop daar niet-veel kleinere projecten kunnen ook profiteren van een mini design doc.
geweldig!, Als je nog steeds leest, geloof je in het belang van design docs. Echter, verschillende engineering teams, en zelfs ingenieurs binnen hetzelfde team, schrijven vaak ontwerp documenten heel anders. Dus laten we praten over de inhoud, stijl en het proces van een goed ontwerp doc.
wat moet in een ontwerpdocument worden opgenomen?
een ontwerpdoc beschrijft de oplossing voor een probleem. Aangezien de aard van elk probleem anders is, natuurlijk zou u uw ontwerp doc anders willen structureren.,
om te beginnen, is het volgende een lijst van secties die u op zijn minst zou moeten overwegen in uw volgende ontwerp doc op te nemen:
titel en personen
de titel van uw ontwerp doc, de auteur(s) (moeten dezelfde zijn als de lijst van personen die aan dit project willen werken), de recensent(s) van het doc (we zullen er meer over vertellen in de sectie proces hieronder), en de datum waarop dit document voor het laatst is bijgewerkt.
overzicht
een samenvatting op hoog niveau die elke ingenieur in het bedrijf zou moeten begrijpen en gebruiken om te beslissen of het nuttig is voor hen om de rest van het document te lezen., Het zou maximaal 3 paragrafen moeten zijn.
Context
een beschrijving van het probleem, waarom dit project noodzakelijk is, wat mensen moeten weten om dit project te beoordelen, en hoe het past in de technische strategie, productstrategie of de kwartaaldoelen van het team.,
doelen en niet-Doelen
de sectie doelen moet:
- beschrijf de door de gebruiker aangestuurde impact van uw project-waar uw gebruiker een ander engineeringteam of zelfs een ander technisch systeem kan zijn
- specificeer hoe u succes kunt meten met behulp van metrics — bonuspunten als u kunt linken naar een dashboard dat deze metrics volgt
Niet — doelen zijn even belangrijk om te beschrijven welke problemen u niet zult oplossen, zodat iedereen op dezelfde pagina zit.,
mijlpalen
een lijst van meetbare controlepunten, zodat uw PM en de manager van uw manager het kunnen afromen en ruwweg weten wanneer verschillende delen van het project zullen worden gedaan. Ik moedig u aan om het project op te splitsen in belangrijke gebruikersgerichte mijlpalen als het project meer dan 1 maand lang is.
gebruik kalenderdata zodat u rekening houdt met ongerelateerde vertragingen, vakanties, vergaderingen, enzovoort., Het zou er ongeveer zo uit moeten zien:
Start Date: June 7, 2018Milestone 1 — New system MVP running in dark-mode: June 28, 2018Milestone 2 - Retire old system: July 4th, 2018End Date: Add feature X, Y, Z to new system: July 14th, 2018
voeg een subsectie hier als de ETA van sommige van deze mijlpalen verandert, zodat de stakeholders gemakkelijk de meest actuele schattingen kunnen zien.
bestaande oplossing
naast het beschrijven van de huidige implementatie, moet u ook door een voorbeeld flow op hoog niveau lopen om te illustreren hoe gebruikers met dit systeem omgaan en/of hoe gegevens er doorheen stromen.,
een gebruikersverhaal is een geweldige manier om dit te framen. Houd er rekening mee dat uw systeem verschillende soorten gebruikers met verschillende use cases kan hebben.
voorgestelde oplossing
sommige mensen noemen dit de sectie technische architectuur. Nogmaals, probeer door een gebruikersverhaal te lopen om dit te concretiseren. Voel je vrij om veel sub-secties en diagrammen op te nemen.
geef eerst een groter beeld en vul vervolgens veel details in. Streef naar een wereld waar je dit kunt schrijven, neem dan een vakantie op een verlaten eiland, en een andere ingenieur in het team kan het gewoon lezen en implementeren van de oplossing zoals u beschreven.,
alternatieve oplossingen
Wat hebt u nog meer overwogen bij het bedenken van de bovenstaande oplossing? Wat zijn de voor – en nadelen van de alternatieven? Heb je overwogen het kopen van een 3rd-party oplossing — of met behulp van een open source Een — dat dit probleem oplost in tegenstelling tot het bouwen van uw eigen?
testbaarheid, Monitoring en waarschuwing
Ik vind het leuk om deze sectie op te nemen, omdat mensen dit vaak als een bijzaak behandelen of het allemaal overslaan, en het komt bijna altijd terug om ze later te bijten als dingen breken en ze hebben geen idee hoe of waarom.,
Teamoverschrijdende Impact
Hoe zal deze toename van de belading en dev-ops?
hoeveel geld kost het?
veroorzaakt het enige latentie regressie naar het systeem?
toont het beveiligingsproblemen?
Wat zijn enkele negatieve gevolgen en bijwerkingen?
Hoe kan het support team dit communiceren met de klanten?
Open vragen
open vragen waar u niet zeker van bent, controversiële beslissingen waar u lezers op wilt laten meewegen, suggesties voor toekomstig werk, enzovoort. Een tong-in-Wang naam voor deze sectie is de “bekende onbekenden”.,
gedetailleerde Scoping en tijdlijn
Deze sectie wordt meestal alleen gelezen door de ingenieurs die aan dit project werken, hun tech leads en hun managers. Daarom is dit gedeelte aan het einde van de doc.
in wezen is dit de uitsplitsing van hoe en wanneer u van plan bent om elk deel van het project uit te voeren. Er is veel dat gaat in scoping nauwkeurig, dus u kunt dit bericht lezen om meer te leren over scoping.
Ik heb de neiging om deze sectie van de design doc ook te behandelen als een lopende project taak tracker, dus ik update dit wanneer mijn scoping schatting verandert., Maar dat is meer een persoonlijke voorkeur.
hoe het te schrijven
nu we hebben gesproken over wat er in een goed ontwerp doc past, laten we het hebben over de schrijfstijl. Ik beloof je dat dit anders is dan je Engelse les op school.
schrijf zo eenvoudig mogelijk
probeer niet te schrijven zoals de academische papers die je hebt gelezen. Ze zijn geschreven om tijdschriftrecensenten te imponeren. Uw doc is geschreven om uw oplossing te beschrijven en feedback te krijgen van uw teamgenoten., U kunt duidelijkheid bereiken door gebruik te maken van:
- eenvoudige woorden
- korte zinnen
- lijsten met opsommingstekens en/of genummerde lijsten
- Concrete voorbeelden, zoals “gebruiker Alice verbindt haar bankrekening, dan …”
veel grafieken en diagrammen toevoegen
grafieken kunnen vaak nuttig zijn om verschillende mogelijke opties te vergelijken, en diagrammen zijn over het algemeen gemakkelijker te ontleden dan tekst. Ik heb veel geluk gehad met Google tekening voor het maken van diagrammen.,
Pro Tip: vergeet niet om een link toe te voegen aan de bewerkbare versie van het diagram onder de screenshot, zodat u het later gemakkelijk kunt bijwerken wanneer dingen onvermijdelijk veranderen.
inclusief getallen
de schaal van het probleem bepaalt vaak de oplossing. Om reviewers te helpen een idee te krijgen van de toestand van de wereld, moet je echte getallen opnemen zoals # van DB rijen, # van gebruikersfouten, latency — en hoe deze schaalbaar zijn met gebruik. Herinner je je Big-O notaties?
probeer grappig te zijn
een specificatie is geen academische paper. Ook, mensen houden van het lezen van grappige dingen, dus dit is een goede manier om de lezer betrokken te houden., Overdrijf dit niet tot het punt van het wegnemen van de kern idee al.
als je, net als ik, moeite hebt om grappig te zijn, heeft Joel Spolsky (duidelijk bekend om zijn komische talenten…) Deze tip:
een van de makkelijkste manieren om grappig te zijn is om specifiek te zijn wanneer het niet nodig is in plaats van te zeggen “speciale interesses,” zeg “linkshandige avacado boeren.”
Voer de sceptische Test uit
voordat u uw ontwerpdoc naar anderen stuurt om te beoordelen, doe alsof u de reviewer bent. Welke vragen en twijfels heb je over dit ontwerp?, Spreek HEN dan met voorbedachte rade aan.
doe de Vakantietest
Als u nu op een lange vakantie gaat zonder internettoegang, kan iemand in uw team het document lezen en implementeren zoals u bedoeld had?
het belangrijkste doel van een ontwerp doc is niet het delen van kennis, maar dit is een goede manier om te evalueren voor duidelijkheid, zodat anderen je daadwerkelijk nuttige feedback kunnen geven.
proces
Ah ja, het gevreesde P-woord., Ontwerpdocs helpen u feedback te krijgen voordat u veel tijd verspilt met het implementeren van de verkeerde oplossing of de oplossing voor het verkeerde probleem. Er is veel kunst om goede feedback te krijgen, maar dat is voor een later artikel. Voor nu, laten we gewoon specifiek praten over hoe je het ontwerp doc te schrijven en feedback te krijgen voor het.
allereerst moet iedereen die aan het project werkt deel uitmaken van het ontwerpproces. Het is oké als de tech lead uiteindelijk het besturen van een groot deel van de beslissingen, maar iedereen moet worden betrokken bij de discussie en kopen in het ontwerp., Dus de” jij ” in dit artikel is echt een meervoud “jij” dat alle mensen op het project omvat.
ten tweede betekent het ontwerpproces niet dat je naar het whiteboard kijkt en ideeën theoretiseert. Voel je vrij om je handen vuil te maken en prototype potentiële oplossingen. Dit is niet hetzelfde als beginnen met het schrijven van productiecode voor het project voor het schrijven van een ontwerp doc. Doe dat niet. Maar je moet absoluut vrij voelen om een aantal hacky wegwerp code te schrijven om een idee te valideren., Om ervoor te zorgen dat je alleen verkennende code schrijft, maak er een regel van dat geen van deze prototype code wordt samengevoegd tot master.
daarna, als u een idee begint te krijgen over hoe u uw project moet uitvoeren, doet u het volgende:
- vraag een ervaren ingenieur of technisch leider in uw team om uw recensent te zijn. Idealiter zou dit iemand die is goed gerespecteerd en / of bekend met de rand gevallen van het probleem. Koop ze om met boba indien nodig.
- ga naar een vergaderruimte met een whiteboard.,
- beschrijf het probleem dat u aanpakt aan deze ingenieur (dit is een zeer belangrijke stap, sla het niet over!).
- leg dan de implementatie uit die je in gedachten hebt, en overtuig hen ervan dat dit het juiste is om te bouwen.door dit alles te doen voordat u zelfs maar begint met het schrijven van uw design doc kunt u zo snel mogelijk feedback krijgen, voordat u meer tijd investeert en gehecht raakt aan een specifieke oplossing., Vaak, zelfs als de implementatie hetzelfde blijft, is uw recensent in staat om hoekgevallen aan te wijzen die u moet behandelen, mogelijke gebieden van verwarring aan te geven en problemen te anticiperen die u later zou kunnen tegenkomen.
dan, nadat u een ruwe versie van uw ontwerp doc hebt geschreven, laat dezelfde recensent het opnieuw lezen, en stempel het door hun naam toe te voegen als de recensent in de titel en mensen sectie van de ontwerp doc. Dit zorgt voor extra stimulans en verantwoording voor de beoordelaar.,
overweeg in dit verband gespecialiseerde beoordelaars (zoals SREs en security engineers) toe te voegen voor specifieke aspecten van het ontwerp.
zodra u en de recensent(s) aftekenen, kunt u de ontwerpdoc naar uw team sturen voor aanvullende feedback en het delen van kennis. Ik stel voor dat de tijd-bounding deze feedback verzamelen proces tot ongeveer 1 week om langdurige vertragingen te voorkomen. Commit aan het aanpakken van alle vragen en opmerkingen mensen vertrekken binnen die week. Het verlaten van opmerkingen opknoping = slecht karma.,
ten slotte, als er veel onenigheid is tussen u, uw recensent en andere ingenieurs die het doc lezen, raad ik ten zeerste aan om alle twistpunten in het Discussiegedeelte van uw doc te consolideren. Dan, het opzetten van een vergadering met de verschillende partijen om te praten over deze meningsverschillen in persoon.
wanneer een discussiethread meer dan 5 commentaren lang is, is het overschakelen naar een persoonlijke discussie meestal veel efficiënter. Houd er rekening mee dat u nog steeds verantwoordelijk bent voor het maken van de laatste oproep, zelfs als iedereen niet tot een consensus kan komen.,
In een gesprek met Shrey Banga onlangs over dit, leerde ik dat Quip heeft een soortgelijk proces, behalve in aanvulling op het hebben van een ervaren ingenieur of tech lead in uw team als een recensent, ze suggereren ook dat een ingenieur in een ander team beoordelen van de doc. Ik heb dit niet geprobeerd, maar ik kan zeker zien dat dit helpt om feedback te krijgen van mensen met verschillende perspectieven en de Algemene leesbaarheid van de doc te verbeteren.
als je al het bovenstaande hebt gedaan, tijd om aan de slag te gaan met de implementatie!, Voor extra brownie points, behandel deze design doc als een levend document terwijl je het ontwerp implementeert. Werk het doc bij elke keer dat u iets leert dat ertoe leidt dat u wijzigingen aanbrengt in de oorspronkelijke oplossing of uw scoping bijwerkt. Je zult me later dankbaar zijn als je de dingen niet steeds opnieuw hoeft uit te leggen aan al je stakeholders.
tot slot, laten we echt meta voor een seconde: hoe evalueren we het succes van een design doc?
mijn collega Kent Rakip heeft hier een goed antwoord op: een ontwerpdoc is succesvol als de juiste ROI van het werk wordt gedaan.,de ts van de technische architectuur
- Je krijgt feedback van reviewers die
Xis het meest risicovolle deel van de voorgestelde architectuur - U besluit te implementeren
Xeerste om risico ‘ s uit het project - 3 dagen later, je om erachter te komen dat
Xis niet mogelijk, of veel moeilijker dan u oorspronkelijk van plan - U besluiten om te stoppen met het werken aan dit project en prioriteit geven aan andere werken in plaats
Aan het begin van dit artikel, we zeiden het doel van een ontwerp doc is ervoor te zorgen dat het juiste werk wordt gedaan., In het voorbeeld hierboven, dankzij dit ontwerp doc, in plaats van potentieel maanden te verspillen om dit project later af te breken, heb je slechts 8 dagen doorgebracht. Lijkt me een behoorlijk succesvol resultaat.
laat hieronder een reactie achter als u vragen of feedback hebt! Ik zou ook graag horen hoe je documenten anders ontwerpt in je team.
krediet geven waar krediet verschuldigd is, heb ik veel van het bovenstaande geleerd door samen te werken met een aantal ongelooflijke ingenieurs bij Plaid (we nemen aan! Kom ontwerpen en bouwen een aantal zoete technische systemen met ons) en Quora.,
als je dit bericht leuk vindt, VOLG ME dan op Twitter voor meer berichten over engineering, processen en backend systemen.