قضيت ثلاثة أسابيع ونصف في كتابة وثيقة المواصفات الفنية المثالية لعميل لوجستي في دبي. كان كل شيء موجودًا: نقاط نهاية API مُخططة بدقة ، ومخططات قاعدة البيانات مع رموز الحالة المرمزة بالألوان ، وحتى مخططات انسيابية لعملية موافقة المستخدم. عادوا بجملة واحدة: "هذا لطيف ، ولكن أين الجزء الذي يتلقى فيه المستخدم إشعارًا عندما تكون الحزمة الخاصة به جاهزة للتسليم؟"
تنبيه: لقد كان موجودًا بالفعل. مدفونًا تحت ستة أقسام فرعية من "إشعارات التطبيق المحمول الفورية" في الملحق ب.
عندها أدركت أن الوثائق ليست مجرد إظهار ما تعرفه. يتعلق الأمر بجعل العميل يشعر بأنه جزء من العملية.
ابدأ بما *يراه* العميل
غالبية عملائي هنا في أبو ظبي لا يفتحون المواصفات لتصحيح منطق التوجيه. إنهم يهتمون بكيفية تصرف النظام عندما يستخدمه شخص ما. لذلك في هذه الأيام ، أبدأ المواصفات بـ مسارات المستخدم أولاً.
على سبيل المثال، في تطبيق حجز Tawasul Limo ثنائي اللغة، فتحت المستند بسيناريوهات:
- •يختار المستخدم سيارة باللغة العربية، ويملأ النموذج، ويتلقى مكالمة تأكيد باللغة العربية.
- •يتم إرسال سائق عبر Firebase push ، ويتحقق من المسار في التطبيق ، ويحدث حالة الحجز.
هذا يفرض القرارات التقنية في السياق. عندما يرى العميل تدفق الإشعارات قيد التنفيذ، فمن غير المرجح أن يفوته أثناء المراجعة.
قسّم المستند إلى طبقات صغيرة الحجم
يجب أن تخدم المواصفات الفنية سيدين: العميل الذي يريد الوضوح ، والمطور الذي يحتاج إلى الدقة. إليك كيف أقوم بتنظيم المواصفات الخاصة بي:
- بنية عالية المستوى: رسم تخطيطي بأسلوب السبورة للمكدس الكامل. بالنسبة لأنظمة Laravel، أرسم هذا: frontend ← طبقة API (Laravel Sanctum) ← قاعدة البيانات ← الخدمات الخارجية (Firebase, AI APIs).
- الميزات الأساسية: صفحة واحدة لكل وحدة رئيسية. في قسم تحديد هوية الذكاء الاصطناعي لتطبيق Greeny Corner للعناية بالنباتات, غطى حدود تحميل الصور وتوقعات وقت الاستجابة وسلوك تجاوز الفشل.
- التفاصيل الفنية: القسم الأخير، وليس الأول. واجهات برمجة التطبيقات، ومخططات ERD لقاعدة البيانات، وعمليات تكامل الطرف الثالث—مخفية حتى يوقع العميل على تدفق الأعمال.
هذا يضع التعقيد في طبقات. لا يغرق العملاء في هياكل استجابة JSON مقدمًا. إنهم يرون الغابة قبل الأشجار.
استخدم الأمثلة، وليس مجرد تفسيرات
يوافق العملاء بشكل أسرع عندما يمكنهم رؤية التطبيق قيد التشغيل من خلال كلماتك. في مواصفات حديثة لمشروع تجارة إلكترونية ثنائي اللغة في الإمارات العربية المتحدة، أضفت ملحقًا بعنوان "أمثلة لقصص المستخدم".
لإتمام عملية الدفع:
- •السيناريو 1: يحدد العميل طريقة دفع باللغة العربية. يقوم التطبيق بتبديل العملة إلى درهم إماراتي تلقائيًا باستخدام رمز البلد من لغة الهاتف.
- •السيناريو 2: تتم معالجة المبلغ المسترد. يرسل النظام بريدًا إلكترونيًا باللغة الإنجليزية إلى العميل ولكنه يعرض حالة اللغة العربية في سجل طلبات التطبيق.
هذا يعمل بشكل أفضل من "تحديث توطين العملة ديناميكيًا بناءً على تفضيلات المستخدم". يحتاج العملاء إلى أفعال، وليس مجرد صفات.
إصدار التغييرات في الوقت الفعلي
اعتدت على كتابة المواصفات في مستندات Google وإرسال الإصدار 0.1، ثم 0.2، ثم 1.0… وأفقد تتبع التعليقات في منتصف الطريق. في العام الماضي، تحولت إلى استخدام GitHub Pages للمسودات الداخلية.
لماذا؟
- •يحصل كل تغيير على تجزئة commit.
- •يسلط العملاء الضوء على فقرة ويعلقون مباشرة في المتصفح.
- •عندما يقولون "هذا الجزء مربك"، يمكنني ربط الارتباك بقرار الميزة.
- •مقارنات الإصدارات أسهل من التمرير عبر سلاسل WhatsApp.
بالنسبة لمنصة Reach Home Properties العقارية ثنائية اللغة، أدى ذلك إلى تقليل حلقة الملاحظات من 10 أيام إلى 2.
الشيء *الوحيد* الذي يقلل من المراجعات
الاجتماعات. ليست مكالمات Zoom حيث يحدق الجميع في شاشة ثابتة، ولكن جلسات سبورة فعلية شخصية.
إليك ما تغير بالنسبة لي بعد ما تعلمته من 7 سنوات من العمل مع الشركات في الإمارات العربية المتحدة ودول مجلس التعاون الخليجي:
- •أحجز جلسات لمدة 90 دقيقة مع أصحاب المصلحة الرئيسيين، وليس الغوص العميق في التكنولوجيا.
- •أبدأ برسم سير العمل الأساسي للتطبيق، خطأ عن قصد.
- •عندما يصححني العميل، نقوم بإصلاحه معًا.
هذه هي الوثيقة التي تتم الموافقة عليها من المحاولة الأولى. إنهم يمتلكون الأخطاء التي أرتكبها خلال الجلسة لأنهم اكتشفوها.
لماذا يطالب عملاء الإمارات العربية المتحدة بالوضوح ثنائي اللغة
لقد تعلمت بالطريقة الصعبة أن دعم اللغة العربية ليس مجرد ترجمة أزرار. في مواصفات حديثة لمقاول حكومي، أراد العميل أن يقوم التطبيق بتنسيق التواريخ بناءً على لغة الجهاز.
في المواصفات الفنية، أشرت إلى:
- •
moment.locale('ar')مقابل تنسيق التاريخ الإنجليزي - •معالجة النص من اليمين إلى اليسار في مكونات React Native TextInput
- •أحرف خاصة في الأسماء العربية (مثل، "محمد") تحتاج إلى التحقق من صحة UTF-8 في نماذج Laravel
لم يكن هذا ركنًا مقطوعًا. بالنسبة إلى البحث النصي الكامل لـ PostgreSQL للغة العربية والإنجليزية: دليل عملي، قمت بتضمين عينات من استعلامات البحث باللغتين لإظهار منطق الواجهة الخلفية.
يجب ألا تكون ضمان الجودة مرحلة قائمة بذاتها
اجعل العملاء يختبرون المواصفات نفسها. كيف؟
أقوم بتضمين خطة ضمان الجودة في المستند. ليس بعد التطوير—أثناء مرحلة الموافقة الأولية.
فيها:
- •ما هي الحالات الطرفية التي سيختبرها الفريق (مثل، رقم هاتف غير صالح بتنسيق الإمارات العربية المتحدة +97150...)
- •كيف سيتحققون من عمليات تكامل الطرف الثالث (تتبع تحليلات Firebase لإجراءات محددة)
- •من في فريق العميل يمتلك الموافقة (عادةً مدير المنتج + مدير تكنولوجيا المعلومات)
إنه يجبر العميل على المرور ذهنيًا بالعملية قبل كتابة سطر واحد من التعليمات البرمجية.
الفوضى الحتمية
بغض النظر عن مدى مقاومة المواصفات للرصاص، هناك دائمًا العميل الذي يقول "أوه، هل يمكننا أيضًا إضافة هذا هنا فقط" بعد ثلاثة أسابيع من التطوير.
لقد حدث ذلك معي مع شركة لوجستية في دبي تحتاج إلى تحديثات لتطبيق السائق في منتصف المشروع. تضمنت مواصفاتها الأصلية تتبع الموقع الجغرافي، لكنهم أرادوا تحديثات GPS في الوقت الفعلي بدلاً من الفواصل الزمنية المجدولة التي تبلغ 15 دقيقة والتي وثقناها.
لذلك أعدنا كتابة الوثيقة. لهذا السبب أقوم دائمًا بإنشاء نظام إدارة الإصدارات في المواصفات نفسها—يتم تتبع التغييرات، ولا يوجد ارتباك، ولا توجد لحظات "لم تقل هذا أبدًا!".
الأسئلة الشائعة
كيف تتعامل مع نطاق المشروع غير الواضح قبل كتابة المواصفات؟
أنا لا أكتب أي شيء حتى يجيب العميل على ثلاثة أسئلة:
- لماذا هذا المشروع مهم في جملة واحدة؟
- من سيستخدمه يوميًا؟
- ماذا يحدث إذا تم تسليمه بشكل خاطئ؟
بمجرد أن أحصل على ذلك، أقوم بهيكلة المواصفات حول حل مشكلتهم الفعلية.
ما هي الأدوات التي تستخدمها للمواصفات الفنية؟
المكدس الخاص بي هو GitHub Pages لإدارة الإصدارات، وMermaid للرسوم البيانية (وليس Lucidchart)، وPostman لتوثيق API. لم يعد العملاء يحصلون على مستندات Word—إنه بطيء جدًا في التحديث.
كيف تشرح الديون الفنية للعملاء غير التقنيين؟
أقارنها ببناء منزل. إذا أسرعنا في الأساس اليوم لإطلاقه بشكل أسرع، فسنقضي وقتًا أطول في إصلاح الشقوق لاحقًا. معظم أصحاب الأعمال في دول مجلس التعاون الخليجي / الإمارات العربية المتحدة يفهمون هذا التشبيه.
هل يجب على العملاء مراجعة كل قسم من المواصفات؟
بالتأكيد لا. يحتاجون إلى التحقق من:
- •تدفقات المستخدم الأساسية
- •عمليات التكامل الرئيسية (على سبيل المثال، بوابات الدفع ، وواجهات برمجة تطبيقات الرسائل القصيرة)
- •نقاط الامتثال (سيادة البيانات، واللائحة العامة لحماية البيانات, ودعم اللغة العربية إذا كان ذلك مناسبًا)
يتعامل المطورون مع الباقي.
إذا كنت بحاجة إلى مساعدة في هيكلة مستند مواصفات يحصل على الموافقة من المحاولة الأولى—أو إذا كنت في منتصف المشروع وتغرق في التعليقات—احجز استشارة مجانية.
لقد كتبت أكثر من 40 مواصفة لشركات في الإمارات العربية المتحدة ودول مجلس التعاون الخليجي. سأريك كيف تنتقل من "هذا يبدو جيدًا" إلى "هذا هو بالضبط ما نحتاجه".