كيف تكتب توثيقًا أفضل

يساعد التوثيق المستخدمين على فهم كيفية استخدام البرمجيات وتطويرها بفعالية. فهو يسرّع عملية التأهيل من خلال تقديم معلومات منظمة عن المنتج، وبنية النظام، والمنهجيات، وممارسات العمل. كما يُعد مصدر الحقيقة في التحليل والتخطيط والتحديثات المستقبلية.

اتخذت قرارك. لديك فكرة في ذهنك تحتاج إلى مشاركتها. فرقع أصابعك وابدأ الكتابة، لكن كيف، وأين، وباستخدام أي أداة؟

أتخيّل دائمًا أن القارئ شخص لديه فهم ضئيل أو معدوم للموضوع. أحاول استخدام المصطلحات الأقرب إليه، ورسم أمثلة من الواقع تكون منطقية، ومشاركة أكبر قدر ممكن من المعلومات المفيدة، وتكرار نفسي أحيانًا.

عندما يتعلق الأمر بالعمل البرمجي، اختر محررًا يجعل الكتابة سهلة وقراءة المستخدمين له سهلة أيضًا. استخدم خطوطًا وألوانًا وعناوين ونقاطًا وفراغات مختلفة. أبرز التفاصيل المهمة، وقم بإجراء مقارنات، واعرض الجداول أو الصور من حين لآخر.

• محررات WYSIWYG
• محررات Markdown
• تطبيقات القوالب

"ما تراه هو ما تحصل عليه" (WYSIWYG) نوع من برمجيات التحرير يتيح للمستخدمين رؤية المحتوى وتعديله بالشكل الذي سيظهر عليه عند عرضه على واجهة، أو موقع ويب، أو عرض شرائح، أو مستند مطبوع.

الكتابة سلسة ومباشرة. كل تعديل نصي تحتاجه موجود في شريط الأدوات.

من بين هذه الأدوات:

• Microsoft Word
• Apple Pages
• Google Docs
• Zoho Writer
• Notion

تُعد محررات Markdown خيارًا شائعًا لكتابة التوثيق التقني. تعلّمها مرة واحدة واكتب في أي مكان، إذ إن الصياغة نفسها بغض النظر عمّا إذا كنت تكتب ملف readme على GitHub، أو مدونة، أو أي قالب markdown آخر.

# Heading1
## Heading2
### Heading3

Regular Text

[Link](URL)
![image](URL)

- Bullet points
- Bullet points

*italic text*
**bold text**

~~~js
console.log("Code block");
~~~

عادةً ما تتم الكتابة داخل بيئة تطوير متكاملة مثل Visual Studio Code أو Notepad++ أو Vim، أو عبر الإنترنت في أي محرر markdown.

إذا كانت كتابة الكود عبئًا زائدًا عليك، يمكنك استخدام أداة مثل readme.so لتوليد markdown بالنقر على عناصر على الشاشة.

الناتج هو markdown خام يمكنك تنزيله واستخدامه في توثيقك.

هناك قوالب متوفرة على الإنترنت مبنية باستخدام أطر عمل ويب شائعة ومصممة خصيصًا للتوثيق.

من بينها:

• HTML وCSS الأساسيان
• Gatsby
• Next.js
• WordPress وأدوات مشابهة

يمكنك دائمًا بناء موقع التوثيق بنفسك.

كتابة توثيق عالي الجودة يتجاوز مجرد الطرق على لوحة المفاتيح. أحيانًا يكون من الأفضل رسم صورة.

تُعد المخططات والتوثيق مزيجًا مثاليًا، لأنها توضح أين توجد ميزة معينة ضمن البنية، وكيف تعمل، وتتحول، ويتم استهلاكها من قبل كيانات أخرى. تتبع المخططات معايير UML المفهومة لدى المطورين ومحللي الأعمال والمهندسين المعماريين.

الفئات القياسية:

• المخططات الهيكلية
• مخططات السلوك

المخططات الشائعة الاستخدام:

• مخطط تدفق البيانات
• مخطط العلاقات بين الكيانات
• مخطط أصناف UML
• مخطط التسلسل

الأدوات الشائعة لرسم المخططات:

• Lucidchart
• Microsoft Visio
• Draw.io
• Excalidraw

من الممارسات الشائعة تصميم التطبيق باستخدام مخططات على ثلاثة مستويات:

• المستوى 0: نظرة عامة على المشروع لأصحاب المصلحة
• المستوى 1: مخططات منخفضة المستوى وأكثر تقنية
• المستوى 2: مخططات أعمق تصف سلوك المكونات والميزات الفردية

إلى جانب رسم المخططات يدويًا، يمكنك استخدام أدوات "المخططات كشيفرة" لتوليد البنية المعمارية بناءً على الكود لديك:

• Mermaid.js
• PlantUML
• Terrastruct
• Diagrams

من الممارسات الشائعة كتابة تعليقات داخل الكود لشرح ما تقوم به ميزة معينة أو توضيح سبب الحاجة إلى تنفيذ معين. باستخدام الصياغة الصحيحة، يمكنك تحويل تعليقاتك إلى ملخصات.

في JavaScript، يمكنك توليد التوثيق بكتابة / ثم الضغط على Enter. عندها يقوم Visual Studio Code بإعداد غلاف:

/**
 *
 */

بداخله يمكنك وصف الأصناف والواجهات والدوال وخصائصها وأنواع القيم المُعادة كما تشاء.

export const exceptionHandler = (
  error: IHTTPError,
  req: Request,
  res: Response,
  _next: NextFunction
) => {}

الآن أضف التعليقات باستخدام صياغة JSDoc:

/**
 * Global Exception Handler
 * @param error - Custom Error interface containing error name, status code, message and stack trace
 * @param req - Express request object
 * @param res - Express response object
 * @param _next - Express next function
 * @returns HTTP error status code and appropriate message
 */

يمكن إيجاد ميزة مشابهة في لغات برمجة أخرى، مثل C#:

/// <summary>
/// Retrieves current weather
/// </summary>
/// <param name="ID">Item ID</param>
/// <returns>List WeatherForecast</returns>
[HttpGet("GetWeatherForecast")]
public IEnumerable<WeatherForecast> Get(int ID) { }

يمكن لحزمة Typedoc توليد صفحات توثيق منسّقة بناءً على تعليقات JSDoc التي تكتبها في محررك.

npm i typedoc

افتح package.json وأضف سكريبت يشغّل Typedoc.

{
  "scripts": {
    "build": "tsc",
    "type-docs": "typedoc"
  }
}

ثم اضبط نقاط الدخول ومجلد الإخراج في tsconfig.json.

{
  "typedocOptions": {
    "entryPoints": ["src/shared/models/*.ts", "src/services/*.ts"],
    "out": "docs/typedoc"
  }
}

شغّل السكريبت وتصفّح توثيق HTML الناتج.

npm run type-docs

يتيح لك Swagger وصف بنية واجهات برمجة التطبيقات لديك بناءً على مواصفة OpenAPI. ومرة أخرى، أنت تستخدم تعليقات الكود لتوليد صفحات التوثيق.

باستخدام Swashbuckle لـ .NET Core أو Swagger UI Express لـ Node.js، يمكنك توسيع واجهات برمجة التطبيقات لديك من خلال توليد توثيق Swagger بناءً على تعليقاتك.

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo {
        Title = "Your Weather API",
        Description = "Weather API description",
        Version = "v1"
    });

    var fileName = Assembly.GetEntryAssembly().GetName().Name + ".xml";
    var filePath = Path.Combine(AppContext.BaseDirectory, fileName);
    options.IncludeXmlComments(filePath);
});

إذا كنت تستخدم Postman لاختبار واجهات برمجة التطبيقات، فقد لا تكون على علم بأن Postman يأتي مع توثيق واجهات برمجة تطبيقات مدمج.

يمكنك إضافة مزيد من السياق لواجهات برمجة التطبيقات بكتابة وصف لكل مجموعة أو نقطة نهاية. يمكنك أيضًا حفظ أمثلة الاستجابات، وإضافة أمثلة، ونشر توثيقك على الإنترنت.

يجب مراجعة التوثيق وتنقيحه بشكل متكرر. أحيانًا تنسى كيف تعمل ميزة معينة وتحتاج إلى تذكير. لهذا وُجد التوثيق. إذا كنت لا تكتب توثيقًا، ابدأ الآن. وإذا كنت تكتبه، خذ وقتك لضبط الجودة بشكل صحيح.