ضد الگوها در وبلاگ نویسی نرم افزار

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

رایج ترین اشتباه در وبلاگ نویسی نرم افزار، تا حد زیادی، پیچ و خم است. من دائما خود را چندین پاراگراف در یک پست می بینم که نمی دانم نویسنده می خواهد به من چه بگوید.

توسعه‌دهندگان عاشق ویژگی‌های خاص هستند، بنابراین پست‌های وبلاگ را با پیشینه، زمینه تاریخی و هر چیز دیگری که در ذهنشان باشد شروع می‌کنند. شاید نوشتن آن سرگرم کننده باشد، اما خواندن آن همیشه جالب نیست.

از دیدگاه خواننده، میلیاردها مقاله دیگر وجود دارد که آنها می توانند بخوانند. چرا باید مال شما را بخوانند؟ آن‌ها 20 دقیقه برای خواندن کامل آن سرمایه‌گذاری نمی‌کنند مگر اینکه انتظار بازدهی داشته باشند. به خواننده دلیلی برای ادامه خواندن بدهید.

زمانی که یک توسعه‌دهنده شروع به خواندن یک پست وبلاگ می‌کند، سعی می‌کند در سریع‌ترین زمان ممکن به دو سوال پاسخ دهد:

عنوان و سه جمله اول را به خود بدهید تا به هر دو سوال پاسخ دهید.

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

در اینجا مقاله ای است که اخیرا نوشتم که مستقیما به اصل مطلب می رسد:

✓ خوب یک پست را با نشان دادن اینکه چگونه برای خواننده مفید است شروع کنید

اگر می خواهید، می خواهید: یک راه ساده برای نوشتن تست های بهتر بروید

یک الگوی عالی تست Go وجود دارد که افراد کمی آن را می شناسند. من می توانم آن را در 30 ثانیه به شما آموزش دهم.

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

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

✗ بد خواننده را مجبور کنید که از مقدمه بیش از حد رد شود

معلمان کارآمد مفاهیم جدید را با چیزی که خواننده آشنا می‌یابد مقایسه می‌کنند. به عنوان مثال، اگر قصد دارید Jellyfin را توضیح دهید، ممکن است بگویید: "Jellyfin یک سرویس پخش جریانی مانند Netflix است، به جز منبع باز و خصوصی، بنابراین هیچ کس بر عادات تماشای شما نظارت نمی کند." بخش دشوار این است که بدانیم چه چیزی برای خواننده آشناست.

✗ بد فرض کنید خواننده همه کارهای شما را می داند

در این مقاله، Docker را به توسعه‌دهندگانی که قبلا در مورد آن نشنیده‌اند، معرفی می‌کنم.

داکر ساده است. این چیزی نیست جز یک فرانت اند نرم برای cgroup های لینوکس. اوه، شما زندان های *BSD را می شناسید؟ Docker نسخه لینوکس آن است.

بسیاری از توسعه دهندگان می خواهند از Docker استفاده کنند اما عباراتی مانند cgroups، jails یا *BSD را نمی شناسند. آنها حتی ممکن است ندانند لینوکس چیست، به خصوص اگر به دنبال معرفی Docker باشند.

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

✓ خوب فرضیات مربوط به دانش پیشینه خواننده را به حداقل برسانید.

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

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

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

– تایلر سیپریانی، زمانی که در حین ویرایش «آینده فایل‌های بزرگ در Git است Git»، مفروضات مربوط به خواننده هدف او را به چالش کشیدم.

آخرین باری که کتابی را خواندید که به شما دستور داد خواندن را متوقف کنید، کتاب دیگری بخرید، آن را کامل بخوانید و سپس کتاب اصلی خود را ادامه دهید؟ وبلاگ نویسان نرم افزار همیشه این کار را انجام می دهند، اگرچه ظریف تر است.

وبلاگ نویسان اغلب می خواهند اصطلاحی را ذکر کنند که خواننده ممکن است آن را نداند، اما خودشان تمایلی به توضیح آن ندارند. در عوض، آنها پیوندی را روی این اصطلاح می زنند و فکر می کنند، "مشکل حل شد!"

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

✗ بد برای توضیح شرایط به خواننده به پیوندها تکیه کنید

قوانین فایروال را برای جلوگیری از رسیدن ترافیک خارجی به پایگاه داده خود تعیین کنید.

کتابچه راهنمای FreeBSD که در بالا لینک شده است یک منبع عالی است، اما فصل مربوط به فایروال ها حدود 20000 کلمه است. وقتی به چنین صفحه‌ای پرمخاطب پیوند می‌دهید، حجم زیادی از کار را روی خواننده می‌ریزید.

به جای تکیه بر پیوندی که کارتان را برای شما انجام می دهد، حداقل توضیح ممکن را برای درک مقاله خود به خواننده بدهید.

✓ خوب اطلاعات مربوطه را در پشت یک پیوند خلاصه کنید

فایروال سیستمی است که نحوه ارتباط میزبان ها و شبکه ها با یک برنامه را محدود می کند. می‌توانید با پیکربندی قوانین فایروال، امنیت برنامه وب خود را افزایش دهید تا درخواست‌های ورودی فقط زمانی به سرور پایگاه داده شما اجازه دهند که از سرور برنامه شما منشأ گرفته باشند.

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

این روزها همه چیز یا دنباله یا راه اندازی مجدد است، از جمله پست های وبلاگ. من پست های وبلاگ زیادی را می بینم که به این شکل باز می شوند:

در بخش اول، ما در مورد لیست های پیوندی پنج تایی و اینکه چگونه آنها می توانند خروجی LOC روزانه شما را 100 برابر کنند، یاد گرفتیم. در پست امروز، من به شما نشان خواهم داد که چگونه عبارات goto به شما اجازه می دهد که scrunkmax کنید (اصطلاحی که در قسمت اول اختراع کردم - یادتان هست؟).

من از شکستن آن برای شما متنفرم، اما اکثر خوانندگان قسمت اول را نخوانده اند. اگر فرض کنید آخرین مقاله شما در ذهن خواننده تازه باشد، آنها فکر می کنند، "اوه، اکنون کار اضافی برای شروع حتی خواندن وجود دارد؟"

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

اگر در مورد سیستم عامل سرگرمی‌ای که از ابتدا ساخته‌اید می‌نویسید، مطمئنا احتمالا به بیش از یک پست وبلاگ نیاز دارید، اما اکثریت قریب به اتفاق پست‌های دنباله‌دار می‌توانند مقالاتی مستقل با حدود 3 درصد تلاش بیشتر باشند.

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

چندین ابزار تجزیه و تحلیل استاتیک توسط هم تیمی هایم و خودم در طول مدت این پروژه استفاده شد.

شما برای مدیران 80 ساله IBM در سال 1988 نمی نویسید. رشته شما توسعه نرم افزار است، یکی از کم ادعایی ترین مشاغل یقه سفید. شخصی که مقاله شما را می خواند احتمالا در حالی که از یک کاسه غلات کنار صفحه کلید خود مشغول خوردن است، لباس خواب و دمپایی به تن دارد. آنها انتظار یا نمی خواهند که شما مانند یک سند قانونی صحبت کنید.

ما چند آنالایزر استاتیک را در این پروژه امتحان کردیم.

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

همه بچه‌هایی که در دبیرستان بازی‌های پنگ نوشتن را در BASIC برای Apple II خود عالی می‌خواندند، به دانشگاه می‌رسند، CompSci 101، یک دوره ساختار داده‌ها را می‌گذرانند، و زمانی که به کار اشاره‌گرها برخورد می‌کردند مغزشان کاملا منفجر می‌شد، و نکته بعدی که می‌دانستید، در رشته علوم سیاسی بودند، زیرا به نظر می‌رسید دانشکده حقوق ایده بهتری است.

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

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

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

اجازه دادن به متن از روی صفحه نمایش در تلفن همراه، تجربه خواندن بدی را ایجاد می کند.

نسخه های دسکتاپ فایرفاکس و کروم هر دو دارای حالت پیش نمایش موبایل هستند. قبل از انتشار مقاله خود را با پیش نمایش تلفن همراه بررسی کنید و مشکلات رندر رایج را بررسی کنید.

خوانندگان موبایل خود را دست کم نگیرید. بر اساس تجزیه و تحلیل من، 25 درصد از شما در حال خواندن این صفحه در تلفن های خود هستید. در وبلاگ شخصی من، 35٪ است.

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

ابزار دسترسی فایرفاکس که متن با کنتراست پایین را شناسایی می کند

اگر تمایلی به جستجوی فونت مناسب در اطراف ندارید، موسسه بریل فونت رایگانی به نام Atkinson Hyperlexible دارد که خواندن آن بسیار راحت است، حتی برای خوانندگانی که بینایی ضعیفی دارند.

تصاویر "نه کاملا چگونه توسعه دهندگان می خوانند" و "خواننده چه می داند" توسط پیوتر لتاچوویچ.