ڈویلپرز کے لیے تکنیکی تحریر

HTML، CSS، JavaScript، Python، PHP، C++، Dart — وہاں بہت ساری پروگرامنگ زبانیں موجود ہیں اور آپ ان میں سے کئی میں مکمل طور پر روانی بھی ہو سکتے ہیں! لیکن جیسا کہ ہم زیادہ سے زیادہ بہتر کوڈ لکھنا چاہتے ہیں، روزمرہ کی زبان میں جس طرح سے ہم لکھتے اور بات چیت کرتے ہیں وہ زیادہ سے زیادہ اہم ہوتا جاتا ہے… اور شاید نظر انداز بھی کیا جاتا ہے۔

جس طرح سے ہم کوڈ کے بارے میں اور اس کے ارد گرد لکھتے ہیں وہ اتنا ہی اہم ہے جتنا کہ خود کوڈ۔ اور اس کے باوجود جہاں آپ اس لائن پر آتے ہیں، ہم سب اس بات سے اتفاق کر سکتے ہیں کہ ہمارے الفاظ کوڈ کی تاثیر کو مدد اور نقصان پہنچانے کی صلاحیت رکھتے ہیں۔

اس مضمون میں، میں اس بات کا خاکہ پیش کرنا چاہتا ہوں کہ یہ دو بظاہر الگ الگ فیلڈز — پروگرامنگ اور تحریر — ایک ساتھ کیسے آ سکتے ہیں اور ہماری ڈویلپر کی مہارت کو اگلے درجے تک لے جا سکتے ہیں۔

انتظار کرو، تکنیکی تحریر؟ ہاں، میرا مطلب بالکل یہی ہے۔ مجھے یقین ہے کہ ہم سب ایک یا دوسرے معنی میں مصنف ہیں۔ اور میں آپ کو تحریری تجاویز، مشورے اور مثالوں کے ساتھ ایک پرائمر دینے کے لیے حاضر ہوں کہ یہ آپ کو ایک بہتر ڈویلپر اور کمیونیکیٹر کیسے بنا سکتا ہے۔

تکنیکی تحریر ہر جگہ ہے۔

پچھلے سال، مقبول میک گٹ کلائنٹ کے پیچھے ٹیم، ٹاور، 4,000 سے زیادہ ڈویلپرز کو پول کیا۔ اور پتہ چلا کہ ان میں سے تقریباً 50% نے کوڈ لکھنے میں دن میں 3-6 گھنٹے گزارے۔

اور ہاں، یہ ایک سروے ہے جس میں ایک خوبصورت طاق گروپ کی رائے شماری ہوتی ہے، لیکن میں تصور کرتا ہوں کہ ہم میں سے بہت سے لوگ اس حد میں کہیں گر جاتے ہیں۔ معاملہ کچھ بھی ہو، ایک ڈویلپر 24/7 کوڈ نہیں لکھ رہا ہے، کیونکہ جیسا کہ یہ پول بتاتا ہے، ہم دوسری چیزوں میں کافی وقت صرف کر رہے ہیں۔

اس میں شامل ہوسکتا ہے:

• ایک نئی خصوصیت کو ڈیمو کرنا،
• اس نئی خصوصیت کی دستاویز کرنا،
• اس نئی خصوصیت سے متعلق کام کے ٹکٹ کو اپ ڈیٹ کرنا، یا
• اس نئی خصوصیت کو سپورٹ کرنے کے لیے بیک لاگنگ کا کام۔

بلاشبہ، باتھ روم کے وقفے اور Wordle کے لئے ہمیشہ وقت ہوتا ہے۔

بہرحال، زیادہ تر چیزیں جو ہم عام طور پر کرتے ہیں ان میں آپ کی ٹیم، ساتھیوں، کلائنٹس، صارفین اور دیگر ڈویلپرز جیسے لوگوں سے بات چیت شامل ہوتی ہے۔

لہذا ہم اپنے وقت کا ایک اچھا حصہ انسانوں کے ساتھ بات چیت کرنے میں صرف کرتے ہیں۔ الفاظ اس کے علاوہ جو ہم کمپیوٹرز کے ساتھ ہوتے ہیں۔ کوڈ. الفاظ تحریری زبان ہیں۔ اور اگر ہم اپنے الفاظ کو بہتر طور پر لکھتے ہیں، تو ہم بہتر بات چیت کریں گے۔ جب ہم بہتر بات چیت کرتے ہیں، تو ہمیں وہ حاصل کرنے کا زیادہ امکان ہوتا ہے جو ہم چاہتے ہیں۔

یہ تکنیکی تحریر 101 ہے۔

اور بات یہیں ختم نہیں ہوتی.. کچھ پروگرامرز اپنی مصنوعات خود بنانا بھی پسند کرتے ہیں، جس کا مطلب ہے کہ انہیں مارکیٹنگ کو اپنے کام کا حصہ بنانا ہوگا۔ تکنیکی تحریر اس میں بھی بہت بڑا کردار ادا کرتی ہے۔ تو ہاں. میرے خیال میں یہ کہنا کافی مناسب ہے کہ تکنیکی تحریر ہے۔ یقینا ہر جگہ.

اچھا گرامر کیا ہے؟

بہت ساری پروگرامنگ زبانوں کے ساتھ، آخری چیز جو ہم چاہتے ہیں وہ ہے ایک اور سیکھنا۔

گرائمر انگریزی کا ایک لازمی حصہ ہے، اور یہ مواصلات کی مکمل صلاحیت کو کھولتا ہے۔ یہ ہمیں زیادہ رسمی، پیشہ ورانہ اور مربوط بناتا ہے۔

میں آپ کو زبان کے بارے میں ایک فوری رنڈاون دیتا ہوں۔

انگریزی نحو

پروگرامنگ زبانوں کی طرح، انگریزی میں ایک اچھی طرح سے متعین نحو ہے، اور یہ الفاظ سے شروع ہوتا ہے۔

الفاظ انگریزی کی تعمیر کے بلاکس ہیں، اور وہ آٹھ بالٹیوں میں آتے ہیں:

اس طرح کے بارے میں سوچو UI اجزاء: وہ ماڈیولر ٹکڑے ہیں جنہیں آپ ایک مکمل اور مضبوط جملہ بنانے کے لیے گھوم سکتے ہیں، اسی طرح آپ ایک مکمل اور مضبوط جملے کو جوڑ سکتے ہیں۔ UI. کیا تمام اجزاء کو ہر وقت وہاں رہنے کی ضرورت ہے؟ یقینی طور پر نہیں! ایک جملہ ان ٹکڑوں کے ساتھ جمع کریں جن کی آپ کو تجربہ مکمل کرنے کی ضرورت ہے، بالکل اسی طرح جیسے آپ انٹرفیس کے ساتھ کرتے ہیں۔

آواز اور لہجہ

الفاظ، اوقاف، جملے کی ساخت، اور الفاظ کا انتخاب۔ یہ سب انگریزی کے اجزاء ہیں۔ ہم انہیں خیالات کا اشتراک کرنے، اپنے دوستوں اور خاندان کے ساتھ بات چیت کرنے اور اپنے ساتھی کارکنوں کو ای میل بھیجنے کے لیے استعمال کرتے ہیں۔

لیکن اس پر غور کرنا بہت ضروری ہے۔ آواز ہمارے پیغامات کی. یہ حیرت انگیز ہے کہ کس طرح ایک فجائیہ نقطہ پیغام کے لہجے کو مکمل طور پر بدل سکتا ہے:

1. مجھے پروگرامنگ پسند ہے۔
2. I کی طرح پروگرامنگ! :)

لہجے کے لیے آواز کو الجھانا آسان ہے، اور اس کے برعکس۔

وائس وہی ہے جو ہمارے الفاظ کے انتخاب سے متعلق ہے، جو سیاق و سباق پر منحصر ہے۔ مثال کے طور پر، ابتدائی افراد کے لیے ایک ٹیوٹوریل میں دوستانہ آواز پہنچانے کے لیے سلیگ اور غیر رسمی زبان کا استعمال کرنے کا زیادہ امکان ہوتا ہے، جب کہ دستاویز کو ایک رسمی، سنجیدہ اور پیشہ ورانہ انداز میں تحریر کیا جا سکتا ہے تاکہ سیدھی بات تک پہنچ سکے۔

ایک ہی پیغام، دو مختلف آوازوں میں لکھا گیا:

• تفریح: "اپنے سوشل نیٹ ورک کو وسعت دیں اور جو کچھ اب ٹرینڈ ہو رہا ہے اس پر اپ ڈیٹ رہیں۔"
• سنجیدہ: "سب سے بڑی سوشل نیٹ ورکنگ ایپس اور آن لائن جابز مارکیٹ میں سے ایک پر نوکریاں تلاش کریں۔"

غلطی سے ایسے پیغامات لکھنا کوئی غیر معمولی بات نہیں ہے جو توہین آمیز، جارحانہ اور غیر پیشہ ورانہ طور پر سامنے آتے ہیں۔ یہ کہاں ہے سر کھیل میں آتا ہے. اپنے پیغامات کو بلند آواز سے پڑھیں، دوسرے لوگوں کو اپنے لیے انہیں پڑھنے کے لیے حاصل کریں، اور اپنے اوقاف اور جملے کی ساخت کے ساتھ تجربہ کریں۔ اس طرح آپ اپنے لہجے کو بہتر بناتے ہیں۔

اس کے بارے میں سوچنے کا ایک اور طریقہ یہ ہے: آپ کی آواز کبھی نہیں بدلتی، لیکن آپ کا لہجہ بدل جاتا ہے۔ آپ کی آواز اس سے ملتی جلتی ہے کہ آپ ایک شخص کے طور پر کون ہیں، جبکہ لہجہ یہ ہے کہ آپ کسی مخصوص صورتحال میں کس طرح کا ردعمل ظاہر کرتے ہیں۔

فعال اور غیر فعال آواز

ایک جملے میں ہمیشہ ایک اداکار، ایک فعل اور ایک ہدف ہوتا ہے۔ جس ترتیب میں یہ آتے ہیں اس کا تعین کرتا ہے کہ آیا جملہ فعال یا غیر فعال آواز میں لکھا گیا ہے۔

اداکار ایک میں پہلے آتا ہے۔ فعال آواز. مثال کے طور پر: "CSS پس منظر کو پینٹ کرتا ہے۔"

وہ جملے جو فعال آواز کا استعمال کرتے ہیں ان کے ہم منصبوں سے زیادہ سیدھے ہوتے ہیں۔ وہ زیادہ واضح، مختصر اور زیادہ قابل فہم ہیں — ایک زیادہ پیشہ ورانہ آواز کے لیے بہترین ہے جو سیدھی بات پر پہنچ جاتی ہے۔

کے ساتھ غیر فعال آواز، اداکار آخری آتا ہے۔ (دیکھیں کہ میں نے وہاں کیا کیا؟) اس کا مطلب ہے کہ ہمارا اداکار — اس معاملے میں CSS — آخر میں اس طرح آتا ہے: "پس منظر کو CSS نے پینٹ کیا ہے۔"

قارئین عام طور پر ایک غیر فعال آواز کو اپنے سروں میں ایک فعال آواز میں تبدیل کرتے ہیں، جس کے نتیجے میں پروسیسنگ کا وقت زیادہ ہوتا ہے۔ اگر آپ نے کبھی سنا ہے کہ فعال آواز میں لکھنا بہتر ہے تو عام طور پر یہی وجہ ہے۔ تکنیکی مصنفین زیادہ تر وقت فعال آواز کو ترجیح دیتے ہیں، بہت کم مستثنیات جیسے کہ تحقیق کا حوالہ دیتے ہوئے: "یہ تجویز کیا گیا ہے کہ …"

لیکن اس کا مطلب یہ نہیں ہے کہ آپ کو ہمیشہ ایک فعال آواز کے لیے کوشش کرنی چاہیے۔ ایک سے دوسرے میں سوئچ کرنا — یہاں تک کہ ایک ہی پیراگراف میں بھی — اگر مؤثر طریقے سے استعمال کیا جائے تو آپ کے مواد کو ایک جملے سے دوسرے جملے میں زیادہ بغیر کسی رکاوٹ کے بہا سکتا ہے۔

غلطیوں سے بچنا

گرامر زبان کی ساخت اور درستگی کے بارے میں ہے، اور اسے حاصل کرنے کے لیے آپ کی دستاویز کی فوری پروف ریڈنگ سے بہتر کوئی چیز نہیں ہے۔ اپنی تحریروں کو املا کی غلطیوں، گرامر کے مسائل اور معنوی خامیوں سے نجات دلانا بہت ضروری ہے۔

اس مضمون کے آخر میں، میں آپ کو وہ انمول ٹولز دکھاؤں گا جو پیشہ ور افراد تحریری غلطیوں سے بچنے کے لیے استعمال کرتے ہیں۔ ظاہر ہے، ان دنوں تقریباً ہر چیز میں بلٹ ان سپیل چیکرز موجود ہیں۔ ہمارے کوڈ ایڈیٹرز کے پاس ہجے کی جانچ اور لنٹنگ پلگ ان بھی ہیں تاکہ غلطیوں کو روکنے میں مدد مل سکے۔ 

لیکن اگر آپ تمام چیزوں کے گرامر کے لیے ایک ون اسٹاپ ٹول تلاش کر رہے ہیں، Grammarly سب سے زیادہ استعمال ہونے والے ٹولز میں سے ایک ہے۔ مجھے اس یا کسی بھی چیز کے لیے کک بیک نہیں مل رہا ہے۔ یہ واقعی ایک بہت اچھا ٹول ہے جسے بہت سے ایڈیٹرز اور مصنفین صاف اور واضح مواد لکھنے کے لیے استعمال کرتے ہیں — جیسا کہ آپ صاف اور واضح کوڈ لکھنے کے لیے Emmet، eslint، یا کسی دوسرے linter کا استعمال کر سکتے ہیں۔

کوڈ کے تبصرے لکھنا

جو چیزیں ہم دوسرے ڈویلپرز کے لیے لکھتے ہیں ان کا ہمارے کام کے مجموعی معیار پر بڑا اثر پڑ سکتا ہے، چاہے یہ ہم کوڈ میں لکھتے ہیں، ہم کوڈ کی وضاحت کیسے کرتے ہیں، یا کوڈ کے کسی ٹکڑے پر ہم کس طرح رائے دیتے ہیں۔

یہ دلچسپ ہے کہ ہر پروگرامنگ زبان تبصرہ لکھنے کے لیے خصوصیات کے معیاری سیٹ کے ساتھ آتی ہے۔ انہیں بتانا چاہیے کہ کوڈ کیا کر رہا ہے۔ اس سے میرا مطلب اس طرح کے مبہم تبصروں سے نہیں ہے:

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 */

یاد رکھیں کہ تبصرے کا مقصد کوڈ کے ٹکڑے میں قدر شامل کرنا ہے، اسے دہرانا نہیں۔ اگر آپ ایسا نہیں کر سکتے تو بہتر ہے کہ آپ کوڈ کو ویسے ہی چھوڑ دیں۔ جو چیز ان مثالوں کو "سست" بناتی ہے وہ یہ ہے کہ وہ صرف اس بات کو دوبارہ بیان کرتے ہیں کہ کوڈ واضح طور پر کیا کر رہا ہے۔ اس معاملے میں، تبصرے بے کار ہیں کیونکہ وہ ہمیں بتاتے ہیں جو ہم پہلے سے جانتے ہیں — وہ قدر میں اضافہ نہیں کر رہے ہیں!

تبصروں میں موجودہ کوڈ کی عکاسی ہونی چاہیے۔

پرانے تبصرے بڑے منصوبوں میں کوئی نایاب نظر نہیں آتے۔ میں کہنے کی ہمت کرتا ہوں۔ سب سے زیادہ منصوبوں.

آئیے ڈیوڈ کا تصور کریں، ایک پروگرامر اور ایک بہترین آدمی جس کے ساتھ گھومنا پھرنا ہے۔ ڈیوڈ سٹرنگز کی فہرست کو الف سے Z تک ترتیب دینا چاہتا ہے، اس لیے وہ جاوا اسکرپٹ میں واضح کرتا ہے:

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

پھر ڈیوڈ کو احساس ہوا کہ sortWords() دراصل Z سے A تک فہرستوں کو ترتیب دیتا ہے۔ یہ کوئی مسئلہ نہیں ہے، کیونکہ وہ آسانی سے آؤٹ پٹ کو ریورس کر سکتا ہے:

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

بدقسمتی سے، ڈیوڈ نے اپنا کوڈ تبصرہ اپ ڈیٹ نہیں کیا۔

اب تصور کریں کہ میں نے آپ کو یہ کہانی نہیں بتائی، اور آپ نے جو دیکھا وہ اوپر کا کوڈ تھا۔ آپ قدرتی طور پر سوچیں گے کہ کوڈ کی اس دوسری لائن کو چلانے کے بعد، `شہروں` کو 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

یہ اہم ہے کیونکہ حل بدل سکتے ہیں۔ یہ جاننا ہمیشہ اچھا ہوتا ہے کہ اگر آپ کا کوڈ کبھی ٹوٹ جاتا ہے تو یہ کہاں سے آیا ہے۔

پل کی درخواستیں لکھنا

درخواستیں کھینچیں (PRs) کسی بھی منصوبے کا بنیادی پہلو ہیں۔ وہ کوڈ کے جائزوں کے مرکز میں بیٹھتے ہیں۔ اور کوڈ کے جائزے اچھے الفاظ کے بغیر آپ کی ٹیم کی کارکردگی میں تیزی سے رکاوٹ بن سکتے ہیں۔

ایک اچھا 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.

یہاں کچھ اچھی مثالیں ہیں:

• NgOptimizedImage میں حسب ضرورت srcset اوصاف کو سپورٹ کریں۔
• ڈیفالٹ امیج کنفیگریشن 75% امیج کوالٹی پر
• تمام بلٹ ان ControlValueAccessors کے لیے واضح سلیکٹرز شامل کریں۔

لمبے عرصے سے گریز کریں۔ PRs

ایک بڑے PR ایک بہت بڑی تفصیل کا مطلب ہے، اور کوئی بھی کوڈ کی سیکڑوں یا ہزاروں لائنوں کا جائزہ نہیں لینا چاہتا ہے، کبھی کبھی صرف آخر تک پوری چیز کو مسترد کرنے کے لیے!

اس کے بجائے، آپ کر سکتے ہیں:

• کے ذریعے اپنی ٹیم کے ساتھ بات چیت کریں۔ مسائل,
• ایک منصوبہ بنائیں،
• مسئلے کو چھوٹے چھوٹے ٹکڑوں میں توڑ دیں، یا
• ہر ٹکڑے پر الگ الگ کام کریں۔ PR.

کیا یہ اب زیادہ صاف نہیں ہے؟

میں تفصیلات فراہم کریں۔ PR جسم

کے برعکس PR عنوان، جسم ہے la تمام تفصیلات کے لیے جگہ، بشمول:

• کیوں ہے 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 پروگرام، یقینی بنائیں کہ اسکرین شاٹ صحیح عناصر اور ریاستوں کو پکڑتا ہے۔

مسئلہ کو ظاہر کرنے کے لیے آپ کو ایک حقیقی تعامل کیپچر کرنے کی ضرورت پڑسکتی ہے۔ اگر ایسا ہے تو کوشش کریں۔ اسکرین ریکارڈنگ ٹول کا استعمال کرتے ہوئے GIFs ریکارڈ کریں۔.

مسئلہ کو دوبارہ پیدا کرنے کا طریقہ

پروگرامرز کے لیے کسی مسئلے کو حل کرنا بہت آسان ہوتا ہے جب وہ اپنے کمپیوٹر پر لائیو ہوتا ہے۔ یہی وجہ ہے کہ مسئلہ کو درست طریقے سے دوبارہ پیش کرنے کے اقدامات کے ساتھ ایک اچھا عہد آنا چاہیے۔

یہاں ایک مثال ہے:

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 یا "ٹائم آؤٹ ایگزیکیوشن۔"

جب تک کہ آپ کسی تکنیکی کلائنٹ یا صارف کی بنیاد کے ساتھ کام نہیں کر رہے ہیں، اس بات کا امکان ہے کہ آپ کے زیادہ تر صارفین نے کمپیوٹر سائنس کا کورس نہیں کیا، اور یہ نہیں جانتے کہ انٹرنیٹ کیسے کام کرتا ہے، اور کوئی خاص چیز کیوں کام نہیں کرتی ہے۔ لہذا، غلطی.

لہذا، ایک اچھے غلطی والے پیغام کی وضاحت نہیں کرنی چاہیے۔ کیوں کچھ غلط ہو گیا، کیونکہ اس طرح کی وضاحت کے لیے خوفناک تکنیکی اصطلاحات استعمال کرنے کی ضرورت پڑ سکتی ہے۔ اس لیے تکنیکی اصطلاح کے استعمال سے گریز کرنا بہت ضروری ہے۔

کبھی بھی صارف پر الزام نہ لگائیں۔

اس کا تصور کریں: میں آپ کے پلیٹ فارم میں لاگ ان کرنے کی کوشش کر رہا ہوں۔ اس لیے میں اپنا براؤزر کھولتا ہوں، آپ کی ویب سائٹ ملاحظہ کرتا ہوں، اور اپنی تفصیلات درج کرتا ہوں۔ پھر مجھے کہا جاتا ہے: "آپ کا ای میل/پاس ورڈ غلط ہے۔"

اگرچہ یہ سوچنا ڈرامائی لگتا ہے کہ یہ پیغام دشمنی ہے، یہ لاشعوری طور پر مجھے بیوقوف محسوس کرتا ہے۔ مائیکرو کاپی کا کہنا ہے کہ صارف پر الزام لگانا کبھی بھی ٹھیک نہیں ہے۔ اپنے پیغام کو کم انگلیوں والی چیز میں تبدیل کرنے کی کوشش کریں، جیسا کہ میلچیمپ کے لاگ ان سے اخذ کردہ اس مثال کی طرح: "معذرت، وہ ای میل پاس ورڈ کا مجموعہ درست نہیں ہے۔ ہم آپ کا اکاؤنٹ بحال کرنے میں آپ کی مدد کر سکتے ہیں۔"

میں تمام CAPS اور فجائیہ نکات سے بچنے کی اہمیت کو بھی شامل کرنا چاہوں گا! یقینی طور پر، وہ حوصلہ افزائی کرنے کے لئے استعمال کیا جا سکتا ہے، لیکن مائکرو کاپی میں وہ صارف کے خلاف دشمنی کا احساس پیدا کرتے ہیں.

صارف کو مغلوب نہ کریں۔

اپنی مائیکرو کاپی میں مزاح کا استعمال ایک اچھا خیال ہے! یہ موڈ کو ہلکا کر سکتا ہے، اور بدترین غلطیوں کی وجہ سے ہونے والی منفی کو روکنے کا یہ ایک آسان طریقہ ہے۔

لیکن اگر آپ اسے استعمال نہیں کرتے ہیں۔ بالکل، یہ صارف کی توہین آمیز اور توہین کے طور پر سامنے آسکتا ہے۔ یہ صرف ایک ہے بڑا خطرہ مول لینا۔

Mailchimp یہ اچھی طرح سے کہتا ہے:

مذاق کرنے کے لیے اپنے راستے سے باہر نہ جائیں — جبری مزاح کسی سے بھی بدتر ہو سکتا ہے۔ اگر آپ کو یقین نہیں ہے تو سیدھا چہرہ رکھیں.

(زور میرا)

قابل رسائی مارک اپ لکھنا

ہم آسانی سے ایک مکمل مضمون تک رسائی کے بارے میں اور اس کا تکنیکی تحریر سے متعلق کیسے خرچ کر سکتے ہیں۔ ہیک، رسائی کو اکثر مواد کی طرز کے گائیڈز میں شامل کیا جاتا ہے، بشمول ان کے لیے مائیکروسافٹ اور MailChimp کے.

آپ ایک ڈویلپر ہیں اور شاید پہلے ہی رسائی کے بارے میں بہت کچھ جانتے ہیں۔ یہاں تک کہ آپ زیادہ محنتی ڈویلپرز میں سے ایک ہو سکتے ہیں جو رسائی کو آپ کے ورک فلو کا بنیادی حصہ بناتا ہے۔ پھر بھی، یہ ناقابل یقین ہے کہ بیک برنر پر کتنی بار رسائی کے تحفظات کو رکھا جاتا ہے، اس سے کوئی فرق نہیں پڑتا ہے کہ ہم سب جانتے ہیں کہ قابل رسائی آن لائن تجربات کرنا ہے جو تمام صلاحیتوں پر مشتمل ہو۔

لہذا، اگر آپ اپنے کوڈ میں کسی اور کی کاپی رائٹنگ کو نافذ کرتے ہوئے، دوسرے ڈویلپرز کے لیے دستاویزات لکھتے ہوئے، یا یہاں تک کہ لکھتے ہوئے پاتے ہیں۔ UI اپنے آپ کو کاپی کریں، کچھ بنیادی رسائی کے بہترین طریقوں کا خیال رکھیں، کیونکہ وہ تکنیکی تحریر کے لیے دیگر تمام مشوروں کو پورا کرتے ہیں۔

چیزیں جیسے:

اینڈی بیل کچھ نسبتاً پیش کرتا ہے۔ چھوٹی چھوٹی چیزیں جو آپ مواد کو مزید قابل رسائی بنانے کے لیے کر سکتے ہیں۔، اور ان کی جانچ کرنا آپ کے وقت کے قابل ہے۔ اور، صرف لاتوں کے لیے، جان ریا نے کچھ صاف ترمیمی چالیں دکھائیں۔ یہ اس وقت ممکن ہے جب ہم سیمنٹک HTML عناصر کے ساتھ کام کر رہے ہوں۔

نتیجہ

وہ چھ طریقے تھے جو یہ ظاہر کرتے ہیں کہ تکنیکی تحریر اور ترقی کس طرح ایک دوسرے سے ملتی ہے۔ اگرچہ مثالیں اور مشورے راکٹ سائنس نہیں ہوسکتے ہیں، مجھے امید ہے کہ آپ نے انہیں مفید پایا، چاہے وہ دوسرے ڈویلپرز کے ساتھ تعاون کر رہے ہوں، آپ کے اپنے کام کو برقرار رکھنا ہو، اپنی کاپی ایک چٹکی میں لکھنا ہو، یا پروجیکٹ کی تجویز کا مسودہ تیار کرنا ہو، چیزیں

پایان لائن: اپنی تحریری صلاحیتوں کو تیز کرنا اور اپنی تحریر میں تھوڑی سی اضافی کوشش کرنا دراصل آپ کو ایک بہتر ڈویلپر بنا سکتا ہے۔

تکنیکی تحریری وسائل

اگر آپ تکنیکی تحریر میں دلچسپی رکھتے ہیں:

اگر آپ کاپی رائٹنگ میں دلچسپی رکھتے ہیں:

اگر آپ مائیکرو کاپی میں دلچسپی رکھتے ہیں:

اگر آپ اپنی تحریر کو بہتر بنانے کے لیے پروفیشنل اسٹائل گائیڈ استعمال کرنے میں دلچسپی رکھتے ہیں:

اگر آپ رسائی کے لیے لکھنے میں دلچسپی رکھتے ہیں: