اگر اسناد به اندازه قانون تمیز به نظر می رسید

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

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

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

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

شکل افلاطونی خیر

چه چیزی باعث ایجاد مستندات خوب می شود؟ این عمدتا در مورد سازماندهی و سهولت ردیابی بصری است. در اینجا برخی از مظاهر آن، بدون ترتیب خاصی، آورده شده است.

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

یک اسپری هماهنگ کننده ویژه رنگارنگ نیز برای ایجاد یک صفحه دوتایی برای مرجع سریع عالی است. به عنوان مثال، اگر خواننده با صفحه آشنا باشد اما باید به دنبال آن هشدار مهم باشد، برای او راحت‌تر است که تا زمانی که کادر را پیدا کند، پیمایش کند تا جستجوی Ctrl-F، که اگر آن را به خاطر نمی‌آورد با شکست مواجه می‌شود. جمله بندی مطالب

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

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

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

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

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

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

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

عادت های بدی که باید حذف شوند مانند عادت های بد هستند

علاوه بر فقدان موارد فوق، در اینجا ویژگی هایی وجود دارد که با وجود آنها، تجربه مصرف سند را ناامید کننده می کند.

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

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

دو راه برای شناسایی اسناد غیرقابل اعتماد وجود دارد. یکی داشتن کلماتی مانند “کار در حال انجام”، “تحقیقی”، “توصیه شده”، و غیره است، به خصوص زمانی که صفحه برای مدتی به روز نشده است. آیا این جزئیات گیج کننده نهایی شده است، آیا توسعه دهندگان فراموش کرده اند صفحه را به روز کنند، یا پروژه از بین رفته است؟

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

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

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

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

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

اسنادی را که می خواهید در دنیا بخوانید بنویسید

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

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