كيف تكتب توثيقًا فعالًا لمشروعك المفتوح المصدر؟

مقدمة:

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

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

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

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

خمس نصائح كتابية قابلة للتطبيق

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

1. استخدم صيغة المبني للمعلوم. مثال ذلك «يمكنك تغيير هذه الإعدادات من خلال…» بدل «يمكن تغيير هذه الإعدادات من خلال…».

2. اكتب جملًا قصيرة وبسيطة. ورغم أن تطبيقي Hemingway App وGrammarly غير مفتوحي المصدر، فكلاهما أداة مفيدة.

3. نسّق النص لتسهل قراءته. استخدم العناوين والقوائم النقطية والروابط لتقسيم المعلومات إلى وحدات، بدل الفقرات التفسيرية الطويلة.

4. استخدم العرض البصري. مثّل المعلومات المتعددة الأبعاد بجداول ورسوم توضيحية بدل الاكتفاء بالجمل.

5. اعتنِ بالإملاء والنحو. افحص الأخطاء الطباعية والقواعد دائمًا، دون استثناء، لتصقل النص.

وبتطبيق هذه النصائح باستمرار في الكتابة والتحرير، تحقق هدفين كبيرين: كفاءة التواصل، وبناء الثقة.

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

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

ابدأ بتوثيق «البدء»

بعد إدماج هذه التقنيات الأساسية في كتابتك، خصص أكبر قدر من الوقت لقسم «البدء». فهو أهم الأقسام بفارق كبير، ومثال كلاسيكي لقاعدة 80/20. تصل معظم زيارات المشروع إلى التوثيق، ويصل معظمها إلى هذا القسم. وإذا أُحسن بناؤه، كسبت مستخدمًا جديدًا فورًا؛ وإلا غادر الزائر، وربما لم يعد.

كيف تبني قسمًا جيدًا للبدء؟ أقترح عملية من ثلاث خطوات.

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

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

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

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

ومن الأمثلة الجيدة دليل البدء الخاص بـLinkerd، وهو شبكة خدمات مفتوحة المصدر لكوبرنيتس. أنا مبتدئ في كوبرنيتس، وأقل معرفة بشبكات الخدمات؛ ومع ذلك أكملت الدليل على حاسوبي دون صعوبة كبيرة، وأعطتني التجربة تصورًا عمليًا عن تشغيل شبكة الخدمات.

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

مكونات أساسية أخرى

إلى جانب ضبط قسم البدء وتحسينه بعناية، هناك خمسة مكونات رئيسية لازمة لتوثيق متكامل: التصميم المعماري، ودليل الاستخدام في بيئة الإنتاج، وحالات الاستخدام، والمعلومات المرجعية، وخريطة الطريق.

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

دليل الاستخدام في بيئة الإنتاج: ثمة فرق كبير بين تجربة شيء على حاسوب محمول ونشره في الإنتاج. وإرشاد المستخدم الراغب في توظيف المشروع بجدية أكبر خطوة تالية مهمة. وإظهار المعرفة التشغيلية في الإنتاج وسيلة أيضًا لجذب أوائل العملاء من الشركات، الذين قد تروق لهم وعود التقنية لكنهم لا يعرفون استخدامها في تلك البيئة أو لا يثقون بقدرتهم على ذلك.

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

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

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

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

وملاحظة أخيرة: أدرج جملة واحدة واضحة تبين الترخيص الذي تستخدمه، ربما في قسم البدء أو README أو مكان بارز آخر. فهذه اللمسة الصغيرة تجعل مراجعة المشروع تمهيدًا لتبنيه أكثر كفاءة بكثير للمستخدم النهائي.

خصص 20% من وقتك للكتابة

أوصي عمومًا بتخصيص 10–20% من وقتك للكتابة؛ أي نحو نصف يوم إلى يوم كامل أسبوعيًا إذا كنت تعمل في المشروع بدوام كامل.

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

شكر خاص إلى لوك بيركنز، المدافع عن المطورين في مؤسسة الحوسبة السحابية الأصلية CNCF، على ملاحظاته القيّمة. ظهر المقال أولًا في COSS Media، وأعيد نشره في Opensource.com بإذن.

المراجع

• https://www.grammar-monster.com/glossary/active_voice.htm
• https://www.hemingwayapp.com/
• https://www.grammarly.com/
• https://en.wikipedia.org/wiki/Pareto_principle
• https://linkerd.io/2/getting-started/
• https://www.redhat.com/en/services/training/rh024-red-hat-linux-technical-overview?intcmp=7016000000127cYAAQ
• https://developers.redhat.com/cheat-sheets/advanced-linux-commands/?intcmp=7016000000127cYAAQ
• https://twitter.com/lucperkins
• https://coss.media/open-source-documentation-technical-writing-101/