Протягом років я читала: МСК1 . Я написала сотні характеристик. МСК2 . Деякі були блискучими, а деякі жахливими. МSK3 . Більшість - жахливо жахлими. . Різниця між хорошими та поганими характеристиками - це не довжина чи формальність, а МСК6 , і МСК7 - це те, чи це насправді допомагає розробникам побудувати правильну річ, не знущаючи їх до божевілля в процесі .
Ось чому я навчився у Microsoft, що змінило моє ставлення до спеціаліз Це не біблія. Як і будь-який інший інструмент, ви використовуєте його, щоб зробити роботуM SK1 ви додаєте стільки деталей, скільки ви маєте , зацікавлені сторони M SK3 і розробники мають піти наперед . Потім ви пристосовуєте його МSK5 змінюєте його
Погляньте на опис як на священний. МСК0 - незмінний документ, і ви - МСК1 - будуєте неправильну річ ідеально. МSK2 - дуже швидко рухається в неправильному напрямку. М СК3 - сприймайте його як живий інструмент, а ви - ' - будуєте щось, що насправді вирішує проблеми.
Цей гнучкий підхід до спеціаліз створює певний виклик: якщо функція може розвиватися так, як ви її вивчаєте , як же ви її знаєте?
Загалом, це принцип, яким я живу в своїй кар 'єрі. МСК1. Кожен процес, будь то деталі, МСК2, заповнення звітів, МSK3, навіть аналіз кодів і т.д. М СК4 - це налоги. ММК5. Як і всі інші податки, вони мають приносити ціну за гроші, щоб отримати кращий результат, ніж було б без них, або вони мають піти. ММС6. Якщо ваш процес каже, що вам потрібна жорстка система розповідей та згортання графів, але жоден злодій не використовує їх для чогось, окрім знущання вашої команди.
По суті, МСК0 - це інструмент для спілкування, щоб покращити функцію, а не dogматичний ",", що не змінює закону
Гнучкий - це: МСК0 , "-", а також клейкі нотатки, МСК2 . економічна стратегія для створення правильного під час невизначеності. Зразки живуть всередині цієї невизначеності , тому вони також мають бути гнучкими Маніфест гнучкості, перетворюйте це на те, як ви думаєте про будування будь-чого . Думайте про це як про модель розробки продукту
Кожна петля зменшує відстань між “ideaM SK1 і МSK2потрібний”:
Обновлюйте спецификацію після кожного циклу. журнал змін - історія того, що ви вивчили.
Найважливіший принцип для написання описів Почнімо з проблеми, не з розв 'язаннямM SK1
Ця модель проста:
Я ' бачив безліч спеціацій, які стрибають прямо в МSK1 Пользователь натискає на кнопку X, яка називає API Y
Пам 'ятайте, що програмісти - це машини, що будують характеристики. Насправді. (код - це інструмент, що надає характеристики. потрібно робити NOT як це зробити. якщо у вас є людина UX, яка є відповідальною за UX-спек, то dev і вони повинні працювати разом для користувача що може змінитися, і будь-хто має можливість підтримувати зміну ( у спеціалізації МSK1 і мати цей процес перевірки, щоб перевірити ідею
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
Перед тим, як написати одне слово про впровадження, вам потрібно відповісти на одне запитанняM SK1 Чому?
Чому ми це створюємо?
Хороша спецификація починається з:
Це те місце, де більшість спеціаліз йдуть tits-upM SK1 Надто неяскраво і розробники залишають припущення; надто деталізовані, а ви ' займаєтеся мікроменеджментом вибору розробки, який розробці краще підготовані зробити
Трюк полягає в тому, щоб визначити Чого потрібно робити без рецепту Як це трапляється. Наприклад
ХорошаМSK0 "Когда пользователь намагається надіслати бланк з неправильними даними МSK2 він повинен отримати безпосередній зворотній зв 'язок, що вказує на те, які поля потребують виправлення ."
Погана: " Під час подачі бланку МSK2 кнопка відправки МСК3s onClick обладнатель має викликатиvalidateForm М СК4, що повторюється за допомогою бланкаФілдери, перевіряючи кожен поле М סК5Werт проти йогоvalidaції М S К6регексова властивість і якщо щось не вийде, треба викликати showError М ็ С К7 з полем M С К8 ім 'я таvalidaція М Ш К 9 पैраметри повідомлень М В С К 10
Перше вказує мені, яким має бути інтерфейс користувача; Я можу застосувати це в ReactM SK1 Vue , Vanilla JavaScript, чи Carrier pigeon для всіх, що це значитьМSK4 Друге припускає деталі застосування, які можуть бути повністю неправильними для технічного стека або introduce unnecessary constraintsMSC5 Різні люди мають різні переваги часто людина, яка пише спецификацію не є МSK6 не технічна МСК7 не є\ МС К8 не той, хто пише код М С К9 Уявіть себе водієм таксі, і вам не говорять про кінцевий пункт, але кожна зміна гальмівки
## Використовуйте зображення / діаграми потокуM SK1 Перейдете до точки
Пам 'ятаєте, що ви? МСК0. Ви намагаєтесь переконати людей зрозуміти, що Ви? МSK1. Ви запропонуєте. МSK2. Деякі команди включають документи Фіґма. МSK3. Сюжетна дошка. \ / ux \ МSK5 \ Spec ') \ Або зображення інтерфейсу, який створив дизайнер. ♪ МSK7 \ Як і все інше, хоча це - МСК8. Допоки ми не спробуємо його. МСК9. Пропонування допоки вони не пройшли зворотній зв' язок. впевнитись, що вас зрозуміють. Використовуйте будь-які інструменти, які вам потрібні
В вікі морська медуза .js діаграми жахливі для цьогоM SK1 ; пам 'ятайте, що штучний інтелект великий в генеруванні цих даних також, беручи до уваги текстуальний опис
Деякі люди можуть аналізувати написані описи, деякі потребують фотографій та фільмівM SK1
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]
Якщо є одна річ, яку я зрозумів: Ви знайдете способи зламати ваші речі, які ви ніколи не уявили.
Хороша спецификація не лише описує щасливий шлях, але й розглядає
Вам не потрібно розв 'язати всі ці проблеми у спецификації, але ви повинні визнати, що вони існують. МSK2 Ніщо не турбує розробників більше, ніж відкриття на половину шляху до втілення того, що ніхто не думав про те, що відбувається, коли зовнішній інтерфейс API зазнає краху.
Для MANY це ' ймовірно, що вони МSK1 не мають можливості для цього спектру МSK2 Ви можете мати мSK3 технічні характеристики ' які розповідають про деталі втілення та технічні рішення для M' технічних питань мSK6
Ці речі не мають бути задумами, що їх приховують під час перегляду коду. МСК1. Якщо існують певні вимоги до безпеки. МСК2 рівні аутентифікації. , шифрування даних. МSK4 журналування аудиторії. ММК5 описати їх у штрих-коді.
Аналогічно,, якщо є важливі обмеження ефективності M SK1 Цей пошук потрібно завершити під 200 ms для наборів даних до МSK3 мільйона записів МSK4 помістити їх в спецификацію \ . Не дозволити розробникам пригадати не \ МSK7функціональні потреби .
Тут' це шаблон, який я використовую для спеціалізування
Один або два абзаци, які підсумовують те, що ми будуємо і чому це важливо. Ваш директор повинен мати змогу прочитати лише цей розділ та зрозуміти цінність.
Яка є теперішня ситуація? What' what prompted this feature? What have users been asking for? What would help us make more money? ? This helps developers understand the problem space without having been in every product meeting?
Я зрозумів. Історія користувачів з в 'язаними людьми в ,, тож це не просто список перевірок, а жива карта того, як різні види користувачів взаємодіють з системою
Ці історії - це не просто коробка, втілити справжніх людей і їхніми цілями. Ви знаєте вся суть створення цього лайна. Прикріпляючи кожну історію до особистості, ви змушуєте себе думати про реальні моделі використання.1 мотивації,2 обмеження.3 Формат простий, але потужний
Врешті-решт, люди - це чудовий спосіб визначити, яким чином ваше програмне забезпечення може служити різним видам користувачів. Можливо, Алексу потрібен панель приладів для перегляду проблем з безпекою у вашій функції, можливо, Морґону потрібні його обмежені права, щоб зупинити його руйнування речей і т.д.
Як [особистість / тип користувачаM SK1 Я хочу [зробити щось] Так що [Я досягнув певної мети].
І “ тож МSK1 clause is the safeguard against building features nobody needs
МSK0 Персона | Історія МSK2 Чому це важливо | |---------|-------|----------------| МSK0 Алекс (AdministratorM SK2 | Як один Адміністратор, Я хочу надати роль та права щоб Я можу гарантувати безпеку та дотримання даних. M SK1 Захищає неавторизований доступ і робить систему надійною | Джеймі МSK1Підзвичайний użytkownik ) МSK3 Як Незвичайний користувач, Я хочу просту панель щоб Я можу швидко побачити найважливішу інформацію, не переймаючись нею. МSK0 Прия (Power User ) МSK3 Як Пауэр-пользователь, Я хочу створити custom workflows щоб Я можу автоматизувати повторювані завдання і економити час МSK0 Morgan (Новый прихідM SK2 МSK3 Як Новина, Я хочу інструкції та вказівки щоб Я можу вивчати систему, не відчуваючи себе втраченим. M SK1 Поліпшує посадку та пам 'ятку на борту МSK0 Тейлор ( Індикатор Заinteresовані сторони, Я хочу, щоб мені регулярно надсилали повідомлення щоб Я можу відслідковувати прогрес без входу в систему.
Це ваше м 'ясо і картопля. Розіділіть його на відділи, які відповідають за функціюM SK1 Ліберально використовувати підголовки . Вміщувати макети чи дроти, якщо у вас є такі; зображення варте тисячі слів опису
Для кожного завдання, вказуватиM SK1
Цілі ефективності, вимоги до безпекиMSC1 стандарти доступностіMСК2 браузерМСК3 підтримка пристроївМ СК4 Не думайте, що це очевидноM СК6 Але в деяких командах це можуть бути WHOLE OTHER TEAMSMSК7 але не думайтеMсК8 не втратите фокусуМсК9 Якщо одна частина вашого циклу перетворюється на водоспад, тоді виMссК10 втратили гнучкість за визначеннямМссК11
Ця частина така ж важлива, як і те, що
Чому це важливо:
Ось приклади речей, які не входять до переліку.
Якщо хтось стверджує, що один із них не має бути застосований в програмі, то це - розмова, яка варта уваги до початку розробки, а не на половину шляху до її застосування.
Будьте чесними щодо того, чого ви не знаєте. МСК0 не знаємо. МSK1 Обележуйте їх чітко і переконайтесь, що вони будуть відповідані перед запуском розробки. . Ніщо гірше, ніж блокувати розвиток, бо ніхто не вирішував, чи ми робимо мягкі або жорсткі .
Які інші системи/командиM SK1надібності це залежить від? Що потрібно бути готовим перед тим, як розробка може розпочатися ?
Як QA перевірить це?? Ці дані мають бути конкретнимиМSK1 піддатними тесту文амиМСК2 Бонусні бали, якщо вониМ СК3 написані у форматі, який міг би стати автоматизованим тестом.
Тут щось таке, про що не говорять достатньо Спекси можуть мати також баги.
Інспективні помилки трапляються, коли сама спецификація є хибною.
Коли ви знаходите конкретну помилку як програміст, у вас є декілька варіантів:
Це майже завжди правильне рішення.
Посилайте чітке повідомлення тому, хто є власником опису
Зробіть це pisemно. (emailM SK1 квитокМSK2 будь-що) так, що там МSK4 є запис .
Інколи вас спокусує просто будувати те, що виspecіфікували, навіть якщо ви знаєте це. Зробіть це.
Я бачив, як розробники впроваджували описи, які вони знали, що були хибними, тому що " це ' це те, що він сказав робити МSK3 і тоді поводилися здивовані, коли QA відкидає їх або користувачі скаржаться на них.
Винятком є те, якщо ви(МСК0) піднімаєте проблему(МSK1) і вам сказали (МСК2) йти далі,, і ви зрозуміли це написати(ММК3). Тоді все гаразд(М СК4), ви(МСК5) зробили свою due diligence(МКС6).
Якщо ви впевнені, що знаєте, що має казати спецификація, то можете спробувати виправити її самі. Це добре для очевидних помилок у шрифті або в форматуванні, але для важливих змін потрібно домовитися з zainteresowanyми сторонами.
Ніколи мовчки не змінюйте вимоги.
Найкращий спосіб - запобігти конкретним помилкам в першу чергу:
Деякі люди думають, що більше деталей завжди краще.
Якщо ваша спецификація перетворюється на Війна і мир ,
Іншою проблемою є: МСК0 МСК1 Створити систему звітів. МСК2 Правильно. МSK3 Привітаємо за це. . Я ' просто щось підірву і ми ' подивимось, чи воно відповідає тому, що у вас в голові.
Якщо ваш опис може бути повністю зафіксований в одній реченні,
" Ми потребуємо панелі дотиків " це не МSK2 не є обов 'язковою річчю ; це M SK4 це передбачуване рішення MSC5 Можливо, вам дійсно потрібна панель дотиков MST6 але можливо, вам потрібно щось зовсім іншеMST7 Почнемо з проблеми МST8 М ST9 Адміністратор системи може М st10 не бачити, коли є проблеми в системі швидко і легко M ST11
Требування, які змінюються щодня - це: МСК0; не обов 'язки; МСК1; вони; МSK2; хаос; .. Якщо речі змінюються так швидко, - МСК4; ви не розумієте проблеми, - '; ще недостатньо добре розумієте проблему; - МSK6; зупиняйтесь і робіть ще більше розкриттів перед написанням опису; - M SK7;
" Коли ми в МСК1, ми там є, МSK2 ми могли б також МSK3 Ні . Ні, ми не могли б Ми могли б 5 t мSK6 Кожна функція має певну ціну \ . \ Якщо ви хочете додати щось нове \ МSK8 \ напишете для неї окремий опис і упорядковуйте його якнайкраще
Це зміна мислення, яка змінила те, як я пишу описи. Погляньте на вашу точність так само, як і на вихідний код.
Ваші описи мають бути в режимі контролю версії разом з вашим кодом. перевіряйте їх в. Переслідувати зміниM SK2 Написати змістовні коммітаційні повідомлення, коли ви їх оновлюєте . Це створює історію того, як еволюціонували вимоги.
У Microsoft, ми зберігали описи в тих самих reposіtoriaх, що й кодM SK1 Коли опис змінювався , він пройшов через той самий процес перегляду як код МSK3 Це не було МСК4 не бюрократія М СК5 це забезпечувало, щоб кожен розумів, що змінюється і чому M СК6 Навіть відстеження ремісії в Word краще, ніж ніщо. MСК7 ви можете мати MСК8ремісії МсК9 секцію, але не дозволять МСК10 дозволити цьому піти з-під контролю МSК11 Вже багато ремісій після запуску dev означає, що опис не був МСС12 не готовий, коли ви почали будувати ММСК13
Так само, як код потребує рефакторування, так і спектиM SK1 Як ви дізнаєтесь більше під час втілення , спект повинен розвиватися, щоб відобразити це навчання
Знайшов кращий спосіб розв 'язати проблему? Обновлюйте спецификацію, щоб відобразити новий підхід і пояснити, чому ви змінили напрямокM SK1 Открили маргинальний випадок, який ви не мали в роздумі' не обмірковували
Спектр після розробки повинен бути більш витончений, ніж опис перед розробкою.. Якщо це не так.
Спектр - це: МСК0, МСК1, МSK2, коли починається розробка. МСК3, ', тільки МСК5, готовий до цього етапу. МSK7, ММК8, зроблено, коли корабель працює і стає підсобним режимом догляду. .. До того часу МСК10, МКС11 - це живий документ, який еволюціонує з вашим розумінням проблеми
Це не значить, що шкала має змінюватися щодня. МSK1. Головні зміни в правилах потребують обговорення та прийняття. МСК2. Але прояснування. М СК3. Додатні приклади. M СК4. Нещодавно винайдені cases мають бути згортані назад до шкали, як ви їх знайдете.
Подумайте про це таким чином.
Тут МСК0 є чимось, про що "'" недостатньо обговорюють . Ваша спецификація стає основою для всього, що прийде після.
Плани тесту: QA пише тестові випадки на основі спецификаціїM SK1 Якщо ця спецификація застаріла , тести перевіряють неправильну річ МSK3 Ви отримуєте хибні позитивні знаки M SK4 тесті проходять, але функція зламана ) або хибne негативні знакi
Документація: Пацієнтська документація , API доки M SK2 системи допомоги , ваш фантастичний RAG AI спеціаліст з підтримки МSK4 вони всі починаються з опису спецификації MSC5 Якщо опис описує характеристики, які не існують MST6 не існують або пропускають характеристики, що їх роблять M ST7 ваші доки хибні з першого дня M st8
Майбутнє розвиток: Коли комусь потрібно розширити функцію через шість місяців, , вони МSK2 читають спецификацію, щоб зрозуміти, як вона працює \ . Якщо вона не співпадає з реальністю \ МSK5 \ вони \МSK6 \ починають з хибних припущень . \
На борту: Нові члени команди вчаться у системі частково, читаючи описи . Застарілі описи показують їм хибну ментальну модель того, як функції працюють
Ось чому спецификація має залишатися актуальною.
У Microsoft , ми ставили до поновлення спецификацій такі ж важливі речі, як і до оновлення коду . Зміни в спецификаціях пройшли через перевірку МSK2 Вони були перероблені разом з кодом МSK3 Коли змінювалась функція \ , \ оновлювання спецификації не було \ МSK5 \ не було опційним ; \ це було частиною визначення \
Якщо ви зміните код, але не підготуєтесь до оновлення спеціаду, ви створили TECHNICAL DEBT. У майбутньому робота буде повільнішою, бо ніхто не знає, що насправді є теперішнім станом.
# Зв 'язок між схемою та її втіленням
Тут: МСК0 - це те, що молодші розробники часто не розуміють . Це не джерело істини.
Спект вказує вам, що ви намагаєтеся створити. МСК1 Код - це те, що насправді ви створили. МSK2 Ці дві речі повинні узгоджуватись. ММК3 але коли вони не узгоджені. ММСК4 не МСК5 код виграє. МСк6 Ви можете. MМСК7 ви не можете запустити спект. МПСК8 можна запустити код.
Це означає:
© 2026 Scott Galloway — Unlicense — All content and source code on this site is free to use, copy, modify, and sell.