di Angela Zhang
Come ingegnere del software, trascorro molto tempo a leggere e scrivere documenti di progettazione. Dopo aver esaminato centinaia di questi documenti, ho visto in prima persona una forte correlazione tra i buoni documenti di progettazione e il successo finale del progetto.
Questo articolo è il mio tentativo di descrivere ciò che rende grande un documento di progettazione.,
L’articolo è suddiviso in 4 sezioni:
- Perché scrivere un documento di progettazione
- che Cosa da includere in un documento di progettazione
- Come scrittura
- Il processo intorno
Perché scrivere un documento di progettazione?
Un documento di progettazione, noto anche come specifica tecnica, è una descrizione di come si prevede di risolvere un problema.
Ci sono già molti scritti sul perché è importante scrivere un documento di progettazione prima di tuffarsi nella codifica. Quindi tutto quello che dirò qui è:
Un documento di progettazione è lo strumento più utile per assicurarsi che il lavoro giusto venga fatto.,
L’obiettivo principale di un documento di progettazione è quello di renderti più efficace costringendoti a pensare attraverso il design e raccogliere feedback dagli altri. Le persone spesso pensano che il punto di un documento di progettazione sia quello di insegnare agli altri su qualche sistema o servire come documentazione in seguito. Mentre quelli possono essere effetti collaterali benefici, non sono l’obiettivo in sé e per sé.
Come regola generale, se stai lavorando a un progetto che potrebbe richiedere 1 ingegnere-mese o più, dovresti scrivere un documento di progettazione. Ma non fermarti qui: molti progetti più piccoli potrebbero beneficiare anche di un mini design doc.
Grande!, Se stai ancora leggendo, credi nell’importanza dei documenti di progettazione. Tuttavia, diversi team di ingegneri e persino ingegneri all’interno dello stesso team, spesso scrivono documenti di progettazione in modo molto diverso. Quindi parliamo del contenuto, dello stile e del processo di un buon documento di design.
Cosa includere in un documento di progettazione?
Un documento di progettazione descrive la soluzione a un problema. Poiché la natura di ogni problema è diversa, naturalmente vorresti strutturare il tuo documento di progettazione in modo diverso.,
Per iniziare, il seguente è un elenco di sezioni che dovresti almeno considerare di includere nel tuo prossimo documento di progettazione:
Titolo e Persone
Il titolo del tuo documento di progettazione, gli autori(dovrebbero essere uguali all’elenco delle persone che intendono lavorare a questo progetto), i revisori del documento (ne parleremo di più nella sezione Processo sotto) e la data dell’ultimo aggiornamento di questo documento.
Panoramica
Un riepilogo di alto livello che ogni ingegnere dell’azienda dovrebbe comprendere e utilizzare per decidere se è utile per loro leggere il resto del documento., Dovrebbe essere 3 paragrafi max.
Contesto
Una descrizione del problema a portata di mano, perché questo progetto è necessario, ciò che le persone hanno bisogno di sapere per valutare questo progetto, e come si inserisce nella strategia tecnica, strategia di prodotto, o gli obiettivi trimestrali del team.,
Obiettivi e Non di Obiettivi
Gli Obiettivi di sezione:
- descrivere la “user-driven” impatto del progetto — dove l’utente potrebbe essere un altro team di progettazione o anche un altro sistema tecnico
- specificare come misurare il successo utilizzando metriche — punti di bonus se si può collegare a un dashboard che tiene traccia di tali metriche
Non Obiettivi sono ugualmente importanti per descrivere i problemi che non saranno di fissaggio in modo che tutti siano sulla stessa pagina.,
Milestones
Un elenco di checkpoint misurabili, in modo che il tuo PM e il manager del tuo manager possano scremarlo e sapere approssimativamente quando verranno eseguite diverse parti del progetto. Ti incoraggio a suddividere il progetto in importanti traguardi rivolti agli utenti se il progetto dura più di 1 mese.
Usa le date del calendario in modo da prendere in considerazione ritardi non correlati, vacanze, riunioni e così via., Dovrebbe essere qualcosa come questo:
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
Aggiungi un sottosezione qui se l’ETA di alcuni di questi milestone modifiche, così i partecipanti possono facilmente vedere le più up-to-data stimata.
Soluzione esistente
Oltre a descrivere l’implementazione corrente, si dovrebbe anche camminare attraverso un flusso di esempio di alto livello per illustrare come gli utenti interagiscono con questo sistema e / o come i dati fluiscono attraverso di esso.,
Una storia utente è un ottimo modo per inquadrare questo. Tieni presente che il tuo sistema potrebbe avere diversi tipi di utenti con diversi casi d’uso.
Soluzione proposta
Alcune persone chiamano questa sezione Architettura tecnica. Ancora una volta, prova a passare attraverso una storia utente per concretizzare questo. Sentitevi liberi di includere molte sottosezioni e diagrammi.
Fornire prima un quadro generale, quindi compilare molti dettagli. Obiettivo per un mondo in cui è possibile scrivere questo, poi prendere una vacanza su qualche isola deserta, e un altro ingegnere del team può solo leggerlo e implementare la soluzione come descritto.,
Soluzioni alternative
Cos’altro hai considerato quando hai trovato la soluzione sopra? Quali sono i pro ei contro delle alternative? Hai preso in considerazione l’acquisto di una soluzione 3rd-party — o l’utilizzo di uno open source — che risolve questo problema invece di costruire il proprio?
Testabilità, monitoraggio e avviso
Mi piace includere questa sezione, perché le persone spesso trattano questo come un ripensamento o saltano tutto insieme, e quasi sempre torna a morderli più tardi quando le cose si rompono e non hanno idea di come o perché.,
Impatto cross-team
In che modo questo aumenterà il carico su chiamata e dev-ops?
Quanti soldi costerà?
Causa una regressione della latenza al sistema?
Espone eventuali vulnerabilità di sicurezza?
Quali sono alcune conseguenze negative ed effetti collaterali?
Come potrebbe il team di supporto comunicare questo ai clienti?
Domande aperte
Eventuali problemi aperti di cui non si è sicuri, decisioni controverse che si desidera che i lettori valutino, suggeriscano lavori futuri e così via. Un nome tongue-in-cheek per questa sezione è il “incognite note”.,
Scoping dettagliato e Timeline
Questa sezione sarà per lo più letta solo dagli ingegneri che lavorano a questo progetto, dai loro lead tecnologici e dai loro manager. Questa sezione è quindi alla fine del documento.
In sostanza, questa è la ripartizione di come e quando si prevede di eseguire ogni parte del progetto. C’è molto che va in scoping con precisione, in modo da poter leggere questo post per saperne di più su scoping.
Tendo a trattare anche questa sezione del documento di progettazione come un tracker di attività di progetto in corso, quindi lo aggiorno ogni volta che la mia stima di scoping cambia., Ma questa è più una preferenza personale.
Come scrittura
Ora che abbiamo parlato di ciò che va in un buon design doc, parliamo di stile di scrittura. Prometto che questo è diverso dal tuo corso di inglese del liceo.
Scrivi nel modo più semplice possibile
Non provare a scrivere come i documenti accademici che hai letto. Sono scritti per impressionare i revisori delle riviste. Il tuo documento è scritto per descrivere la tua soluzione e ottenere feedback dai tuoi compagni di squadra., È possibile ottenere chiarezza utilizzando:
- Semplici parole
- frasi Brevi
- elenchi Puntati e/o numerati gli elenchi
- esempi Concreti, come “Utente Alice si connette il suo conto in banca, quindi …”
Aggiungere un sacco di grafici e diagrammi
Grafici spesso può essere utile per confrontare le diverse opzioni possibili, e i diagrammi sono generalmente più facili da analizzare un testo. Ho avuto fortuna con Google Drawing per la creazione di diagrammi.,
Suggerimento pro: ricorda di aggiungere un link alla versione modificabile del diagramma sotto lo screenshot, in modo da poterlo aggiornare facilmente in un secondo momento quando le cose inevitabilmente cambiano.
Include numbers
La scala del problema spesso determina la soluzione. Per aiutare i revisori a capire lo stato del mondo, includi numeri reali come # di righe DB, # di errori utente, latenza e come questi si ridimensionano con l’utilizzo. Ricordi le tue notazioni Big-O?
Cerca di essere divertente
Una specifica non è un documento accademico. Inoltre, alla gente piace leggere cose divertenti, quindi questo è un buon modo per mantenere il lettore impegnato., Non esagerare fino al punto di togliere l’idea di base però.
Se tu, come me, hai difficoltà a essere divertente, Joel Spolsky (ovviamente noto per i suoi talenti comici…) ha questo suggerimento:
Uno dei modi più semplici per essere divertente è essere specifico quando non è chiamato Invece di dire “interessi speciali”, diciamo “agricoltori avacado mancini.”
Fai il test scettico
Prima di inviare il tuo documento di progettazione ad altri da rivedere, fai un passaggio fingendo di essere il recensore. Quali domande e dubbi potresti avere su questo design?, Quindi indirizzali preventivamente.
Fai il test di vacanza
Se fai una lunga vacanza ora senza accesso a Internet, qualcuno del tuo team può leggere il documento e implementarlo come previsto?
L’obiettivo principale di un documento di progettazione non è la condivisione della conoscenza, ma questo è un buon modo per valutare per chiarezza in modo che altri possano effettivamente darti un feedback utile.
Processo
Ah sì, la temuta P-word., I documenti di progettazione ti aiutano a ottenere feedback prima di perdere un po ‘ di tempo a implementare la soluzione sbagliata o la soluzione al problema sbagliato. C’è un sacco di arte per ottenere un buon feedback, ma questo è per un articolo successivo. Per ora, parliamo solo specificamente di come scrivere il documento di progettazione e ottenere feedback per questo.
Prima di tutto, tutti coloro che lavorano al progetto dovrebbero far parte del processo di progettazione. Va bene se il lead tecnologico finisce per guidare molte delle decisioni, ma tutti dovrebbero essere coinvolti nella discussione e acquistare nel design., Quindi il” tu “in questo articolo è un” tu ” davvero plurale che include tutte le persone del progetto.
In secondo luogo, il processo di progettazione non significa che stai fissando le idee teorizzanti della lavagna. Sentiti libero di sporcarti le mani e prototipare potenziali soluzioni. Questo non è lo stesso che iniziare a scrivere codice di produzione per il progetto prima di scrivere un documento di progettazione. Non farlo. Ma dovresti assolutamente sentirti libero di scrivere un codice usa e getta hacky per convalidare un’idea., Per assicurarti di scrivere solo codice esplorativo, fai in modo che nessuno di questo codice prototipo venga unito al master.
Dopo di che, come si inizia ad avere qualche idea di come andare circa il vostro progetto, effettuare le seguenti operazioni:
- Chiedere un ingegnere esperto o tech lead sul tuo team di essere il vostro revisore. Idealmente questo sarebbe qualcuno che è ben rispettato e / o familiare con i casi limite del problema. Corromperli con boba se necessario.
- Entra in una sala conferenze con una lavagna.,
- Descrivi il problema che stai affrontando a questo ingegnere (questo è un passo molto importante, non saltarlo!).
- Quindi spiega l’implementazione che hai in mente e convincili che questa è la cosa giusta da costruire.
Fare tutto questo prima ancora di iniziare a scrivere il tuo documento di progettazione ti consente di ottenere un feedback il prima possibile, prima di investire più tempo e attaccarti a qualsiasi soluzione specifica., Spesso, anche se l’implementazione rimane la stessa, il tuo recensore è in grado di indicare i casi d’angolo che devi coprire, indicare eventuali potenziali aree di confusione e anticipare le difficoltà che potresti incontrare in seguito.
Quindi, dopo aver scritto una bozza approssimativa del documento di progettazione, chiedi allo stesso revisore di leggerlo di nuovo e stampalo aggiungendo il loro nome come revisore nella sezione Titolo e persone del documento di progettazione. Questo crea ulteriore incentivo e responsabilità per il revisore.,
A tale proposito, considerare l’aggiunta di revisori specializzati (come SREs e ingegneri della sicurezza) per aspetti specifici del progetto.
Una volta che tu e il revisore(s) firmate, sentitevi liberi di inviare il documento di progettazione al vostro team per ulteriori feedback e condivisione delle conoscenze. Suggerisco di limitare il tempo di questo processo di raccolta del feedback a circa 1 settimana per evitare ritardi prolungati. Impegnarsi ad affrontare tutte le domande e commenti persone lasciano entro quella settimana. Lasciando commenti appesi = bad karma.,
Infine, se c’è molta contesa tra te, il tuo recensore e altri ingegneri che leggono il documento, consiglio vivamente di consolidare tutti i punti di contesa nella sezione di discussione del tuo documento. Quindi, organizza un incontro con le diverse parti per parlare di questi disaccordi di persona.
Ogni volta che un thread di discussione è più lungo di 5 commenti, passare a una discussione di persona tende ad essere molto più efficiente. Tieni presente che sei ancora responsabile di effettuare la chiamata finale, anche se tutti non possono raggiungere un consenso.,
Nel parlare con Shrey Banga di recente su questo, ho imparato che Quip ha un processo simile, tranne che oltre ad avere un ingegnere esperto o un tecnico nella tua squadra come recensore, suggeriscono anche di avere un ingegnere in una squadra diversa rivedere il documento. Non ho provato questo, ma posso certamente vedere questo aiutare a ottenere feedback da persone con prospettive diverse e migliorare la leggibilità generale del documento.
Una volta fatto tutto quanto sopra, è ora di iniziare l’implementazione!, Per ulteriori punti brownie, considera questo documento di progettazione come un documento vivente mentre implementi il progetto. Aggiorna il documento ogni volta che impari qualcosa che ti porta a apportare modifiche alla soluzione originale o ad aggiornare l’ambito. Mi ringrazierai più tardi quando non dovrai spiegare le cose più e più volte a tutti i tuoi stakeholder.
Infine, prendiamo davvero meta per un secondo: come valutiamo il successo di un documento di progettazione?
Il mio collega Kent Rakip ha una buona risposta a questo: un documento di progettazione ha successo se viene eseguito il giusto ROI di lavoro.,ts di architettura tecnica
X è il più rischioso parte del progetto di architetturaX prima di ridurre i rischi del progettoX non è possibile, o molto più difficile di quanto originariamente previstoAll’inizio di questo articolo, abbiamo detto che l’obiettivo di un progetto doc è di assicurarsi che il lavoro viene fatto., Nell’esempio sopra, grazie a questo documento di progettazione, invece di sprecare potenzialmente mesi solo per interrompere questo progetto in seguito, hai trascorso solo 8 giorni. Mi sembra un risultato abbastanza positivo.
Si prega di lasciare un commento qui sotto se avete domande o commenti! Mi piacerebbe anche sapere come si progettano i documenti in modo diverso nella tua squadra.
Dando credito dove il credito è dovuto, ho imparato molto di quanto sopra lavorando a fianco di alcuni ingegneri incredibili a Plaid (stiamo assumendo! Vieni a progettare e costruire alcuni sistemi tecnici dolci con noi) e Quora.,
Se ti piace questo post, seguimi su Twitter per ulteriori post su ingegneria, processi e sistemi di backend.