نگارش فنی برای توسعه دهندگان

HTML، CSS، جاوا اسکریپت، پایتون، پی‌اچ‌پی، سی پلاس پلاس، دارت – زبان‌های برنامه‌نویسی بسیار زیادی وجود دارند و حتی ممکن است به چندین مورد از آنها کاملاً مسلط باشید! اما از آنجایی که قصد داریم کدهای بیشتر و بهتر بنویسیم، نحوه نوشتن و برقراری ارتباط در زبان روزمره اهمیت بیشتری پیدا می‌کند... و شاید حتی نادیده گرفته شود.

روشی که در مورد کد و اطراف آن می نویسیم مسلماً به اندازه خود کد مهم است. و علی‌رغم اینکه شما در آن خط قرار می‌گیرید، همه ما می‌توانیم موافق باشیم که کلمات ما این پتانسیل را دارند که هم به اثربخشی کد کمک کنند و هم به آن آسیب بزنند.

در این مقاله، من می‌خواهم توضیح دهم که چگونه این دو زمینه به ظاهر متمایز - برنامه‌نویسی و نوشتن - می‌توانند با هم ترکیب شوند و مهارت‌های توسعه‌دهنده ما را به سطح بعدی ببرند.

صبر کنید، نوشتن فنی؟ بله، دقیقاً منظورم همین است. من واقعاً معتقدم که همه ما به یک معنا نویسنده هستیم. و من اینجا هستم تا به شما یک آغازگر با نکات نوشتن، توصیه‌ها و مثال‌هایی ارائه کنم که چگونه می‌تواند شما را توسعه‌دهنده و ارتباط‌دهنده بهتری کند.

نوشتن فنی همه جا هست

سال گذشته، تیم پشتیبان کلاینت محبوب مک گیت، Tower، از بیش از 4,000 توسعه دهنده نظرسنجی کرد و دریافتند که نزدیک به 50٪ از آنها بین 3-6 ساعت در روز برای نوشتن کد صرف می کنند.

و بله، این یک نظرسنجی است که در مورد یک گروه خاص انجام شده است، اما تصور می‌کنم بسیاری از ما در این محدوده قرار داریم. در هر صورت، یک توسعه‌دهنده کد 24/7 نمی‌نویسد، زیرا همانطور که این نظرسنجی نشان می‌دهد، ما زمان زیادی را صرف انجام کارهای دیگر می‌کنیم.

که ممکن است شامل موارد زیر باشد:

• نمایش یک ویژگی جدید،
• مستندسازی آن ویژگی جدید،
• به روز رسانی بلیط کاری مربوط به آن ویژگی جدید، یا
• کارهای عقب افتاده برای پشتیبانی از این ویژگی جدید.

البته، همیشه زمانی برای استراحت در حمام و وردل وجود دارد.

به هر حال، بیشتر کارهایی که ما معمولا انجام می دهیم شامل برقراری ارتباط با افرادی مانند تیم شما، همکاران، مشتریان، کاربران و سایر توسعه دهندگان است.

بنابراین ما بخش زیادی از زمان خود را صرف برقراری ارتباط با انسان ها می کنیم کلمات علاوه بر ارتباطی که از طریق رایانه با رایانه داریم رمز. کلمات زبان نوشتاری هستند. و اگر کلماتمان را بهتر می نوشتیم، بهتر ارتباط برقرار می کردیم. وقتی بهتر ارتباط برقرار می کنیم، به احتمال زیاد به آنچه می خواهیم می رسیم.

آن رایتینگ فنی 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 */

به یاد داشته باشید که هدف از یک نظر افزودن ارزش به یک کد است نه تکرار آن. اگر نمی توانید این کار را انجام دهید، بهتر است فقط کد را همانطور که هست بگذارید. چیزی که این مثال ها را "تنبل" می کند این است که آنها صرفاً آنچه را که کد آشکارا انجام می دهد دوباره بیان می کنند. در این مورد، نظرات اضافی هستند زیرا آنها به ما می گویند که ما قبلاً می دانیم - آنها ارزش افزوده ای ندارند!

نظرات باید منعکس کننده کد فعلی باشند

نظرات منسوخ در پروژه های بزرگ مشاهده نادری نیست. به جرات می گویم در اکثر پروژه ها.

بیایید دیوید را تصور کنیم، یک برنامه نویس و یک مرد همه جانبه باحال برای معاشرت با او. دیوید می‌خواهد فهرستی از رشته‌ها را بر اساس حروف الفبا از A تا 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

این مهم است زیرا راه حل ها می توانند تغییر کنند. همیشه خوب است بدانید در صورت خراب شدن کد شما از کجا آمده است.

نوشتن درخواست های کشش

درخواستها را بکشید (PRث) یک جنبه اساسی هر پروژه هستند. آنها در قلب بررسی کد قرار دارند. و بررسی کد می‌تواند به سرعت به یک گلوگاه در عملکرد تیم شما تبدیل شود، بدون اینکه عبارت خوب باشد.

خوب PR شرح خلاصه می کند چی تغییر در حال انجام است و چرا در حال ساخت است پروژه های بزرگ دارای یک الگوی درخواست کشش هستند، مانند این که از a اقتباس شده است مثال واقعی:

## 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 عنوان، بدن است 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 مطمئن شوید که اسکرین شات عناصر و حالات مناسب را ثبت می کند.

ممکن است لازم باشد یک تعامل واقعی را برای نشان دادن مشکل ثبت کنید. اگر اینطور است، سعی کنید 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 اقتباس شده است: «متأسفیم، این ترکیب ایمیل و رمز عبور درست نیست. ما می توانیم به شما کمک کنیم تا حساب خود را بازیابی کنید."

من همچنین می خواهم اهمیت اجتناب از ALL CAPS و علامت تعجب را اضافه کنم! مطمئناً می توان از آنها برای انتقال هیجان استفاده کرد، اما در میکروکپی احساس خصومت نسبت به کاربر ایجاد می کنند.

کاربر را غرق نکنید

استفاده از طنز در میکروکپی ایده خوبی است! این می تواند خلق و خو را سبک کند، و این یک راه آسان برای مهار منفی بودن ناشی از بدترین خطاها است.

اما اگر از آن استفاده نکنید کاملا، می تواند به عنوان تحقیر آمیز و توهین آمیز برای کاربر ظاهر شود. این فقط یک است بزرگ ریسک پذیرفتن

Mailchimp به خوبی می گوید:

[D]برای شوخی کردن دست به کار نشوید - طنز اجباری می تواند بدتر از هیچ باشد. اگر مطمئن نیستید، صورتتان را صاف نگه دارید.

(تاکید از من است)

نوشتن نشانه گذاری در دسترس

ما به راحتی می‌توانیم یک مقاله کامل در مورد دسترسی و نحوه ارتباط آن با نوشتن فنی صرف کنیم. هک، دسترسی اغلب در راهنماهای سبک محتوا، از جمله راهنماهای برای مایکروسافت و نام Mailchimp.

شما یک برنامه‌نویس هستید و احتمالاً از قبل اطلاعات زیادی در مورد دسترسی دارید. حتی ممکن است یکی از توسعه دهندگان سخت کوش باشید که دسترسی را به بخش اصلی گردش کار خود تبدیل می کند. با این حال، بسیار باورنکردنی است که هر چند وقت یک‌بار ملاحظات دسترسی مورد توجه قرار می‌گیرد، مهم نیست که چقدر مهم است که همه ما می‌دانیم که ایجاد تجربیات آنلاین در دسترس که شامل همه توانایی‌ها است، مهم است.

بنابراین، اگر متوجه شدید که کپی‌رایتینگ شخص دیگری را در کد خود پیاده‌سازی می‌کنید، برای توسعه‌دهندگان دیگر اسناد می‌نویسید یا حتی می‌نویسید. UI از خودتان کپی کنید، به برخی از بهترین شیوه های دسترسی اساسی توجه داشته باشید، زیرا آنها تمام توصیه های دیگر برای نوشتن فنی را تکمیل می کنند.

چیزهایی مانند:

اندی بل مقداری نسبتاً ارائه می دهد کارهای کوچکی که می توانید برای دسترسی بیشتر به محتوا انجام دهیدو ارزش وقت گذاشتن برای بررسی آنها را دارد. و فقط برای ضربه زدن، جان رئا چند ترفند ویرایش منظم را نشان می دهد زمانی که ما با عناصر HTML معنایی کار می کنیم امکان پذیر است.

نتیجه

آن‌ها شش راه بودند که نشان می‌دهند چگونه نوشتن فنی و توسعه همزمان هستند. اگرچه ممکن است مثال‌ها و توصیه‌ها علمی موشکی نباشند، امیدوارم که برای شما مفید بوده باشد، چه همکاری با توسعه‌دهندگان دیگر، حفظ کار خود، نوشتن نسخه‌ای از خودتان، یا حتی تهیه پیش‌نویس پروژه، و غیره. چیزها

نتیجه نهایی: تقویت مهارت های نوشتاری و کمی تلاش بیشتر برای نوشتن می تواند شما را به یک توسعه دهنده بهتر تبدیل کند.

منابع نگارش فنی

اگر به نوشتن فنی علاقه دارید:

اگر به کپی رایتینگ علاقه دارید:

اگر به میکروکپی علاقه دارید:

اگر علاقه مند به استفاده از یک راهنمای سبک حرفه ای برای بهبود نوشتار خود هستید:

اگر علاقه مند به نوشتن برای دسترسی هستید: