هذا نص مترجم آليًا وقد يحتوي على أخطاء!
ملخص موجز
- يساعد دليل المستخدم شخصًا محددًا في إنجاز مهمة محددة واحدة.
- كل خطوة تتضمن إجراءً واحدًا وتوضح ما يجب على المستخدم رؤيته بعد ذلك.
- لا يُعتبر الدليل مكتملًا حتى يتبعه شخص غير ملم بالنظام.
من يجب أن يستخدمها؟
اسأل دائمًا أولًا: من الذي سيقوم باستخدام الدليل، وما هي النتائج التي ينبغي أن يحققها بعد الانتهاء؟
الموظف الجديد في مجال تقنية المعلومات والذي يتقن استخدام الطرفية (Terminal) يحتاج إلى دليل مختلف عن المعلم الذي لم يفتح طرفية قط. لذلك قد يتطلب النظام نفسه عدة أدلة. اكتشف ما يعرفه المستلم مسبقًا، وما لديه حق الوصول إليه، والمصطلحات التي لا يعرفها.
ما نوع المستند؟
دليل المستخدم هو دليل إجراءات: فهو يساعد المستخدم على إكمال مهمة واحدة. إنه ليس كتابًا دراسيًا أو مرجعًا أو شرحًا لسبب عمل النظام بالطريقة التي يعمل بها.
| نوع المستند | السؤال الذي يطرحه القارئ | مثال |
|---|---|---|
| دليل الإجراءات | كيف أفعل هذا؟ | كيفية نشر إصدار جديد من التطبيق |
| التدريب | كيف أتعلم هذا؟ | حاويتك الأولى، خطوة بخطوة |
| المرجع | ما هي القيمة أو الأمر؟ | قائمة بالمنافذ والخدمات |
| الشرح | لماذا تعمل بهذه الطريقة؟ | سبب استخدامنا لوسيط عكسي (reverse proxy) |
إذا احتاج المستخدم إلى شرح أثناء العملية، فابقَ مختصرًا وضعه في المكان الذي يحتاج إليه المستخدم.
الأقسام في الدليل التعليمي
| القسم | ما الذي يجيب عليه؟ |
|---|---|
| الأهداف | ماذا حقق المستخدم بعد اتباع الدليل التعليمي؟ |
| قبل البدء | أي صلاحيات، وبرنامجيات، وملفات، ومعارف مسبقة مطلوبة؟ |
| خطوة بخطوة | ماذا يفعل المستخدم، وبأي ترتيب، وماذا يجب أن يراه بعد كل خطوة؟ |
| أمثلة | كيف يبدو الأمر (الأمر البرمجي)، أو الإعداد، أو النتيجة الصحيحة؟ |
| استكشاف الأخطاء وإصلاحها | ماذا يفعل المستخدم عندما لا تكون النتيجة كما هو متوقع؟ |
| إذا اضطررت للتراجع | كيف يتم عكس تغيير كان خاطئاً؟ |
| قائمة التحقق | كيف يتحقق المستخدم من صحة كل شيء في النهاية؟ |
| نصائح مهمة | ماذا تعلمت مما ينبغي للمستخدم معرفته؟ |
| المصادر والتحكم | على أي مصادر، وأي إصدار، وأية بيئة اختبار يعتمد هذا الدليل التعليمي؟ |
كيفية كتابة خطوة
تستند القواعد إلى معايير تعليمات الاستخدام والتوثيق للمستخدمين (IEC/IEEE 82079-1 وISO/IEC/IEEE 26514).
- ابدأ كل خطوة بفعل في صيغة الأمر: “افتح”، “شغّل”، “تحقّق”.
- اجعل هناك إجراءً واحدًا لكل خطوة وتعليمية واحدة لكل جملة. حافظ على الجمل أقل من حوالي 20 كلمة.
- اكتب ما يجب أن يراه المستخدم عند اكتمال الخطوة.
- ضع التحذيرات قبل الخطوة التي تنطبق عليها، وليس بعدها.
- استخدم نفس الكلمة لنفس الشيء طوال الوقت. إذا كانت تُسمى “المساحة الطرفية” في مكان، فلا ينبغي أن تسمى “وحدة التحكم” في مكان آخر.
- وضّح المصطلح التقني في المرة الأولى التي يُستخدم فيها.
خطوة ضعيفة:
قم بإعداد الموقع الإلكتروني وتحقق من أن كل شيء يعمل بشكل صحيح.
خطوة أفضل:3. تحقق من الإعدادات
قم بتشغيل الأمر التالي:
sudo nginx -tيجب أن ترى ما يلي:
nginx: configuration file /etc/nginx/nginx.conf test is successfulإذا رأيت شيئًا آخر، انتقل إلى قسم «استكشاف الأخطاء وإصلاحها».
الأمر والنتيجة المتوقعة والمواضع المستعارة
- ضع الأوامر داخل كتلة أكواد، والنتائج المتوقعة في كتلة منفصلة أدناه.
- استخدم تنسيق الكود لأسماء الملفات ومساراتها والأوامر ضمن النص الجاري، على سبيل المثال
/etc/nginx/. - لا تكتب أبدًا كلمات مرور حقيقية أو مفاتيح أو عناوين داخلية. استعمل مواضع مستعارة واضحة:
<server-ip>و<اسم_المستخدم>و<النطاق>. - حافظ على طول أسطر الأكواد دون نحو ٧٠ حرفًا حتى لا تُقص عند الطباعة الورقية.
استكشاف الأخطاء وإصلاحها
قم ببناء عملية استكشاف الأخطاء والإصلاح حول ما يراه المستخدم:
Egenskap → mulige årsaker → undersøkelse → løsning → bekreftelse
| العَرَض | السبب المحتمل | الفحص | الحل | كيف تعرف أنه تم حله |
|---|---|---|---|---|
| يعرض الموقع الإلكتروني “502 خطأ في البوابة” | الخدمة الخلفية لا تستجيب | شغّل docker compose ps وراجع ما إذا كانت الحاوية قيد التشغيل | ابدأ الحاوية باستخدام docker compose up -d | يتم تحميل الصفحة، ويعرض docker compose ps كلمة «Up» في عمود الحالة (STATUS) |
تُوجد الطريقة المستخدمة في [[طريقة استكشاف الأخطاء وإصلاحها المستوى 1 - الاستكشاف المنهجي للأخطاء|طريقة استكشاف الأخطاء وإصلاحها]].
لقطات الشاشة
استخدم لقطة شاشة فقط عندما تساعد المستخدم على التعرف على نتيجة صحيحة. اقتطع الصورة، وعلّم الجزء الأهم بسهم أو رقم، واحذف المعلومات الحساسة. اكتب نصًا بديلاً يوضح ما تظهره الصورة.
- ويندوز: مفتاح ويندوز + Shift + S
- ماك: Cmd + Shift + 4
طباعة إلى PDF
- افتح الدليل في المعاينة داخل VS Code، أو افتح الملف على GitHub.
- اختر الطباعة. ويندوز: Ctrl + P. ماك: Cmd + P.
- اختر «حفظ كـ PDF».
- تصفّح ملف الـ PDF. تأكد من عدم قطع أي أسطر شيفرة أو جداول أو صور.
احصل على ملاحظات قبل التسليم
دع زميلاً في الدراسة يقرأ الدليل قبل أن تعلن أنه مكتمل. الشخص الذي يقدم الملاحظات يجب أن يجيب بإيجاز ويشير إلى المكان المحدد في النص:
- الدقة: هل هناك خطوات أو ادعاءات تشك فيها؟
- المتلقي والهيكلية: هل من الواضح لمن يخاطب هذا الدليل، وما هي العناصر التي يجب وضعها أولاً؟
- اللغة والإجراء: هل تحتوي كل خطوة على إجراء واحد ونتيجة متوقعة؟ هل تم شرح المصطلحات التقنية؟
- الأمان: هل يوجد شيء لا ينبغي نشره؟
قدم نقطتين قويتين ونقطتي تحسين محددتين. كن لطيفًا ومحددًا: جملة مثل «أقترح عليك شرح وكيل (proxy) في الخطوة 2 لأن …» تكون أكثر فائدة من كلمة «غير واضح». لمزيد من المعلومات حول كيفية تقديم الملاحظات: NDLA كيف نقدم الملاحظات؟.
المهمة 1 - تحسين الخطوات الضعيفة
أعد كتابة كل خطوة بحيث تحتوي على فعل واحد في صيغة الأمر، وإجراء واحد، ونتيجة متوقعة. قسّم الخطوات التي تتضمن عدة إجراءات.
- «يجب الآن تشغيل الحاوية والتحقق من أنها تعمل.»
- «غيّر الإعدادات، وتذكر اختبارها بعد ذلك ثم إعادة تحميلها مرة أخرى.»
- «سجّل الدخول إلى الخادم باستخدام كلمة المرور Sommer2026! وانتقل إلى المجلد الخاص بالموقع الإلكتروني.»
المهمة 2 - اكتب دليلًا موجزًا
اختر مهمة يمكنك القيام بها دون مساعدة، مثل بدء حاوية أو نشر تغيير على موقع ويب.
- اكتب لمن هو موجه الدليل، وما الذي ينبغي أن يكونوا قادرين على فعله بعد ذلك.
- اكتب من ثلاث إلى ست خطوات مع النتيجة المتوقعة.
- أضف سطرًا واحدًا على الأقل في قسم استكشاف الأخطاء وإصلاحها.
- دَع زميلًا لك يتبع الدليل دون أن تشرح له شيئًا. صحح ما توقف عنده.
المزيد للقراءة
- NDLA: إنشاء تعليمات استخدام ومعلومات لمجموعات مستخدمين مختلفة
- NDLA: تطوير مواد التدريب
- المجلس النرويجي للغة: اللغة الواضحة
- ديأتاكسيس حول أنواع الوثائق الأربعة (باللغة الإنجليزية)