الكتابة الفنية للمطورين

HTML و CSS و JavaScript و Python و PHP و C ++ و Dart - هناك العديد من لغات البرمجة الموجودة وقد تكون طليقًا في العديد منها! ولكن نظرًا لأننا نهدف إلى كتابة كود أكثر وأفضل ، فإن الطريقة التي نكتب بها ونتواصل بها بلغة الحياة اليومية تصبح أكثر أهمية ... وربما يتم تجاهلها.

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

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

انتظر ، كتابة فنية؟ نعم ، هذا بالضبط ما أعنيه. أعتقد حقًا أننا جميعًا كتاب بمعنى أو بآخر. وأنا هنا لأقدم لك كتابًا تمهيديًا يحتوي على نصائح ونصائح وأمثلة عن كيفية جعلك مطورًا ومحاورًا أفضل.

الكتابة الفنية في كل مكان

في العام الماضي ، كان الفريق الذي يقف وراء عميل Mac Git الشهير ، Tower ، استطلع رأي أكثر من 4,000 مطور ووجدوا أن ما يقرب من 50٪ منهم يقضون ما بين 3-6 ساعات يوميًا في كتابة الكود.

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

قد يشمل ذلك:

• عرض ميزة جديدة ،
• توثيق تلك الميزة الجديدة ،
• تحديث بطاقة عمل متعلقة بهذه الميزة الجديدة ، أو
• العمل المتراكم لدعم هذه الميزة الجديدة.

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

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

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

هذه هي الكتابة الفنية 101.

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

ما هي القواعد النحوية الجيدة؟

مع وجود العديد من لغات البرمجة ، فإن آخر شيء نريده هو تعلم لغة أخرى.

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

اسمحوا لي أن أقدم لكم لمحة سريعة عن اللغة.

بناء الجملة الإنجليزية

تمامًا مثل لغات البرمجة ، تحتوي اللغة الإنجليزية على بنية محددة جيدًا ، وهي تبدأ بالكلمات.

الكلمات هي اللبنات الأساسية للغة الإنجليزية ، وهي تقع في ثمانية دلاء:

فكر في هذه مثل UI المكونات: هي أجزاء معيارية يمكنك تحريكها لبناء جملة كاملة وقوية ، بالطريقة نفسها التي يمكنك بها تجميع جملة كاملة وقوية معًا UI. هل يجب أن تكون جميع المكونات موجودة طوال الوقت؟ بالتاكيد لا! قم بتجميع جملة مع القطع التي تحتاجها لإكمال التجربة ، تمامًا كما تفعل مع الواجهة.

صوت ونبرة

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

لكن من الأهمية بمكان مراعاة ملف صوت من رسائلنا. إنه لأمر مدهش كيف يمكن لعلامة تعجب واحدة أن تغير نبرة الرسالة تمامًا:

1. أنا أحب البرمجة.
2. I مثل برمجة! :)

من السهل الخلط بين الصوت والنبرة والعكس صحيح.

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

نفس الرسالة مكتوبة بصوتين مختلفين:

• المرح: "قم بتوسيع شبكتك الاجتماعية وابق على اطلاع دائم بما هو شائع الآن."
• جدي: "ابحث عن وظائف في أحد أكبر تطبيقات الشبكات الاجتماعية وسوق الوظائف عبر الإنترنت."

ليس من غير المعتاد أن تكتب بالخطأ رسائل تبدو متعالية ومهينة وغير مهنية. هذا هو المكان لهجة يأتي دور. اقرأ رسائلك بصوت عالٍ، واجعل الآخرين يقرؤونها لك ، وجرب علامات الترقيم وهيكل الجمل. هذه هي الطريقة التي تشحذ بها نبرة صوتك.

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

النشط والصوت المبني للمجهول

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

الممثل يأتي أولا في الصوت النشط. على سبيل المثال: "ترسم CSS الخلفية".

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

مع المبني للمجهول، يأتي الفاعل أخيرًا. (انظر ماذا فعلت هناك؟) هذا يعني أن ممثلنا - CSS في هذه الحالة - يأتي في النهاية على النحو التالي: "الخلفية مرسومة بواسطة CSS."

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

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

تجنب الأخطاء

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

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

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

كتابة تعليقات التعليمات البرمجية

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

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

red *= 1.2 // Multiply `red` by 1.2 and re-assign it

بدلاً من ذلك ، استخدم التعليقات التي توفر المزيد من المعلومات:

red *= 1.2 // Apply a 'reddish' effect to the image

الأمر كله يتعلق بالسياق. "ما نوع البرنامج الذي أقوم بإنشائه؟" هو بالضبط نوع السؤال الذي يجب أن تطرحه على نفسك.

يجب أن تضيف التعليقات قيمة

قبل أن ننظر إلى ما يجعل التعليق "جيدًا" على رمز التعليمات البرمجية ، إليك مثالين للتعليقات البطيئة:

const age = 32 // Initialize `age` to 32

filter: blur(32px); /* Create a blur effect with a 32px radius */

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

يجب أن تعكس التعليقات الكود الحالي

التعليقات القديمة ليست نادرة في المشاريع الكبيرة ؛ أجرؤ على القول في أكثر المشاريع.

لنتخيل ديفيد ، مبرمجًا ورجلًا رائعًا من جميع الأنحاء للتسكع معه. يريد David أن يفرز قائمة من السلاسل أبجديًا من الألف إلى الياء ، لذلك يفعل ما هو واضح في JavaScript:

cities = sortWords(cities) // sort cities from A to Z

يدرك ديفيد بعد ذلك أن sortWords () في الواقع تفرز القوائم من Z إلى A. وهذه ليست مشكلة ، حيث يمكنه ببساطة عكس الناتج:

cities = sortWords(cities) // sort cities from A to Z
cities = reverse(cities)

لسوء الحظ ، لم يقم David بتحديث تعليقه على الكود.

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

في حين أن هذا قد يكون مثالًا مبالغًا فيه ، إلا أن شيئًا مشابهًا يمكن أن يحدث (وغالبًا ما يحدث) إذا كنت تتسابق مع موعد نهائي قريب. لحسن الحظ ، يمكن منع ذلك باتباع قاعدة واحدة بسيطة ... قم بتغيير تعليقاتك في نفس الوقت الذي تقوم فيه بتغيير الرمز.

هذه قاعدة بسيطة ستوفر عليك وعلى فريقك الكثير من التقنية الديون.

الآن بعد أن عرفنا كيف تبدو التعليقات المكتوبة بشكل سيئ ، فلنلقِ نظرة على بعض الأمثلة الجيدة.

يجب أن توضح التعليقات رمزًا أحاديًا

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

 function addSetEntry(set, value) {    
  /* Don't return `set.add` because it's not chainable in IE 11. */  
  set.add(value);
  return set;
}

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

يمكن أن تحدد التعليقات المهام المستقبلية

شيء مفيد آخر يتعلق بالتعليقات هو الاعتراف بأن هناك المزيد من العمل الذي يتعين القيام به.

// TODO: use a more efficient algorithm
linearSort(ids)

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

التعليقات يمكن أن تصل إلى المصدر

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

// Adds handling for legacy browsers
// https://stackoverflow.com/a/XXXXXXX

هذا مهم لأن الحلول يمكن أن تتغير. من الجيد دائمًا معرفة مصدر شفرتك في حالة تعطلها.

كتابة طلبات السحب

طلبات السحب (PRق) جانب أساسي من أي مشروع. هم يجلسون في قلب مراجعات الكود. ويمكن أن تصبح مراجعات الكود بسرعة عنق الزجاجة في أداء فريقك دون صياغة جيدة.

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

## Proposed changes
Describe the big picture of your changes here to communicate to the maintainers why we should accept this pull request.

## Types of changes
What types of changes does your code introduce to Appium?
 - [ ] Bugfix (non-breaking change which fixes an issue)
 - [ ] New feature (non-breaking change which adds functionality)
 - ...

## Checklist
 - [ ] I have read the CONTRIBUTING doc
 - [ ] I have signed the CLA
 - [ ] Lint and unit tests pass locally with my changes

## Further comments
If this is a relatively large or complex change, kick off the discussion by explaining why you chose the solution you did and what alternatives you considered, etc…

تجنب الغموض PR عناوين

الرجاء تجنب العناوين التي تبدو كالتالي:

• إصلاح البناء.
• إصلاح الخطأ.
• أضف التصحيح.

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

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

فيما يلي بعض الأمثلة الجيدة:

• دعم سمات srcset المخصصة في NgOptimizedImage
• التكوين الافتراضي للصورة يصل إلى 75٪ من جودة الصورة
• أضف محددات صريحة لجميع أدوات ControlValueAccessors المضمنة

تجنب طويلا PRs

كبير PR يعني وصفًا ضخمًا ، ولا أحد يريد مراجعة مئات أو آلاف أسطر التعليمات البرمجية ، أحيانًا ينتهي الأمر برفض كل شيء!

بدلاً من ذلك ، يمكنك:

• التواصل مع فريقك من خلال قضايا,
• أعمل خطة،
• تقسيم المشكلة إلى أجزاء أصغر ، أو
• العمل على كل قطعة على حدة PR.

أليس أكثر نظافة الآن؟

قدم التفاصيل في PR الجسدي

وخلافا لل PR العنوان والجسم ال مكان لجميع التفاصيل ، بما في ذلك:

• لماذا هو PR يجري القيام به؟
• لماذا هذا هو أفضل نهج؟
• أي أوجه قصور في المنهج ، وأفكار لحلها إن أمكن
• رقم الخطأ أو التذكرة والنتائج المعيارية وما إلى ذلك.

الإبلاغ عن الأخطاء

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

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

على سبيل المثال ، تأتي معظم المشاريع الكبيرة مع قالب:

 <!-- Modified from angular-translate/angular-translate -->
 ### Subject of the issue
 Describe your issue here.

 ### Your environment
 * version of angular-translate
 * version of angular
 * which browser and its version

 ### Steps to reproduce
 Tell us how to reproduce this issue.

 ### Expected behavior
 Tell us what should happen.

 ### Actual behavior
 Tell us what happens instead.

اجمع لقطات الشاشة

التقط المشكلة باستخدام ملف أداة تصوير شاشة النظام.

إذا كانت لقطة شاشة من ملف CLI البرنامج ، تأكد من أن النص واضح. إذا كانت UI البرنامج ، تأكد من أن لقطة الشاشة تلتقط العناصر والحالات الصحيحة.

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

كيفية إعادة إنتاج المشكلة

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

وإليك مثال على ذلك:

Update: you can actually reproduce this error with objects:

 ```html
 <div *ngFor="let value of objs; let i = index">
   <input [ngModel]="objs[i].v" (ngModelChange)="setObj(i, $event)" />
 </div>
 ```

 ```js
 export class OneComponent {
   obj = {v: '0'};
   objs = [this.obj, this.obj, this.obj, this.obj];
 ​
  setObj(i: number, value: string) {
     this.objs[i] = {v: value};
  }
 }
 ```

 The bug is reproducible as long as the trackBy function returns the same value for any two entries in the array. So weird behavior can occur with any duplicate values.

اقترح سبب

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

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

التواصل مع العملاء

قد تعمل كمستقل منفرد ، أو ربما تكون المطور الرئيسي في فريق صغير. في كلتا الحالتين ، لنفترض أنك مسؤول عن التواصل مع العملاء في مشروع ما. 

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

لذا ، كيف يمكننا التخفيف من هذه الصورة النمطية؟ اسأل العملاء عما يريدون ، واستمع دائمًا إلى ملاحظاتهم. إليك كيفية القيام بذلك.

اسأل الأسئلة الصحيحة

ابدأ بالتأكد من أنك أنت والعميل على نفس الصفحة:

• ؟ من هو جمهورك المستهدف
• ما هو الهدف من الموقع؟
• من هو أقرب منافس لك وماذا يفعلون بالشكل الصحيح؟

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

• هل أنت موافق على ذلك حتى لو كان مصحوبًا بتكلفة أداء إضافية؟
• هل يساعدنا تحريك المكون في تحقيق هدفنا بشكل أفضل؟
• عظيم ، من المسؤول عن الحفاظ على ذلك بعد الإطلاق؟ 
• هل تعرف ما إذا كان التباين بين هذين اللونين يتجاوز معايير WCAG AA؟

الأسئلة أكثر براءة وتثير الفضول حول العداء.

سوق نفسك

إذا كنت تقدم عرضًا تقديميًا لعميل محتمل ، فستحتاج إلى إقناعهم بتوظيفك. لماذا يجب على العميل أن يختارك؟ من المهم تحديد ما يلي:

• من أنت
• ماذا تفعل
• لماذا أنت مناسب للوظيفة
• روابط للعمل ذي الصلة الذي قمت به

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

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

الكتابة المصغرة

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

قد يكون هذا هو السبب في أننا نرى أحيانًا أخطاء مثل هذا:

Error: Unexpected input (Code 693)

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

تجنب المصطلحات الفنية

لا يعرف معظم الناس ماهية الخادم ، بينما يعرفه 100٪ من المبرمجين. لهذا السبب ليس من غير المعتاد رؤية مصطلحات غير شائعة مكتوبة في رسالة خطأ ، مثل API أو "تنفيذ المهلة".

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

لذلك ، لا ينبغي أن تشرح رسالة الخطأ الجيدة لماذا حدث خطأ ما ، لأن مثل هذه التفسيرات قد تتطلب استخدام مصطلحات فنية مخيفة. لهذا السبب من المهم جدًا تجنب استخدام المصطلحات التقنية.

لا تلوم المستخدم أبدًا

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

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

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

لا تربك المستخدم

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

لكن إذا لم تستخدمه تماما، يمكن اعتباره تعاليًا وإهانة للمستخدم. هذا مجرد كبير المجازفة لاتخاذ.

Mailchimp يقول ذلك جيدًا:

[د] لا تبتعد عن طريقك لإلقاء نكتة - يمكن أن تكون الدعابة القسرية أسوأ من لا شيء على الإطلاق. إذا لم تكن متأكدًا ، فاحرص على أن يكون وجهك مستقيماً.

(توكيد لي)

كتابة ترميز يمكن الوصول إليه

يمكننا بسهولة قضاء مقال كامل حول إمكانية الوصول وكيفية ارتباطها بالكتابة الفنية. هيك ، غالبًا ما يتم تضمين إمكانية الوصول في أدلة نمط المحتوى ، بما في ذلك تلك الخاصة بـ مایکروسافت و Mailchimp.

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

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

اشياء مثل:

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

وفي الختام

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

خلاصة القول: إن شحذ مهاراتك في الكتابة وبذل القليل من الجهد الإضافي في كتابتك يمكن أن يجعلك في الواقع مطورًا أفضل.

موارد الكتابة الفنية

إذا كنت مهتمًا بالكتابة الفنية:

إذا كنت مهتمًا بكتابة الإعلانات:

إذا كنت مهتمًا بالنسخ المصغر:

إذا كنت مهتمًا باستخدام دليل أسلوب احترافي لتحسين كتابتك:

إذا كنت مهتمًا بالكتابة لإمكانية الوصول: