Penulisan Spesifikasi dan Penyerahan kepada Kejuruteraan yang Tidak Berdarah

Spesifikasi terakhir anda lapan halaman. Kejuruteraan membukanya sekali pada hari Isnin, mengimbas tajuk-tajuk, dan tidak membukanya semula. Menjelang hari Khamis, dua cerita tersekat kerana tiada siapa yang tahu sama ada eksport itu perlu memasukkan rekod yang diarkibkan. Menjelang semakan sprint seterusnya, 40% kerja telah ditulis semula. Anda dipersalahkan kerana spesifikasi yang terlalu panjang. Kejuruteraan dipersalahkan kerana tidak membaca. Tiada siapa yang membaiki sistemnya.

Itulah gelung itu. Inilah cara memutuskannya.

Mengapa spesifikasi terakhir anda tidak dibaca

Saya telah menyaksikan perkara ini berlaku pada tiga pasukan dalam tahun lalu. Setiap satu mempunyai tindanan berbeza, domain berbeza, corak yang sama: PM menghasilkan spesifikasi yang panjang, kejuruteraan menghasilkan sprint yang panjang, dan jurang antara apa yang ditulis dan apa yang dibina dipenuhi dengan kerja semula.

Nombor 40% kerja semula bukan dari tinjauan. Itulah yang pasukan temui apabila mereka benar-benar mengira. Tarik tiket sprint terakhir anda, tandakan setiap cerita yang berubah skop, mendapat tiket susulan, atau dihantar dengan pepijat yang diketahui yang boleh dikesan kepada "kami tidak tahu perkara itu." Itulah kadar kerja semula anda. Kebanyakan pasukan yang melakukan latihan ini dengan jujur mendapat antara 30 dan 50%.

Spesifikasi itu tidak menyebabkan perkara ini bersendirian. Tetapi spesifikasi adalah tempat termurah untuk memperbaikinya. Kod mahal untuk ditulis semula. Dokumen percuma untuk ditulis semula, dan dokumen 1 halaman ditulis semula jauh lebih banyak daripada yang 8 halaman.

Berikut adalah apa yang kita gantikan dengan novel itu.

Spesifikasi 1 halaman

Tujuh bahagian. Setiap satu mendapat tempatnya. Jika bahagian tidak melakukan kerja sebenar, ia tidak dimasukkan.

# [Nama Ciri]

**Masalah**
Apa yang rosak atau hilang untuk pengguna. Satu ayat. Pengguna sebenar, kesakitan sebenar. Bukan "pengguna tidak boleh melakukan X." Lebih seperti "Wakil jualan tidak boleh mengeksport pipeline mereka untuk dikongsi dengan pengurus sebelum sesi one-on-one, jadi mereka membuat tangkap layar dan menampalnya ke Slack."

**Hipotesis**
Jika kita menghantar [perkara], maka [hasil] akan berlaku, kerana [sebab]. Satu ayat. Inilah pertaruhan kita.

**Metrik Kejayaan**
Satu nombor yang memberitahu kita kita menang. Bukan tiga. Satu. Jadilah spesifik: "30% daripada wakil jualan yang melihat pipeline mereka menggunakan Eksport dalam 14 hari selepas pelancaran." Tambahkan petunjuk awal jika yang lewat mengambil masa terlalu lama untuk dibaca.

**Skop**
Apa yang ada. Senarai titik peluru, maksimum 7 item. Setiap titik peluru adalah sesuatu yang pengguna boleh lakukan atau lihat.

**Anti-Skop**
Apa yang TIDAK ada, walaupun seseorang akan bertanya. Senarai titik peluru. Jadilah spesifik: "Templat eksport tersuai, tidak dalam v1. Eksport berjadual, tidak dalam v1. Penyusunan semula lajur CSV, tidak dalam v1." Inilah bahagian yang menyelamatkan sprint anda.

**Kes Pinggir**
Lima perkara yang akan rosak jika kita tidak memikirkannya sekarang: keadaan kosong, ralat, set data besar, kebenaran, pengeditan serentak. Senaraikan yang sebenar untuk ciri ini.

**Soalan Terbuka**
Keputusan yang belum kita jawab lagi, dengan nama dilampirkan. "Adakah eksport memasukkan tawaran yang diarkibkan?, @ravi untuk mengesahkan dengan operasi jualan menjelang Rabu."

Itu sahaja. Satu halaman. Keseluruhan spesifikasi.

Ciri pembunuh adalah anti-skop. Kebanyakan PM melangkauinya kerana ia terasa negatif atau kerana mereka fikir "jelas kita tidak melakukan X." Ia tidak pernah jelas kepada kejuruteraan. Ia tidak pernah jelas kepada reka bentuk. Ia tidak pernah jelas kepada pihak berkepentingan yang menghantar DM kepada anda pada hari Jumaat bertanya mengapa ciri kegemaran mereka tidak ada. Anti-skop adalah bahagian yang anda tunjuk apabila seseorang cuba mengembangkan kerja di pertengahan sprint. Tanpanya, anda berdebat dari ingatan. Dengannya, anda menunjuk kepada baris yang semua orang tandatangani dua minggu lalu.

Saya pernah menghantar ciri tanpa anti-skop dan terpaksa membina semula aliran eksport dua kali kerana versi pertama mengandaikan data yang tidak ditapis dan versi kedua disesuaikan semula untuk mengendalikan penapis yang disimpan. Dua jurutera, tiga minggu. Semua diselamatkan oleh bahagian anti-skop 4 titik peluru yang mengambil masa 90 saat untuk ditulis.

Ulasan eng pra-spesifikasi (15 minit)

Spesifikasi itu tidak pergi dari komputer riba anda ke Jira. Ia melalui ulasan eng 15 minit dahulu, dan anda membawa draf, bukan dokumen yang telah siap.

Persediaan:

• Siapa: Ketua teknikal, seorang jurutera kanan, anda. Itu sahaja. Belum ada pereka bentuk. Tiada rakan PM. Tiada pengurus.
• Bila: Sebelum anda menunjukkan spesifikasi kepada sesiapa pun. Sebelum reka bentuk bermula. Sebelum pihak berkepentingan memberi pandangan.
• Apa yang anda bawa: Spesifikasi 1 halaman, ditanda DRAF. Bahagian Masalah dan Hipotesis adalah kukuh. Segala-galanya lain adalah umpan.
• Apa yang anda dapat: Senarai kes pinggir yang anda terlepas, gambaran kasar usaha, dan "ini adalah pendekatan yang salah" awal jika ia adalah pendekatan yang salah.

Agenda, disimpan pada nota melekit:

0-2 min:  Masalah + hipotesis (anda bercakap)
2-8 min:  Eng mencari kelemahan dalam skop dan kes pinggir
8-12 min: Eng mencadangkan dua atau tiga arah pelaksanaan
12-14 min: Soalan terbuka, siapa memiliki setiap satu
14-15 min: "Adakah kita baik dari segi arah?", ya/tidak/mungkin

Jika jawapannya adalah "tidak" atau "mungkin," anda tidak menulis lebih banyak spesifikasi. Anda pergi memperbaiki pembingkaian masalah atau pendekatannya. Kebanyakan masalah spesifikasi adalah masalah pembingkaian yang berpakaian kostum.

Sebab ini berfungsi: kejuruteraan yang mengulas spesifikasi separuh matang memberikan anda pemikiran terbaik mereka sebelum mereka berada dalam mod defensif. Sebaik sahaja spesifikasi itu "selesai," ulasan itu bertukar menjadi kritikan terhadap kerja anda. Apabila ia adalah draf, anda adalah pengarang bersama. Jurutera yang sama yang akan menulis ulasan kritis 12 komen di Jira akan sebaliknya berkata "bagaimana jika kita hanya menambahkan bendera ke titik akhir eksport sedia ada?" dan menjimatkan anda seminggu.

Dokumen kickoff

Setelah spesifikasi 1 halaman lulus ulasan pra-spesifikasi dan reka bentuk telah memberi pandangan, anda menulis dokumen kickoff. Inilah yang disematkan dalam saluran pasukan. Ia adalah kontrak.

Empat bahagian, masing-masing ringkas:

Jadual RACI, satu nama per peranan

Jawatankuasa tidak boleh dipertanggungjawabkan. Satu nama boleh.

Jika anda tidak dapat mengisi baris Akauntabel dengan nama tunggal, projek itu belum bersedia untuk dimulakan.

Pencapaian dengan tarikh

Tiga atau empat pencapaian. Tarikh sebenar. Bukan "akhir sprint."

• 14 Mac: Reka bentuk siap, pembangunan bermula
• 21 Mac: Titik akhir bahagian belakang di belakang bendera ciri, ujian dalaman pada persekitaran pementasan
• 28 Mac: Beta dengan 10 pelanggan
• 4 Apr: Hari Demo (tidak boleh diubah)
• 11 Apr: GA

Tarikh demo, tidak boleh diubah

Pilih tarikh. Beritahu pasukan. Beritahu pihak berkepentingan. Beritahu diri sendiri bahawa anda akan menunjukkan apa sahaja yang ada pada tarikh itu, walaupun tidak cantik.

Tarikh demo yang bergerak bukan tarikh demo. Ia adalah aspirasi. Hantarkan apa yang ada. Jika apa yang ada adalah separuh ciri, demonstrasikan separuh ciri dan terangkan apa yang tinggal. Itulah cara kepercayaan dibina. Pasukan yang menunjukkan demo setiap dua minggu walaupun hasilnya kasar sentiasa akhirnya lebih cepat daripada pasukan yang menunjukkan demo apabila ia sudah dipoles.

Kriteria pembunuhan

Inilah bahagian yang tidak mahu ditulis oleh sesiapa dan yang semua orang perlukan.

"Kita akan berhenti membina ini jika: pelanggan beta tidak menggunakan eksport dalam 7 hari selepas pengaktifan, ATAU kependaman bahagian belakang melebihi 800ms pada p95 dengan set data ujian kami, ATAU lebih daripada dua pelanggan melaporkan isu ketepatan data semasa beta."

Tiga syarat. Konkrit. Boleh diukur. Dilakukan sebelum bermula.

Tanpa kriteria pembunuhan, setiap ciri hidup selama-lamanya. Dengannya, pasukan mempunyai perlindungan untuk memanggilnya. Saya telah membunuh dua ciri dalam 18 bulan lalu menggunakan bahagian ini, dan kedua-dua kali jurutera berterima kasih kepada saya. Tiada siapa yang mahu menghabiskan tiga minggu lagi pada sesuatu yang tidak berfungsi. Mereka hanya memerlukan kebenaran, secara bertulis, yang ditetapkan terlebih dahulu.

Loom lebih baik daripada mesyuarat (kebanyakannya)

Mesyuarat penyerahan di mana anda membawa kejuruteraan melalui spesifikasi selama 30 minit? Langkauinya. Rakam Loom 4 minit sebagai gantinya.

Apa yang masuk dalam Loom:

1. Spesifikasi 1 halaman pada skrin, anda berbual mengenainya.
2. Dua aliran demo: laluan gembira dan satu kes pinggir.
3. Tiga perkara yang paling anda jangkakan akan menjadi soalan.
4. Ayat di penghujung: "Letakkan soalan dalam benang, saya akan menjawab menjelang akhir hari."

Apa yang ini berikan kepada anda: kejuruteraan menonton pada kelajuan 1.5x apabila mereka bersedia, bukan apabila kalendar anda ada. Soalan masuk dalam benang, yang bermakna semua orang melihat jawapan sekali dan bukannya anda menerangkan perkara yang sama dalam tiga DM Slack. Jurutera baru yang menyertai projek dua minggu kemudian menonton Loom yang sama dan bukannya menarik seseorang ke tepi.

Bila Loom tidak berfungsi: apabila projek itu benar-benar kabur dan pasukan perlu berdebat dengan lantang. Apabila kepercayaan rendah dan async terasa seperti PM sedang bersembunyi. Apabila terdapat pertukaran strategik sebenar yang memerlukan bilik. Untuk kes tersebut, adakan mesyuarat. Untuk segala-galanya lain, gunakan Loom.

Definisi "sudah selesai"

Kriteria penerimaan yang ditulis sebagai "pengguna boleh log masuk" bukan kriteria penerimaan. Ia adalah harapan.

Gunakan Given / When / Then. Contoh konkrit, data sebenar, keadaan sebenar.

Buruk:

Pengguna boleh mengeksport pipeline.

Baik:

Given saya adalah wakil jualan dengan akses lihat ke pipeline saya, And saya telah menggunakan penapis yang menunjukkan hanya tawaran yang dimiliki oleh saya dengan peringkat = "Rundingan," When saya klik Eksport dan pilih CSV, Then fail muat turun bernama pipeline-2026-04-28.csv yang mengandungi tepat tawaran yang kelihatan selepas penapis, dengan lajur: Nama, Peringkat, Jumlah, Tarikh Tutup, Pemilik.

Kes pinggir (keputusan kosong): Jika penapis mengembalikan sifar tawaran, tunjukkan toast: "Tiada tawaran untuk dieksport," dan jangan muat turun fail.

Kes pinggir (set data besar): Jika penapis mengembalikan lebih daripada 10,000 tawaran, baris gilirkan eksport dan emelkan fail apabila siap. Tunjukkan toast: "Eksport dalam baris gilir. Kami akan mengemelnya kepada anda."

Itulah dua minit lagi penulisan. Ia adalah tiga hari perdebatan yang diselamatkan. Jurutera QA membaca ini dan menulis ujian. Jurutera bahagian belakang membaca ini dan mengetahui kontrak titik akhir. Ketua customer success membaca ini dan tahu apa yang perlu diberitahu kepada pelanggan beta. Satu artifak, empat kerja.

Jangan langkau kes pinggir. Kes pinggir adalah tempat tinggalnya kerja semula.

Templat retro selepas penghantaran

Dua puluh minit. Lima soalan. Disiarkan dalam saluran Slack pasukan dalam tempoh seminggu selepas GA.

**[Nama ciri], Retro Selepas Penghantaran**

1. Apa yang tidak jelas dalam spesifikasi?
   (Satu titik peluru setiap orang, tanpa berdebat, hanya menyenaraikan.)

2. Apa yang kita terlepas dalam skoping, apa yang muncul yang tidak kita rancang?
   (Usaha, risiko, kebergantungan, apa sahaja.)

3. Kerja semula apa yang berlaku, dan mengapa?
   (Jadilah spesifik. "Membina semula kegigihan penapis dua kali kerana kami tidak memutuskan tentang URL berbanding storan tempatan cukup awal.")

4. Kes pinggir mana yang menggigit kita?
   (Satu yang kita harap ada dalam spesifikasi dari awal.)

5. Apa yang masuk ke dalam spesifikasi seterusnya?
   (Satu perubahan konkrit kepada templat atau proses.)

, Balasan dalam benang menjelang Jumaat. Saya akan merumuskan dan menyiarkan perubahan spesifikasi seterusnya pada hari Isnin.

Tujuannya bukan menyalahkan. Tujuannya adalah untuk mengevolusi templat. Spesifikasi seterusnya mendapat satu peningkatan. Kemudian yang berikutnya mendapat satu lagi. Enam bulan kemudian, proses spesifikasi pasukan anda jauh lebih baik daripada di mana ia bermula, dan tiada siapa yang terpaksa duduk melalui retro 90 minit untuk sampai ke sana.

Saya menyimpan fail yang saya panggil spec-improvements.md dengan satu titik peluru setiap retro. Ia dua skrin panjangnya selepas setahun. Ia adalah dokumen paling berharga yang saya miliki.

Anti-corak biasa yang perlu diperhatikan

Beberapa corak yang muncul berulang kali. Namakan mereka dengan lantang pada saat anda melihatnya. Mereka mati apabila dinamakan.

• Penyerahan "reka bentuk melempar ke tembok". Reka bentuk selesai, menjatuhkan pautan Figma dalam spesifikasi, menghilang. Kejuruteraan menemui interaksi yang tidak diliputi oleh mock, bertanya kepada reka bentuk, mendapat "gunakan pertimbangan anda." Tiga hari kemudian ia dihantar dengan salah. Penyelesaian: reka bentuk menyertai kickoff. Baris RACI mereka adalah "Dirunding" dengan nama dilampirkan. Mereka sedia untuk soalan interaksi bagi sprint pertama.

• Spesifikasi yang berkembang semasa sprint. Pihak berkepentingan menghantar DM kepada anda pada hari Selasa. "Hei, boleh kita juga tambah X kepada keluaran ini?" Anda berkata ya kerana berkata tidak terasa seperti politik. Menjelang hari Jumaat pasukan sudah ketinggalan. Penyelesaian: anti-skop. Tunjuk padanya. "X ada dalam v2. Saya mencatatnya." Selesai.

• Anti-skop yang hilang. Kejuruteraan membina ciri, kemudian bertanya "bagaimana pula dengan rekod yang diarkibkan?" Anda berkata "soalan yang bagus, mari kita tambahkan." Itulah anti-skop yang meresap kembali sebagai soalan Trojan horse. Penyelesaian: anti-skop ada dalam spesifikasi dari hari pertama. Apa sahaja yang tidak ada dalam senarai dalam skop adalah, secara lalai, di luar.

• Kejutan hari demo. Hari demo tiba. PM tidak melihat binaan sejak hari Isnin. Separuh aliran tidak berfungsi seperti yang dikatakan spesifikasi. Pihak berkepentingan pulang dengan keliru. Penyelesaian: PM melakukan walkthrough peribadi dengan ketua kejuruteraan 24 jam sebelum hari demo. Ketidakpadanan ditangkap apabila ia masih boleh diperbaiki.

Penutup

Spesifikasi adalah kontrak, bukan esei.

Spesifikasi 1 halaman adalah pendek kerana spesifikasi yang pendek dibaca. Ulasan eng pra-spesifikasi adalah 15 minit kerana apa sahaja yang lebih panjang menjadi mesyuarat yang tidak mahu dihadiri oleh sesiapa. Dokumen kickoff mempunyai satu nama per peranan kerana jawatankuasa tidak boleh dipertanggungjawabkan. Loom menggantikan walkthrough kerana penulisan async berkembang dan kalendar mesyuarat tidak. Given/When/Then wujud kerana "pengguna boleh log masuk" telah menghantar seribu log masuk yang rosak.

Anti-skop dan kriteria pembunuhan adalah dua bahagian yang paling banyak dilangkau oleh PM dan yang paling banyak disesali selepas itu. Jangan langkaui mereka. Mereka adalah insurans paling murah yang akan anda beli.

Lebih pendek, lebih tajam, ditandatangani. Itulah keseluruhan permainannya.

Baca Lagi

• Penerangan Kerja Pengurus Produk
• Menjalankan Perancangan Sprint yang Tidak Menyeret
• Komunikasi Roadmap untuk Pasukan Merentas Fungsi
• Bekerja dengan Reka Bentuk: Penyerahan PM dan Pereka Bentuk