اگر فقط اسناد به اندازه کد تمیز به نظر می رسید

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

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

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

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

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

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

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

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


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


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

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



منبع

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

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

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

عادت‌های بدی که باید مانند عادت‌های بد کنار بگذارید