عند كتابة وثائق المنتج أو الوثائق التقنية، من الضروري هيكلة المحتوى بوضوح وتقديمه بصريًا بطريقة بديهية. يساعد هذا القراء على استيعاب النقاط الرئيسية بسرعة ويقلل من الجهد المطلوب لفهم المحتوى.
أبيدوج (Apidog)، كأداة لإدارة واجهات برمجة التطبيقات (API)، لا يتيح فقط إدارة وثائق API بكفاءة، بل يسمح أيضًا للفرق بإنشاء وثائق منتجات احترافية باستخدام صيغة Markdown المرنة. تم بناء وثائق مساعدة Apidog للمستخدمين باستخدام ميزات Markdown الخاصة بـ Apidog.
فيما يلي 10 نصائح عملية لكتابة وثائق المنتج باستخدام Markdown في Apidog.
1. تخصيص عنوان الشريط الجانبي
عند إنشاء مستند Markdown جديد في Apidog، يتم استخدام العنوان الموجود في مستند Markdown افتراضيًا كعنوان للشريط الجانبي، كما هو موضح أدناه:
إذا كنت تريد أن يكون عنوان الشريط الجانبي وعنوان المستند مختلفين، يمكنك تخصيصهما بشكل منفصل.
على سبيل المثال، يمكنك استخدام "نظرة عامة" كعنوان للشريط الجانبي ومنح المستند عنوانًا أكثر تحديدًا مثل "تصميم واجهات برمجة التطبيقات (APIs) في Apidog".
إليك كيفية إعداد ذلك: داخل مستند Markdown، انقر على "عنوان الشريط الجانبي" وقم بتعديل العنوان.
استخدام عناوين مختلفة للشريط الجانبي والمستند له فائدتان:
- يبقى **عنوان الشريط الجانبي** قصيرًا ومنظمًا، مما يحافظ على نظافة هيكل المجلدات.
- يمكن أن يكون **عنوان المستند** أكثر تفصيلاً ووصفًا للوضوح.
عند مشاركة رابط مستند على منصات مثل Slack، يظهر عنوان المستند في المعاينة، مما يجعل الرابط يبدو أوضح وأسهل في الفهم. إليك مثال على كيفية ظهوره في Slack:
2. اقتباس موارد المشروع والمخططات
يسهل Apidog اقتباس نقاط النهاية والمستندات والمخططات من مشروعك مباشرةً إلى ملفات Markdown.
لاقتباس نقاط النهاية ومستندات Markdown:
- افتح مستند Markdown الخاص بك وانقر على "إدراج نقطة نهاية/Markdown في المشروع".
- اختر المورد الذي تريد إدراجه (نقطة نهاية أو مستند Markdown).
سيتم ربط المحتوى المقتبس تلقائيًا بالمورد المستهدف في المشروع، وسيؤدي النقر عليه في عرض المعاينة إلى الانتقال إلى تلك الصفحة التفصيلية.
لاقتباس المخططات:
- اذهب إلى "إدراج" → "مخطط البيانات".
- اختر المطلوب.
ستتم مزامنة أي تغييرات يجريها فريقك على مخطط البيانات تلقائيًا مع الإصدار المقتبس، مما يضمن بقاء وثائقك محدثة دائمًا. وهذا يمنع الارتباك والأخطاء الناتجة عن المعلومات القديمة.
مثال على الكود:
<DataSchema id="4700682" />
3. التحكم في سلوك الروابط والتنقل
يدعم Apidog Markdown أنواعًا مختلفة من الروابط، ويختلف سلوكها في الوثائق عبر الإنترنت:
- تفتح بعض الروابط في **علامة تبويب جديدة للمتصفح**
- تفتح بعضها في **الصفحة الحالية**
- يقفز البعض الآخر مباشرة إلى **قسم معين** في المستند باستخدام الروابط الثابتة (anchors)
اختيار نوع الرابط الصحيح يجعل التنقل أسهل ويساعد المستخدمين على العثور بسرعة على المعلومات التي يحتاجونها.
أدناه، ستجد تفاصيل حول كيفية عمل كل نوع من الروابط وكيفية تكوينها.
3.1 الروابط التي تفتح في الصفحة الحالية
الروابط المضافة عبر "إدراج نقطة نهاية/Markdown في المشروع" تولد عناوين تبدأ بـapidog://link/pages/...، والتي تفتح في صفحة المتصفح الحالية عند النقر.
على سبيل المثال:
[Overview](apidog://link/pages/990068)
كيفية إعداد ذلك: انقر على زر "إدراج نقطة نهاية/Markdown في المشروع" واختر نقطة النهاية أو المستند المطلوب.
يمكن استخدام الروابط مثل apidog://link/pages/... كروابط عادية في Apidog Markdown. بعد النشر أو المشاركة، يتم تحويلها تلقائيًا إلى عناوين ويب فعلية (مثل https://xxx.apidog.io/xxx) وتدعم الانتقال. على سبيل المثال، في مكون "بطاقة" (Card):
<Card title="Click here" href="apidog://link/pages/990068">
This is a card, click to jump to the target page
</Card>
3.2 الروابط التي تفتح في علامة تبويب جديدة
أي رابط لم يتم إضافته عبر "إدراج نقطة نهاية/Markdown في المشروع" سيفتح في علامة تبويب جديدة للمتصفح افتراضيًا. على سبيل المثال:
[API-design first approach](https://docs.apidog.com/api-design-first-approach-533942m0)
3.3 الروابط الثابتة (Anchor Links) التي تفتح في علامة تبويب جديدة
لربط مباشرة بقسم معين في جدول المحتويات (TOC)، أضف رابطًا ثابتًا (مثل #xxx) إلى نهاية الرابط الخاص بك. على سبيل المثال:
[these methods are the same as those used for inviting users to the team](https://docs.apidog.com/managing-team-members-613028m0#invitation-methods)
3.4 الروابط الثابتة (Anchor Links) التي تفتح في الصفحة الحالية
يمكنك أيضًا استخدام الروابط الثابتة في روابط المشروع الداخلية للانتقال إلى قسم معين داخل المستند نفسه. على سبيل المثال:
[these methods are the same as those used for inviting users to the team](apidog://link/pages/613028#invitation-methods)
الروابط الثابتة مثل apidog://link/pages/613028#invitation-methods تعمل فقط بعد **مشاركة أو نشر** الصفحة. إذا نقرت على هذه الروابط في عميل Apidog قبل النشر، فلن يحدث شيء لأن الرابط لم يتم تحويله إلى مسار ويب يمكن الوصول إليه بعد.
يمكن أن تكون الروابط أعلاه بصيغة Markdown أو HTML، على سبيل المثال:
Link that opens in the current page:
<a href="apidog://link/pages/533969">Design APIs in Apidog</a>
Link that opens in a new tab:
<a href="https://docs.apidog.com/design-apis-in-apidog-533969m0">Design APIs in Apidog</a>
Anchor link (opens in a new tab):
<a href="https://docs.apidog.com/design-apis-in-apidog-533969m0#design-apis">Design APIs in Apidog</a>
Anchor link (opens in the current page):
<a href="apidog://link/pages/533969#design-apis">Design APIs in Apidog</a>`4. إنشاء تخطيطات جنبًا إلى جنب باستخدام الحاويات والأعمدة
عندما تحتاج إلى إظهار الاختلافات بين الإصدارات، أو مقارنات الميزات، أو المعلومات المتوازية، استخدم مكون "Container" المتداخل مع مكون "Column" لإنشاء تخطيط جذاب بصريًا جنبًا إلى جنب.
يسهل هذا التخطيط على القراء مقارنة المحتوى بنظرة سريعة، مما يحسن الوضوح والتواصل.
على سبيل المثال:
إليك كيفية إعداد ذلك: في مستند Markdown، اختر "Container"، ثم "أعمدة متعددة ← عمودين". يمكنك ملء كل عمود بالمحتوى، مثل وصف "الإصدار القديم" و "الإصدار الجديد".
مثال على صيغة Markdown:
<Container>
<Columns>
<Column>
**Old Version**
</Column>
<Column>
**New Version**
</Column>
</Columns>
---
<Columns>
<Column>
Here is the old version content
<DataSchema id="4700681" />
</Column>
<Column>
Here is the new version content
<DataSchema id="8144258" />
</Column>
</Columns>
</Container>💡 في Markdown أعلاه، يشير <DataSchema id="xxxxxx" /> إلى مخطط في المشروع.
5. استخدام مكون الخطوة للإرشاد البصري
للدورات التعليمية العملية أو أدلة الميزات، استخدم مكون "Step" في Apidog Markdown لتقسيم العمليات المعقدة إلى خطوات بسيطة وسهلة المتابعة.
يساعد هذا التصميم الموجه في تقليل ارتباك المستخدم وتحسين معدلات النجاح، خاصة للمستخدمين الجدد أو عند شرح الميزات المعقدة.
يقوم مكون "Step" بترقيم كل خطوة تلقائيًا ويضيف إشارات بصرية لجعل العملية واضحة وجذابة.
على سبيل المثال:
إليك كيفية إعداد ذلك: في مستند Markdown، اختر مكون "Step" وأدخل محتوى مفصلاً لكل خطوة.
مثال على صيغة Markdown:
<Steps>
<Step title="First Step">
These are instructions or content that only pertain to the first step.
</Step>
<Step title="Second Step">
These are instructions or content that only pertain to the second step.
</Step>
<Step title="Third Step">
These are instructions or content that only pertain to the third step.
</Step>
</Steps>
6. تحسين عرض الصور وتخطيطها
في Apidog Markdown، إدراج الصور سهل. يمكنك تحميل الصور من جهاز الكمبيوتر الخاص بك أو لصقها مباشرة في المحرر.
يمكن أن تأتي روابط الصور من شبكات توصيل المحتوى (CDNs) التابعة لجهات خارجية، مثل:
يتم دعم كل من صيغ Markdown و HTML لإدراج الصور، على سبيل المثال:
<img src="https://api.apidog.com/api/v1/projects/544525/resources/350490/image-preview" alt="Apidog"/>باستخدام HTML، يمكنك إضافة أنماط CSS المضمنة، مثل تحديد العرض والارتفاع والتوسيط:
<img src="https://api.apidog.com/api/v1/projects/544525/resources/350490/image-preview" alt="Apidog" style="width: 400px;display: block; margin: 0 auto"/>
// or
<div style="text-align: center;">
<img src="https://api.apidog.com/api/v1/projects/544525/resources/350490/image-preview" alt="Apidog" style="width: 400px;" />
</div>في الوضع الداكن، إذا كانت الصورة تحتوي على شفافية، فسيكون الخلفية افتراضيًا بيضاء. لإزالة الخلفية البيضاء، استخدم CSS المضمن:
<img src="https://api.apidog.com/api/v1/projects/544525/resources/350490/image-preview" alt="Apidog" style="background-color: transparent;"/>لجعل عرض الصورة أكثر احترافية وجمالاً، يمكنك إضافة خلفية للصورة:
<Background>
</Background>أو أضف إطارًا وتسمية توضيحية للصورة:
<Frame caption="Appearance Preferences">
</Frame>7. استخدام الجداول لعرض المعلومات المهيكلة بوضوح
الجداول هي أفضل طريقة لتقديم البيانات المهيكلة. يدعم Apidog Markdown صيغة جدول Markdown القياسية ويسمح بأنماط HTML لجعل الجداول أكثر احترافية وجمالاً.
جدول أساسي:
| Feature | Status | Description |
| --- | --- | --- |
| User Auth | ✅ Done | Supports multiple login methods |
| Data Sync | ⚠️ In Progress | Expected next week |
| Report Export | ❌ Not Started | Planned for Q3 |تعديل عرض العمود: استخدم أنماط HTML المضمنة للتحكم في عرض العمود وتجنب التخطيطات الفوضوية.
| <div style="width: 100px;">Feature</div> | <div style="width: 100px;">Status</div> | <div style="width: 200px;">Descriptions</div> |
| --- | --- | --- |
| User Auth | ✅ Done | Supports multiple login methods |
| Data Sync | ⚠️ In Progress | Expected next week |
| Report Export | ❌ Not Started | Planned for Q3 |
8. استخدام كتل الأكورديون للأسئلة الشائعة
تعد كتل الأكورديون مثالية لتنظيم الأسئلة الشائعة أو التفاصيل غير الأساسية. يسمح هذا الهيكل للقراء بتوسيع المحتوى حسب الحاجة، مما يحافظ على الصفحة مرتبة وغير مزدحمة.
تعد كتل الأكورديون مناسبة بشكل خاص للأسئلة الشائعة، والميزات الاختيارية، والتكوينات المتقدمة، واستكشاف الأخطاء وإصلاحها، وما إلى ذلك، مما يسمح للمستخدمين بالوصول بسرعة إلى المعلومات الرئيسية دون فقدان التفاصيل.
الاستخدام الأساسي:
`<Accordion title="How to reset password?"> 1. Click “Forgot Password” on the login page 2. Enter your registered email address 3. Click “Send Reset Email” 4. Click the reset link in the email and set a new password </Accordion>تعيين الحالة الافتراضية (مطوية):
<Accordion title="Advanced Settings (Optional)" defaultOpen={false}> This section covers advanced but non-essential options for users with special needs. - Custom request headers - Proxy server settings - Performance optimization </Accordion>
9. استخدام الإشعارات لتسليط الضوء على المعلومات الهامة
تعتبر الإشعارات وكتل التمييز رائعة للتأكيد على المعلومات الهامة مثل الملاحظات أو النصائح أو التحذيرات، مما يضمن عدم تفويت المستخدمين للمحتوى الرئيسي.
إشعار:
:::tip
This is a tip notice
:::
:::warning
This is a warning notice
:::
:::caution
This is a caution notice
:::
:::danger
This is a danger notice
:::
:::check
This is a check notice
:::
:::info
This is an info notice
:::
:::note
This is a note notice
:::
كتلة التمييز:
:::highlight purple 💡
This is highlighted content
:::
:::highlight yellow 👋
This is highlighted content
:::
:::highlight orange 🚀
This is highlighted content
:::
:::highlight red 🌟
This is highlighted content
:::
:::highlight gray 🚀
This is highlighted content
:::
:::highlight blue 📌
This is highlighted content
:::
:::highlight green 🔑
This is highlighted content
:::
10. إضافة ميزات التمرير والنسخ للمصطلحات
باستخدام مكون Tooltip، يمكنك إظهار التعريفات عند التمرير فوق النص.
<Tooltip tip="This is a tip!"> Hover here for a tip</Tooltip>باستخدام مكون CopyToClipboard، يمكنك نسخ النص بالنقر.
<CopyToClipboard >Click here to copy text</CopyToClipboard>اجمع بين Tooltip و CopyToClipboard للحصول على "تلميح عند التمرير ونسخ":
<Tooltip tip="This is a tip, and you can copy!"><CopyToClipboard >Click here to copy text</CopyToClipboard></Tooltip>
الخاتمة
باستخدام ميزات Apidog Markdown هذه بمرونة، يمكنك إنشاء وثائق احترافية وجذابة بصريًا. تقلل الوثائق الجيدة من تكاليف التواصل، وتحسن كفاءة التطوير، وتبرز احترافية فريقك وجودة المنتج. الوثائق الممتازة جزء أساسي من تجربة المنتج وتستحق الاستثمار. لمزيد من النصائح، اطلع على وثائق Apidog Markdown.