Як писати круті технічні вимоги?

Нещодавно мене запитали як я пишу технічні вимоги, документацію, які інструменти і діаграми використовую. Як завжди, я вважаю, що інструменти зовсім не важливі, куди важливіша людина котра цими інструментами буде користуватися.

🗒️ Почніть з того, що будь-який документ це формат передачі інформації. Ви пишете, малюєте чи будуєте клікабельний прототип, щоб передати якусь інформацію до іншої людини котра прочитає цей документ. Тому найважливіше мати гарне розуміння яку саме інформацію ви хочете передати, і правильну структуру цієї інформації у вашій голові.

Тут я не можу дати вам порад як цього досягнути окрім однієї, розібратися і розуміти як те, що ви збираєтесь описати повинно працювати 💻 , або вже працює. Ви можете описати тільки те, що ви дійсно розумієте.

Тому не так важливо, який інструмент, чи тип діаграми ви будете використовувати для документування, якщо ви зробили погану структуру цієї інформації й загальний аналіз того, що ви хочете донести до іншої людини.

Коли ви точно знаєте, що ви хочете донести до іншої людини, правильний формат документа з’явиться сам.

❓Для того, щоб зрозуміти як працює будь-яка технічна система, ви повинні розібратися в наступних речах:

• З яких складових частин вона складається
• Як ці частини взаємодіють між собою?
• Які стани цих частин бувають
• Як вони працюють в не звичайних умовах: коли даних немає чи сталася якась помилка?
• Чи є якісь чисельні ліміти у цих об'єктів? Кількість символів у формі. Кількість контактів на сторінці. Якщо кількість об'єктів більша, як користувач може передивитися їх усі? Якщо кількість більша ніж ліміт, що станеться?

Коли ви аналізуєте чи робите архітектуру будь-якого проєкту це найважливіші речі. Це саме ті речі, котрі дадуть вам комплексне уявлення про роботу системи, і що саме описувати.

⚙️ Усі ці питання добре накладаються на усю систему в цілому, так і на окремі її частини. Наприклад:

• Якась фронтендна фіча складається з таких і таких частин. Вони повʼязані між собою таким чином, тут у нас буває такий empty state компонента, а тут такі повідомлення о помилках в таких випадках.
• Якийсь бекендний ендпоїнт чи який алгоритм? Складається з таких частин / етапів, таким чином вони повʼязані між собою: також використовується такий метод який ми не покрили у цьому документі. Коли даних немає повертає таку інформацію або робіть ось це, в інших випадках робить ось так. Якщо якийсь партнер не повертає дані робить ось так.

Як ви бачите зараз я тільки накидав якийсь безсенсовий приклад, але підставивши туди свої дані ви вже отримаєте опис з достатньо великою кількістю edge case'ів і варіантів що можна описати.

🗯️️️️️️ Чим більше таких питань і допущень ви будете тримати у голові тим краще ви будете розуміти як працює система, так і знаходити якісь недоліки з якими можуть зустрітися ваші користувачі.