چه چیزی باعث ایجاد مستندات خوب می شود؟ اساساً در مورد سازماندهی و سهولت ردیابی بصری است. در اینجا برخی از مظاهر آن، بدون ترتیب خاصی وجود دارد.
متأسفانه، نمی‌توانید دیگران را مجبور کنید اسناد را آنطور که شما می‌خواهید بنویسند. شما می توانید امتحان کنید، اما شما فقط مانند یک تند و سریع به نظر می رسید. رویکرد بهتر برای شما برای نوشتن اسنادی که به بهترین شیوه ها پایبند باشد. زمانی که به یادداشت‌های خود رجوع می‌کنید، نه تنها مفیدتر است، بلکه به دیگران الهام می‌دهد تا بازی خود را ارتقا دهند.
پاشیدن قالب‌بندی خاص رنگارنگ نیز برای دو برابر کردن صفحه به عنوان یک مرجع سریع عالی است. به عنوان مثال، اگر خواننده با صفحه آشنا باشد، اما باید آن یک هشدار مهم را جستجو کند، برای او راحت تر است که تا زمانی که کادر را پیدا کند، پیمایش کند تا اینکه Ctrl-F آن را جستجو کند. جمله بندی مطالب را به خاطر بسپارید
لینک ها به طور آزادانه گنجانده شده اند. نویسندگان اسناد باید تا حد امکان به صفحات مربوط به سیستم های مرتبط پیوند دهند. آیا تاکنون اسنادی با پیوندهای بیش از حد دیده اید؟ من اینطور فکر نمی کردم.
زمانی که کد درون خطی دارای پس‌زمینه کمی سایه‌دار باشد، امتیاز امتیاز می‌دهد. باز هم، این برای کمک به تشخیص آن در طول اسکن بصری است. تکه های بزرگ کد باید در چیزی مانند یک جعبه فراخوانی محصور شوند. اگر کدهای زیادی وجود دارد که ارزش خواندن دارند، از دست دادن آن غیرممکن است.
شامل یک اسکریپت و دستور دادن به خوانندگان برای اجرای آن. هرگز، فقط یک اسکریپت اجرا کنید نیت نویسنده معمولاً خوب است. آنها می خواهند به خواننده اجازه دهند مقداری بار شناختی را تخلیه کند. اما نویسنده هرگز نمی تواند مطمئن باشد که مورد استفاده خواننده با آنچه که فیلمنامه در نظر گرفته است مطابقت دارد یا مهارت هایی برای ارزیابی اینکه آیا چنین است.
جداول نیز یکی دیگر از نشانه های بصری عالی هستند. من نمی توانم با ترجیحات همه صحبت کنم، اما مغز من اگر اطلاعات را در یک جدول در مقایسه با یک پاراگراف نشان دهد، بهتر جذب می کند. تصور کنید باید تا آنجا که می توانید صفحه ای را که فقط یک بار دو هفته پیش خوانده اید، فقط با یک نگاه سریع به خاطر بیاورید. چه چیزی را بهتر به شما یادآوری می کند: نگاه کردن به صفحه ای با یک میز بزرگ یا صفحه ای که تنها متن دارد؟
این به این معنا نیست که نویسندگانی را که در حال حاضر زمان کمیاب است، در تولید اسناد فشرده کنند. من به‌تازگی مشاهده کردم که این به اندازه‌ای بد است که به شما توصیه می‌کنم که تماشای قالب‌بندی نامطلوب فقط مراقب خودتان است.
با توجه به تمایل من به مهندسی نرم افزار و نویسندگی، یکی از مواردی که در نقشم برایم برجسته بوده، مستندسازی است. احتمالاً باید این را پیش‌بینی می‌کردم، اما در حالی که دیوانه‌وار همه چیز را دنبال می‌کردم به آن نرسیدم، خوب؟ من اسناد خیره‌کننده‌ای را دیده‌ام که خواننده را در سفری از طریق کد و اسنادی راهنمایی می‌کند که تقریباً چشمانم را از دیوارهای متنی که به سختی مرتبط بودند خیره می‌کردند.
از سوی دیگر، نویسنده ممکن است بر فرضیات غیرواقعی تکیه کرده باشد یا فقط یک فیلمنامه slapdash نوشته باشد. لازم نیست فیلمنامه را نادیده بگیرید. شما فقط باید قبل از استفاده از آن برای هر چیزی آن را بخوانید.
اسنادی را که می خواهید در جهان بخوانید بنویسید
تکه‌های کد، چه درون خطی و چه در یک بخش قالب‌بندی شده جداگانه، به صورت monospace استایل داده می‌شوند. اگر کد در صفحه مستندات شما وجود دارد، احتمالاً برای استفاده یا بررسی در پروژه است. هر دو دلیل کافی برای خروج کد شما از بافت هستند.
فراتر از فقدان موارد فوق، در اینجا برخی از ویژگی ها وجود دارد که با حضور آنها، تجربه مصرف مستندات ناامید کننده ای را ایجاد می کند.
در این مرحله، من به وضوح نشان می‌دهم که این کار را کرده است. این نقش من را در معرض انواع سیستم های کامپیوتری ایجاد شده توسط افراد مختلف در طول زمان قرار داده است. همه این سیستم ها مرا مجبور کرده اند تا حجم عظیمی از دانش فنی را به سرعت جذب کنم.
پس از خواندن ده‌ها صفحه، شهودی برای آنچه که نمونه‌ها را از سوگواران جدا می‌کرد، به وجود آوردم. آنچه در پی می آید تقطیر آگاهانه آن شهود است.
صورت افلاطونی (at) خیر
نویسنده و تیم های درگیر اطلاعات تماس را ارائه می دهند. نرم افزار تغییر می کند، اما اسناد همیشه ادامه نمی دهند. وقتی این اتفاق می‌افتد، دانستن اینکه برای به‌روزرسانی‌ها با چه کسی باید چک کنید، مفید است. هر چیزی کمک می کند، حتی نام، اما مفیدترین اطلاعات تماس ایمیل لیست سرویس تیم است. هم‌تیمی‌های فردی می‌آیند و می‌روند، اما لیست‌سرور معمولاً بدون توجه به اینکه چه کسی در آن تیم است پینگ می‌زند.
این ماه یک سال از زمانی که من فعلی و فنی ترین نقش حرفه ای ام را بر عهده گرفتم می گذرد. من قصد نداشتم آن را مخفی نگه دارم. در واقع، این موضوع خیلی در نوشتن من نقشی نداشت.
تبلیغات
داده های رابطه ای در جداول سازماندهی شده اند. بهترین چیز در مورد جداول این است که آنها تداعی را نشان می دهند. اینها هم به صورت افقی، که در آن یک آیتم دارای چندین ویژگی است، و هم به صورت عمودی، که در آن بسیاری از موارد دارای یک کلاس از ویژگی ها هستند، گسترش می یابند. کامپیوترها بر اساس ارتباط ساخته شده اند. این همه یک متغیر اختصاص داده شده است، اساس عملاً همه زبان های برنامه نویسی، واقعاً – یک مقدار مرتبط با نام مرجع یا مکان.
قالب بندی مطابقت ندارد. علاوه بر این واقعیت که بد به نظر می رسد و ممکن است صفحه را ناخوانا کند، قالب بندی نامرتب نشان می دهد که نویسنده بدون هیچ تلاشی برای متن یا تطبیق اطلاعات، کپی و جایگذاری کرده است. گاهی اوقات اطلاعات به همان اندازه دقیق است، اما در برخی مواقع، زمینه از دست رفته می تواند خواننده قابل اعتماد را به مسیر اشتباه هدایت کند.
چند راه برای شناسایی اسناد غیرقابل اعتماد وجود دارد. یکی وجود کلماتی مانند “کار در حال انجام”، “تحقیقی”، “پیشنهاد شده” و غیره است، به خصوص زمانی که صفحه مدتی است به روز نشده است. آیا آن جزئیات مبهم نهایی شد، آیا توسعه دهندگان فراموش کردند صفحه را به روز کنند، یا پروژه کنار گذاشته شد؟
مثال‌ها، یادآوری‌ها، هشدارها و غیره در جعبه‌های فراخوانی محصور شده‌اند. این عمل نه تنها توجه خواننده را به محتویات آن معطوف می‌کند، بلکه به شکستن چیزی که در غیر این صورت یک دیوار یکنواخت از متن بود، کمک می‌کند.
تبلیغات
هیچ نشانه ای از صحت اطلاعات وجود ندارد. این یک مورد یواشکی است زیرا به طور قابل درک وسوسه انگیز است که فرض کنیم اگر در سند باشد، درست است. اما آیا شما واقعاً شواهد واقعی برای اثبات آن دارید؟ نرم افزار از توانایی توسعه دهندگان برای نوشتن آن پیشی می گیرد. گاهی نویسندگان فقط اشتباه می کنند.
در حالی که از ابتدا برخی از عادات سازنده ذکر شده را دنبال می کردم، بسیاری از آنها را انتخاب کردم زیرا آنها را در جای دیگری مشاهده کردم و فکر کردم، “من این کار را شروع خواهم کرد.” آن شخص ممکن است شما نیز باشید.
سازمان ضعیف است. سازمان دهی ضعیف اشکال مختلفی دارد، اما فاجعه آمیزترین آن نبود یا ناهماهنگی سرفصل های بخش است. حتی اگر فهرست مطالب مرتبط داخلی وجود نداشته باشد، داشتن سرفصل‌هایی برای پیمایش، تشخیص آنچه را که به دنبال آن هستید از جزئیات نامربوطی که شما را درگیر می‌کند بسیار آسان‌تر می‌کند.
یکی دیگر از نشانه‌های دقت مشکوک، سندی است که ادعاهای بزرگی را بدون پیوند ایجاد می‌کند و هیچ صفحه دیگری آن را تأیید نمی‌کند. اگر این را می بینید، قبل از تکیه بر آنچه می خوانید، دو بار فکر کنید.
نمودارها گنجانده شده است. هر چیزی که برای جداول کاربرد دارد در نمودارها نیز صدق می کند، اما بیشتر. روابط با اشکال ساده نشان داده شده است که مغز شکارچی ما در پردازش آنها خوب است. نمودارها برای درک ریزسرویس ها حیاتی هستند زیرا منطق زیادی فراتر از یک برنامه یا سرویس خاص در حال بررسی وجود دارد.