في خريف عام 2016 ، تم إرشادي أنا وزميلي بتحسين الوثائق والمحتوى في شركتي السابقة. لقد أمضينا عامًا في جميع أنواع الوثائق: مرجع واجهة برمجة التطبيقات ، والأدلة ، والبرامج التعليمية ، ومشاركات المدونات. قبل ذلك ، كتبت أرصفة لمدة 5 سنوات ، لكنني لم أتعلم هذا رسميًا. ولكن لا يمكنني أن أكون عديم الخبرة: بالإضافة إلى توثيق واجهة برمجة التطبيقات (API) للمشاريع والشركات الناشئة ، قمت أيضًا بتدريس Python Flask في الندوات أثناء الدراسة في الدورات الأخيرة في الجامعة. لكنها الآن فرصة للتركيز فقط على عملي المفضل: مساعدة المتخصصين على جميع المستويات من خلال الوثائق الفنية.
لقد تعلمت هذا العام الكثير من مجتمع Write The Docs ومن موفري API الآخرين ومن طريقة التجربة والخطأ. في العام الماضي ، شاركت تجربتي في تقرير "ما أرغب في معرفته عن كتابة الوثائق" في مؤتمر بورتلاند
لاستراتيجيات وممارسات API . هذه المقالة هي لمحة عامة عن المعرفة المكتسبة.
كيف يقرأ الناس الوثائق بالفعل؟
"أمة ترتجف من جزء كبير من نص واحد" ، تصوير البصلهل تعرف هذا الشعور كما في الصورة؟ يحدث ذلك. ربما ليس جسديا ، ولكن على الأرجح ، يرتجف الناس عقليا. كنت أتألم باستمرار من فكرة أن الناس لن يقرؤوا نصاتي ما لم أخرجها بطريقة سهلة الهضم. يا إلهي ، يمكن أن يحدث هذا حتى مع هذه المقالة.
في دراسة بحثية لمجموعة Neilson Norman Group عام 2006 ، عرض 232 مستخدمًا آلاف صفحات الويب. اتضح أن المستخدمين عادة ما ينظرون إلى الصفحات باستخدام النمط F:
- "يقرؤون أولاً في الاتجاه الأفقي ، عادةً في الجزء العلوي من منطقة المحتوى. هذا هو العنصر العلوي في الشكل F. "
- "ثم ينتقلون قليلاً إلى أسفل الصفحة - ويقومون بحركة أفقية ثانية ، والتي عادة ما تغطي منطقة أقصر من السابقة. يشكل هذا العنصر الإضافي العنصر الأوسط من الشكل F ".
- "أخيرًا ، يقوم المستخدمون بمسح الجانب الأيسر من المحتوى رأسيًا . في بعض الأحيان يكون هذا فحصًا بطيئًا ومنهجيًا ، يتم عرضه كشريط صلب على خريطة حرارية. في بعض الأحيان تكون الحركة أسرع ، وتشكل بقع على خريطة الحرارة. هذا هو العنصر الرأسي الأخير في الشكل F. "
مجموعة حرارية نيلسن نورمانوجدت الدراسة بعض أنماط المسح البديلة ، مثل نمط كعكة النفخة ، الخريطة المرقطة ، قالب التخطيط ، نمط الالتفاف ، والنمط الهادف. أوصي بشدة بقراءة
التقرير .
من المهم ملاحظة أن النمط F في
طريق المستخدمين ، ولكن تحديد الموقع الجيد للمحتوى يساعد على منع التصوير بالاشعة.
ما هي الآثار المحددة للتوثيق؟
- يجب أن تشير الفقرتان الأوليان إلى أهم المعلومات.
- الكلمات 3-5 الأولى حاسمة
- العناوين والفقرات والقوائم النقطية بكلمات إعلامية
- قد تكون تغييرات الخط (الحجم والروابط والخط الغامق وما إلى ذلك) ضرورية لجذب انتباه القارئ
فكيف هيكلة المحتوى على الصفحة؟
- منع المسح: تأكد من تمييز المعلومات التي يحتاجها القارئ
- فكر واحد في فقرة. إذا كان هناك العديد ، فكسر الفقرة
- يتخطى المستخدمون كل ما يشبه اللافتات ، لذا كن حذرًا مع الرسوم التوضيحية.
- لا تقم بتوسيع عمود النص أكثر من اللازم: على النحو الأمثل 65-90 حرفًا
لقد تعلمت بعض هذه النصائح من
محاضرة كيفين بورك
، "كيفية كتابة الوثائق للمستخدمين الذين لا يقرؤونها". دعم كيفن توثيق Twilio من 2011 إلى 2014.
بالإضافة إلى ذلك ، تحتوي الفقرات على تفاصيل خاصة بها. مثل نص
البصل ، عندما تقرأ الكثير من الفقرات ، يمكنك تخطي الجوهر. ثم لماذا استخدامها في كثير من الأحيان؟ دعونا نجري تجربة من وثائق Keen IO:
اقرأ هذا بسرعة:يمكن أن يكون لمجموعات الأحداث أي اسم تقريبًا ، ولكن هناك عدة قواعد: يجب ألا يحتوي الاسم على أكثر من 64 حرفًا. يجب أن يحتوي على أحرف ASCII فقط. لا يمكن أن تكون فارغة.
الآن اقرأ هذا بسرعة:يمكن أن يكون لمجموعات الأحداث أي اسم تقريبًا ، ولكن هناك بعض القواعد:
- يجب ألا يزيد العنوان عن 64 حرفًا
- يجب أن يحتوي على أحرف ASCII فقط
- لا يمكن أن تكون فارغة
في كلا المثالين ، نفس النص
بالضبط . هذه ليست ذرة نيوتن: الثانية تساعد على استيعاب المعلومات بشكل أفضل وأسرع. إذا كانت الفقرة تحتوي على قائمة من أي نوع ، فقم بتحويلها إلى قائمة ذات تعداد نقطي.
في وقت لاحق سنناقش بمزيد من التفصيل تخطيط الوثائق والملاحة عليه.
أمثلة التعليمات البرمجية
ما هي وثائق API بدون رمز ، أليس كذلك؟ هناك أمثلة برمجية في العديد من مستنداتنا ، ويقرأها المستخدمون
بالفعل . لكن المشكلة هي أنهم لا ينتبهون دائمًا للنص المحيط.
يعتبر السياق في نموذج التعليمات البرمجية مهمًا لنجاح المطور. يحب المطورون النسخ واللصق بسرعة. فيما يلي مثال على Keen IO API:
var client = new Keen({ projectId: "your_project_id", writeKey: "your_write_key" }); var ticketPurchase = { price: 50.00, user: { id: "020939382", age: 28 }, artist: { id: "19039", name: "Tycho" } } client.addEvent("ticket_purchases", ticketPurchase);
يقوم المطور بسرعة بنسخ هذا الرمز ولصقه. و ...
أولاً ، كيف يقومون بتشغيل الملف على الإطلاق؟ ربما مثل
node file_name.js ، ولكن هذا ليس في التعليمات البرمجية. يمكن للمرء أن يشير في التعليقات في الأعلى.
حسنًا ، لقد بدأوا ذلك و ...
ReferenceError: Keen is not defined . :-( لم يتم بدء عميل Keen ، في الأعلى لا يوجد استيراد أو طلب بيان ، وهو يعمل فقط بعد تثبيت مكتبة npm.
قام المستخدم بإصلاحه وتشغيله مرة أخرى ... خمن؟! خطأ آخر!
your_project_id و
your_write_key مفقودة.
كل هذا يمكن أن يكون أكثر وضوحا.
فيما يلي مثال من وثائق Twilio التي توفر سياقًا جيدًا للمستخدم النهائي:
لقطة شاشة من وثائق مكتبة Twilio Node Helperيوضح هذا على الفور كيفية تثبيت المكتبة ، وتضمينها في التعليمات البرمجية الخاصة بك وما يجب استبداله في نموذج التعليمات البرمجية قبل تشغيلها.
نسخ ولصق البق
نظرًا لأن لدينا الكثير من نماذج التعليمات البرمجية في الوثائق ، فإن النسخ واللصق الناجح هو خاصية مهمة جدًا. في ما يلي مثالان على عدم احترام ذلك:
يبدو غير ضار جدا ، أليس كذلك؟ فكر مرة أخرى ، ماذا يحدث عند نسخ هذا ولصقه في سطر الأوامر؟ سوف تتلقى على الأرجح:
bash: command not found: $
خطأ شائع. إما أنك تريد أن يبدو الأمر في سطر الأوامر ، أو أن تقوم بنسخه عن طريق الخطأ. أود أن أوصي بالتخلي عن
$ . يمكنك أيضًا العثور على طريقة لمنع نسخ ولصق هذا الرمز بحيث لا يزعج الخطأ المستخدمين.
مثال أحدث: هل تحققت من مدى سهولة تحديد الرمز الذي يريد المستخدم نسخه؟
كافحت Kelsey Hightower لنسخ رمز عينة من StackOverflow في عرض Google Cloud Next.
"نسخ مبرمجين جيدين ، لصق المبرمجين الرائعين"هل فعل ذلك عن قصد؟ لن نعرف أبداً. ومع ذلك ، هذا توضيح لكيفية محاولة المبرمجين إبراز أجزاء كبيرة من النص في بعض مواقع التوثيق. تأكد من أن واجهة مستخدم الموقع تجعل من السهل نسخ الكتل الكبيرة. يمكنك حتى كسر هذه الكتل لشرح الأجزاء بشكل فردي. لذلك ستصبح أكثر سهولة للنسخ والفهم.
"هذا كل شيء!"
"هذا كل شيء!" تبدو العبارة غير ضارة إلى حد كبير خارج السياق ، ولكن تخيل كيف يتم إدراك كلمات معينة مثل "سهل" و "بسيط" و "تافه" و "سهل" عندما تواجه مشاكل - ليست رائعة! عندما يكون الشخص عالقًا في محاولة تشغيل واجهة برمجة التطبيقات ، فإن هذه العبارة تلقي بظلال من الشك على ذكائه وتجعله يطرح السؤال التالي: "إذن أنا غبي؟" إنه يحبط المعنويات.
التبسيط
التبسيط أمر شائع. وهي أكثر شيوعًا بين المبتدئين في كتابة الوثائق. غالبًا ما يكون مؤلفو التوثيق هم في نفس الوقت مطورو النظام ، لذلك تبدو بعض الأشياء "سهلة" لهم. لكنهم طوروا هذه الوظيفة ، وكتبوا كودًا لها ، ودققوها عدة مرات ، ثم كتبوا الوثائق. عندما تفعل شيئًا عشرات المرات ، من الواضح أنه سيكون "سهلاً" بالنسبة لك. ولكن ماذا عن شخص لم يشاهد واجهة مستخدم أو وظيفة من قبل؟
التعاطف
إن اختيار الكلمات مهم
حقًا . التعاطف هو القدرة على فهم مشاعر الآخرين ومشاركتها. عندما نظهر التعاطف ، فإننا لا نساعد القادمين الجدد فحسب ، بل نساعد أيضًا المستخدمين الأكثر تقدمًا. وهذا يساعد على زيادة العدد المحتمل للمستخدمين وحالات الاستخدام والعملاء وحتى أرباح الشركة.
ولكن عندما يكتب التوثيق خبير تطوير مشروع ، يكون التعاطف أكثر صعوبة. إليك بعض النصائح المفيدة التي ساعدتني في الماضي:
- اطلب من المشاركين الأقل خبرة في المشروع التعليق بصدق على الوثائق.
- شجع المشاركين الأقل خبرة في المشروع على المساهمة أو الإشارة إلى نقاط التوثيق التي لا يفهمونها.
- خلق بيئة حيث يتم تشجيع الأسئلة ، بما في ذلك تلك التي قد تبدو "واضحة" للمشاركين ذوي الخبرة في المشروع - سيساعدك ذلك على ملاحظة "النقاط العمياء"
- استخدم معالجات الكود في مراجعة الكود وعمليات CI لضمان التعاطف والود اللغوي لجميع المستخدمين.
- أخيرًا ، اطلب التعليق على توثيق المستخدمين الحقيقيين ، وأظهر لهم النص واسأل عما إذا كان كل شيء واضحًا
رسائل الخطأ كنوع من الوثائق
عادة ، من المرجح أن يرى المستخدمون رسائل خطأ من الوثائق. وفقًا لكايت فوس ، "رسائل الخطأ هي في الواقع فرصة". أعتقد أن العديد من مطوري التوثيق يفوتون هذه الفرصة. هناك مكان للتدريب وإقامة علاقات ثقة وتوقعات المستخدمين. بادئ ذي بدء ، سوف تساعد الناس على مساعدة أنفسهم.
Kate at Write يوفر محرر المستندات الكثير من المعلومات المفيدة حول كتابة رسائل الخطأ. لقد تعلمت الكثير خلال عملي السابق حول رسائل خطأ واجهة برمجة التطبيقات ، بالإضافة إلى التواجد على الجانب الآخر من الحواجز ، وتلقي رسائل خطأ من واجهات برمجة التطبيقات الأخرى كمطور.
تقول كيت أن رسائل الخطأ الجيدة مبنية على ثلاثة مبادئ:
التواضع
تحتاج إلى الاعتذار على الفور ، حتى لو لم يكن خطأك. أمارس هذا أيضًا في خدمة الدعم.
مثال:
عذرًا ، تعذر الاتصال بـ ___. يُرجى التحقق من إعدادات الشبكة والاتصال بالشبكة المتاحة والمحاولة مرة أخرى.
الإنسانية
استخدم مصطلحات يمكن قراءتها بواسطة الإنسان ؛ تجنب عبارات مثل "استثناء تم طرحه بواسطة هدف المكالمة". عند كتابة التعليمات البرمجية التي يتم تشغيل العديد من رسائل الخطأ لها ، من السهل التخلص من المفردات الواضحة.
مثال (خطأ كود حالة Twilio 401):
{ “code”: 20003, “detail”: “Your AccountSid or AuthToken was incorrect.”, “message”: “Authenticate”, “more_info”: “https://www.twilio.com/docs/errors/20003", “status”: 401 }
النفع
إذا كنت تتذكر إحدى هذه النصائح ، فتذكر الفائدة. شارك المعلومات مع المستخدم حول كيفية حل المشكلة.
مثال:
عذرًا ، الصورة التي حاولت تحميلها كبيرة جدًا. حاول مرة أخرى بصور أصغر من 4000 بكسل في العرض و 4000 بكسل في العرض.
كيفية كتابة رسائل الخطأ
كما هو الحال مع أي وثائق أخرى ، قدم معلومات مهمة أولاً. يمكن القيام بذلك عن طريق تحديد الكائن أولاً ، ثم الإجراء. يبحث المستخدم عن نتيجة ، وليس عن كيفية الوصول إليها. هذا مفيد عندما يقوم المستخدمون بالبحث عن رسائل الخطأ بسرعة.
مثال سيء:
اضغط على زر العودة للعودة إلى الصفحة السابقة.
مثال جيد:
للعودة إلى الصفحة السابقة ، استخدم زر العودة.
رسائل خطأ التوثيق
أجده مفيدًا
جدًا عند ذكر رسائل خطأ API العامة في الوثائق. بهذه الطريقة ، يمكن لمؤلف التوثيق توضيح رسالة الخطأ دون تكبير الوثائق ، بينما يساعد المستخدم في نفس الوقت على فهم سبب حدوث الخطأ.
ينشر Twilio قائمة كاملة بالأخطاء والتحذيرات مع الأسباب والحلول المحتملة. باستخدام هذه الطريقة ، يمكنك جعل رسائل الخطأ الفعلية أقصر ولكن لا تزال مفيدة.
في حالة الخطأ 20003 (خطأ رمز الحالة 401 ، المذكور سابقًا) ، هناك العديد من الأسباب المحتملة المذكورة بوضوح في الكتالوج.
المصدر: https://www.twilio.com/docs/api/errorsيقوم Stripe بشيء مماثل مع وصف تفصيلي لرموز الخطأ المختلفة.
المصدر: https://www.twilio.com/docs/api/errorsيمكنك أيضًا العثور على رسائل الخطأ الخاصة بك في أسئلة StackOverflow. أجبهم بتواضع وإنسانية وبفائدة. بسبب تحسين محركات البحث ، ينتهي المستخدمون غالبًا برسائل الخطأ الخاصة بك على StackOverflow بدلاً من الوثائق الفعلية.
تلميح: إذا لم يستجب أحد بشكل متواضع وإنساني ومفيد ، فعندئذٍ يمكنك تعديل إجابات StackOverflow بما يكفي من "السمعة".
اختيار الكلمات
العديد من الكلمات لها أنماط عقلية راسخة. على سبيل المثال ، هناك كلمات مثل "مكتبات" و "حزم SDK" و "أغلفة" و "عملاء" ممتلئة بالفعل وتنتقل إلى انتباه القارئ.
في محاضرته ،
"حتى في هذه المحاضرة ، من الصعب العثور على اسم" في كتابة المستندات ، تقول روثي بيندور لماذا يكون اختيار الكلمات المناسبة أمرًا صعبًا.
غالبًا ما نختار الكلمات بشكل سيئ ، على الرغم من أنه عند كتابة النص ، فإننا نفعل ذلك طوال الوقت. مثل العديد من عناوين SDK ، تثير كل كلمة مجموعة واسعة من المشاعر والأفكار والتعاريف في القارئ. قد لا تفهم ذلك - وغالبًا ما نفترض افتراضات خاطئة.
في مثل هذه الحالة ، المثل الشهير صحيح كما لم يحدث من قبل: "هناك مهمتان صعبتان فقط في مجال علوم الكمبيوتر: إبطال ذاكرة التخزين المؤقت واختراع الأسماء". غالبًا ما يُنسب الاقتباس إلى فيل كارلتون ، ولكن اليوم هناك العديد من الاختلافات في هذا القول. في بعض الأحيان يضيفون في النهاية "... وخطأ لكل وحدة". يعتبر Ruti هذا دليلاً على أن البرمجيات اليوم تعتمد إلى حد كبير على كود أو عمل شخص آخر.
لماذا يتم الاحتفاظ بأسماء الكائنات (أو الوثائق) السيئة؟
كما هو الحال مع التبسيط المفرط ، فإننا غالبًا لا نفهم أن الاسم سيئ. هذا ما يسميه روثي
فشل التعاطف . هكذا أقول إن مشكلة الكلمات الفاشلة لا تهمني ، وبالتالي فهي غير موجودة.
تلميح للولايات المتحدة الأمريكية: لمنع العنصرية العرضية ، استخدم الكلمات "القائمة المحظورة" و "القائمة المسموح بها" بدلاً من "الأسود" و "الأبيض".
(المصادر: أندريه ستالتز والقضبان / القضبان / الأعداد / 33677 )
لا يزال يذكرني بما تسميه روثي
خطأ التفكير المبتدئ . إنه مثل القول "إنه واضح لي تمامًا. لا أفهم كيف لا يستطيع شخص ما فهم ذلك ".
أخيرًا ، تذكر روثي
خطأ توطين . على سبيل المثال ، تعني كلمة Bing باللغة الصينية "مريض".
وفقًا
لدراسة أجرتها GitHub مفتوحة المصدر عام 2017 :
ما يقرب من 25 ٪ من المطورين يقرؤون ويكتبون اللغة الإنجليزية ليست "جيدة جدًا". عند التواصل في مشروع ، استخدم لغة مفهومة ومتاحة للأشخاص من البلدان غير الناطقة باللغة الإنجليزية.
هل تأخذ هذا في الاعتبار عند استخدام الأمريكيات والتعابير في التوثيق؟ قد يكون العديد منها غير مفهومة للمستخدمين.
تلميح: أعتقد اعتقادًا راسخًا أن أحد أكبر "الحيل" لحل هذه المشكلات هو تنوع فريق التوثيق.
لا تزال هناك حالات عندما نعترف بالخطأ ، ولكن لا يمكننا أو لا نريد تصحيحه ، لأننا ...
- تعادل معها
- لا نجد الوقت
- نحن لا نرى الأهمية
- ليس لدينا وكالة لإصلاحها.
يمكنك أن تقول أو تسمع: "لكن هذا من بنات أفكاري!" ، "من أزال حبيبي؟" "إذا أعدنا التسمية ، فسينكسر كل شيء" ، "لا أعتقد أن تغيير هذا الاسم سيؤثر على أي شيء مهم".
لا يمكنك أن تخاف من إعادة الهيكلة وإعادة الكتابة عندما يتعلق الأمر بالتوثيق. كيفية تحسينه ، إذا كنت لا توافق على حقيقة أنه لم يتم الاختيار الأفضل في البداية؟
كيف تختار الكلمات الصحيحة؟
للبدء ، أوصيك بطرح سؤال: ما الكلمات التي يستخدمها المستخدمون؟ تستخدم دوائر المبرمج المختلفة مصطلحات مختلفة ، لا تحاول استخدام الآخرين. هذا مفيد ليس فقط للقراء ، ولكن أيضًا للبحث و SEO.
في النهاية ، كل شيء يأتي حتمًا إلى التقييم الذاتي. ومع ذلك ، هناك عدد قليل من المبادئ للنظر فيها. تقول روثي إن الأسماء السيئة هي التي يمكنها:
- محرج
- منزعج
- تضليل
- للتشويش
- الإساءة
الأسماء الحسنة من ناحية أخرى:
- المساهمة في التوضيح المفاجئ ("هذا كل شيء!")
- يتم حقنه في السياق
- شرح
- تضيء
- تقديم الدعم
أوصي بأخذ هذه الصفات في الاعتبار عند اقتطاع الوثائق من أجل إجراء مراجعات مفيدة وصادقة حولها.
اختيار الكلمات الصحيحة أمر صعب. لا توجد صيغة سحرية. يختلف جميع المستخدمين ، وكذلك حالات استخدام المنتج ؛ ما يصلح للبعض قد لا يعمل مع الآخرين. إذا كان الأمر سهلاً ، لكان الجميع لديهم وثائق أفضل بكثير. كما تقول روثي للمطورين: "كتابة البرامج هي تمرين على اختراع الأسماء. تعامل معها ". وإذا كنت تكتب وثائق لبرنامج شخص آخر ، "أخبر المطور إذا لم تصل أسماؤه إلى الهدف".