تصویر نمای کلی، OpenDocs را به عنوان مکانی برای ایجاد نمودارها، مستندسازی مشترک، سازماندهی دانش، و به اشتراک‌گذاری یا انتشار نتایج معرفی می‌کندراهکار مفیدی برای کار با آن، این است که هر سند را به عنوان بخشی از یک پایگاه دانش نگهداری‌شده در نظر بگیرید، نه به عنوان یک فایل یک‌باره.
OpenDocs به عنوان یک محیط مبتنی بر وب برای مدیریت دانش و مستندسازی توصیف شده است که محتوای متنی را با مدل‌های بصری یکپارچه می‌کند. Pipeline بصری Visual Paradigm همچنین می‌تواند نمودارهای ایجادشده در Visual Paradigm Desktop یا Online را به OpenDocs متصل کند و وابستگی به تصاویر ثابتِ به‌صورت دستی صادرشده را کاهش دهد. قابلیت‌های موجود ممکن است به نسخه و پیکربندی Visual Paradigm شما بستگی داشته باشد.
۱. برنامه‌ریزی برای پایگاه دانش
قبل از نوشتن صفحات، تعیین کنید که این فضا برای چه هدفی است و چه کسانی از آن استفاده خواهند کرد. یک ساختار متمرکز، یافتن و نگهداری اطلاعات را برای افراد آسان‌تر می‌کند.
برای مثال، یک پایگاه دانش محصول یا سیستم ممکن است به این صورت سازماندهی شود:
-
نمای کلی — هدف، دامنه، مالکان و پیوندها به صفحات کلیدی
-
معماری — زمینه سیستم، اجزا، یکپارچه‌سازی‌ها و استقرار
-
فرآیندها — گردش‌کارها، رویه‌ها و نقاط تصمیم‌گیری
-
داده‌ها — موجودیت‌ها، جریان‌های داده و تعاریف
-
عملیات — کتاب‌های اجرا، پایش، بازیابی و تماس‌های پشتیبانی
-
تصمیمات — انتخاب‌های طراحی، توجیه و پیامدها
-
واژه‌نامه — اصطلاحات مشترک و مخفف‌ها
سطح اصلی را فشرده نگه دارید. مطالب جزئی را در زیرصفحات متمرکز قرار دهید و صفحات مرتبط را به یکدیگر پیوند دهید.
۲. ایجاد یک صفحه نمای کلی واضح
با صفحه‌ای شروع کنید که به خواننده جدید کمک کند تا جهت‌گیری کند. شامل:
-
هدف:این پایگاه دانش چه مواردی را پوشش می‌دهد.
-
مخاطبان:چه کسانی باید از آن استفاده کنند.
-
دامنه: چه چیزی گنجانده شده است—و، اگر مفید باشد، چه چیزی گنجانده نشده است.
-
مالکیت:چه کسی محتوا را نگهداری می‌کند.
-
پیمایش:پیوندهایی به مهم‌ترین بخش‌ها.
-
تازگی:تاریخ بازبینی یا راهنمایی برای گزارش محتوای منسوخ.
برای خوانندگانی بنویسید که از پروژه اطلاع ندارند. اختصارات غیررایج را بسط دهید و زمینه‌ی پشت نمودارهای مهم را توضیح دهید.
۳. پیش‌نویس و ساختاردهی محتوا
OpenDocs از تألیف مستندات و محتوای بصری در همان فضای کاری پشتیبانی می‌کند. نتایج جستجو یک ویرایشگر متمرکز بر Markdown و در برخی گردش‌های کاری، تجربه‌ی ویرایش WYSIWYG را توصیف می‌کنند؛ از حالت ویرایش موجود در حساب کاربری خود استفاده کنید.
الگوی قابل اعتماد صفحه عبارت است از:
-
خلاصه:نکته‌ی کلیدی در چند جمله.
-
زمینه:چرا این موضوع اهمیت دارد و چه فرضیه‌هایی اعمال می‌شود.
-
بصری:یک نمودار که ساختار، رفتار یا روابط را توضیح می‌دهد.
-
جزئیات:تعاریف، مراحل، قوانین یا توضیحات پشتیبان.
-
صفحات مرتبط:پیوندهایی به پیش‌نیازها و مواد پیگیری.
-
مالک و تاریخ بازبینی:چه کسی صفحه را بررسی می‌کند و چه زمانی.
برای رویه‌ها از عناوین توصیفی، پاراگراف‌های کوتاه و فهرست‌ها استفاده کنید. از جداول زمانی استفاده کنید که خوانندگان نیاز به مقایسه‌ی فیلدها یا اسکن حقایق ساختاریافته دارند. از نمودارهایی که اطلاعاتی را حمل می‌کنند که متن هرگز آن‌ها را توضیح نمی‌دهد، پرهیز کنید.
۴. نمودارهایی را انتخاب کنید که به یک سؤال پاسخ دهند
یک مدل بصری بر اساس مسئله‌ای که می‌خواهید خواننده درک کند، انتخاب کنید:
-
نمودار جریان یا BPMN:چه اتفاقی می‌افتد و به چه ترتیبی؟
-
نمودار مورد استفاده یا فعالیت UML:چه کسی با سیستم تعامل دارد و چه رفتاری رخ می‌دهد؟
-
نمودار مؤلفه یا استقرار UML:اجزا چه هستند و چگونه چیده شده‌اند؟
-
نمودار توالی:شرکت‌کنندگان چگونه در طول زمان با یکدیگر ارتباط برقرار می‌کنند؟
-
نمودار مفهومی داده (ERD):چه موجودیت‌های داده‌ای وجود دارند و چگونه با یکدیگر مرتبط هستند؟
-
نقشه ذهنی یا نقشه مفهومی:ایده‌ها چگونه گروه‌بندی و به هم متصل شده‌اند؟
-
نمودار گانت، نقشه راه یا ساختار شکست کار:چه کاری برنامه‌ریزی شده است و چگونه با یکدیگر هماهنگ می‌شود؟
مستندات Visual Paradigm گردش‌کارهای OpenDocs را توصیف می‌کنند که شامل انواع نمودارهایی مانند UML، BPMN، ERD، نقشه‌های ذهنی و بصری‌های برنامه‌ریزی پروژه هستند. پیش از ایجاد فرآیندی بر پایه یک نوع نمودار خاص، اطمینان حاصل کنید که آن نوع نمودار در نسخه شما موجود است.
به هر نمودار یک عنوان و توضیح کوتاه بدهید. اختصارات را تعریف کنید، مرزهای مهم را برچسب‌گذاری کنید و سطح جزئیات را متناسب با مخاطب نگه دارید. اگر نموداری خواندن آن دشوار شد، آن را به یک نمای کلی و یک یا چند نمای دقیق تقسیم کنید.
۵. افزودن نمودارها به مستندات
تصویر کلی یک چرخه ساده تألیف را پیشنهاد می‌کند: یک بصری ایجاد کنید، آن را در جایی قرار دهید که از متن پشتیبانی کند، و توضیح دهید که چگونه باید آن را خواند.
یک ترتیب عملی به این صورت است:
-
ابتدا توضیحات پیرامونی را بنویسید تا نمودار هدفی واضح داشته باشد.
-
نمودار را در ویرایشگر یا ابزار مدل‌سازی در دسترس خود ایجاد کنید.
-
آن را با استفاده از یکپارچگی‌های موجود در حساب کاربری خود در صفحه مربوطه درج یا جاسازی کنید.
-
یک زیرنویس یا متن مجاور اضافه کنید که دامنه و نکته کلیدی آن را توصیف کند.
-
بررسی کنید که برچسب‌ها در عرض صفحه‌ای که خوانندگان استفاده می‌کنند، قابل خواندن باشند.
-
صفحه را به عنوان یک خواننده بازبینی کنید، نه فقط در نمای ویرایش.
وقتی نمودارها از طریق خط لوله Visual Paradigm ارسال می‌شوند، منابع یک گردش‌کار را برای در دسترس قرار دادن آثار مدل برای OpenDocs و انتخاب آن‌ها برای استفاده در مستندات توصیف می‌کنند. این می‌تواند به کاهش نسخه‌های منسوخ کمک کند، اما تیم‌ها همچنان باید تأیید کنند که اثر جاسازی‌شده به مدل و نسخه مورد نظر اشاره می‌کند.
۶. همکاری با یک فرآیند بازبینی سبک
از یک فرآیند یکسان استفاده کنید تا همکاری دقت را بهبود بخشد، نه اینکه ویرایش‌های متضاد ایجاد کند:
-
مسئولیت را واگذار کنید:برای هر صفحه یا بخش مهم، یک مالک مشخص کنید.
-
پیش‌نویس:محتوا را بنویسید و بصری‌های لازم برای توضیح آن را شامل کنید.
-
بازبینی:از یک متخصص موضوعی بخواهید صحت را بررسی کند و از یک خواننده خارج از تیم فوری بخواهید وضوح را بررسی کند.
-
حل تغییرات:توافق بر روی ویرایش‌های متن و نمودارها.
-
انتشار یا اشتراک‌گذاری:نسخه بازبینی‌شده را در دسترس مخاطبان مورد نظر قرار دهید.
-
بازدید مجدد:صفحه را هنگام تغییر سیستم یا فرآیند بازبینی کنید.
تصویر همکاری تیمی را نشان می‌دهد، اما کنترل‌ها و دسترسی‌های دقیق همکاری ممکن است متفاوت باشد. به جای فرض اینکه هر حسابی گزینه‌های اشتراک‌گذاری یا ویرایش یکسانی را پشتیبانی می‌کند، کنترل‌های نمایش‌داده‌شده در فضای کاری OpenDocs خود را بررسی کنید.
۷. سازماندهی و نگهداری پایگاه دانش
یک پایگاه دانش خوب نیازمند مراقبت مستمر است. صفحات را به اندازه‌ای کوچک نگه دارید که قابل اسکن باشند، از عناوین یکسان استفاده کنید و موضوعات مرتبط را به هم پیوند دهید به جای تکرار توضیحات یکسان در چندین مکان.
برای هر صفحه مهم، موارد زیر را پیگیری کنید:
-
مالک مشخص
-
مخاطبان مورد نظر
-
منبع حقیقت برای مدل‌ها یا داده‌های پیوندی
-
تاریخ آخرین بازبینی
-
هرگونه محدودیت شناخته‌شده یا پرسش‌های حل‌نشده
هنگامی که یک نمودار تغییر می‌کند، متن اطراف آن را نیز بازبینی کنید. ممکن است تصویر به‌روز باشد، در حالی که توضیح، اصطلاحات یا فرآیند پیوندی نیست.
۸. اشتراک‌گذاری یا انتشار با دقت
قبل از اشتراک‌گذاری یک صفحه یا فضا، بررسی کنید:
-
آیا مخاطبان مورد نظر می‌توانند به آن دسترسی داشته باشند
-
آیا محتوا شامل اطلاعات حساس یا فقط داخلی است
-
آیا نمای اشتراک‌گذاری‌شده نمودارها و چیدمان را همان‌طور که انتظار می‌رود نمایش می‌دهد
-
آیا گیرنده به یک صفحه واحد یا کل پایگاه دانش نیاز دارد
-
آیا مواد برای خوانندگان خارجی آماده است
گزینه‌های دقیق اشتراک‌گذاری و انتشار به حساب و پیکربندی بستگی دارد. مرحله «اشتراک‌گذاری» در تصویر کلی را به عنوان یک هدف فرآیند در نظر بگیرید، نه تضمینی برای مقصد انتشار خاص یا مدل مجوز.
۹. چک‌لیست صفحه قابل استفاده مجدد
قبل از در نظر گرفتن یک صفحه آماده، تأیید کنید که:
-
عنوان و هدف مشخصی دارد
-
برای مخاطبان مورد نظر معنادار است
-
اصطلاحات ناآشنا را تعریف می‌کند
-
از نمودارهایی استفاده می‌کند که به پرسش‌های خاص پاسخ می‌دهند
-
تصاویر مهم را در متن توضیح می‌دهد
-
پیوندهایی به صفحات مرتبط و مواد اولیه دارد
-
مالک و تاریخ بازبینی را مشخص می‌کند
-
در نمای اشتراک‌گذاری یا نمای مخاطب‌محور آن بررسی شده است
نمونه گردش کار
برای مستندسازی یک سرویس جدید، با یک صفحه نمای کلی آغاز کنید که هدف و مالکیت آن را توضیح می‌دهد. یک نمودار زمینه سیستم اضافه کنید تا کاربران و وابستگی‌های خارجی آن را نشان دهد. یک نمودار مؤلفه برای بخش‌های اصلی آن ایجاد کنید، سپس جریان‌های درخواست کلیدی و رویه‌های عملیاتی را در صفحات جداگانه مستند کنید. صفحات را از طریق نمای کلی به هم پیوند دهید، آن‌ها را با تیم سرویس بازبینی کنید و نمای مناسب را با مخاطبان هدف به اشتراک بگذارید. اگر مدل زیربنایی تغییر کند، تصویر پیوندی و توضیح آن را به‌روزرسانی یا مجدداً بررسی کنید.
اصل مرکزی ساده است: فرآیند نوشتن، نمودارها، سازماندهی و اشتراک‌گذاری را به هم پیوند دهیداین همان چیزی است که مجموعه‌ای از صفحات و تصاویر را به مستندسازی مفید و قابل نگهداری تبدیل می‌کند.
This post is also available in Deutsch, English, Español, Français, Bahasa Indonesia, 日本語, Polski, Portuguese, Ру́сский, Việt Nam, 简体中文 and 繁體中文.