مستندات نرم افزار فقط مجموعه ای از مقالات است. اما حتی آنها هم می توانند شما را دیوانه کنند. اول، شما زمان زیادی را صرف جستجوی دستورالعمل های لازم می کنید. سپس متن مبهم را می فهمید. همانطور که نوشته شده انجام می دهید، اما مشکل حل نمی شود. دنبال مقاله دیگه میگردی عصبی میشی... یه ساعت بعد از همه چیز دست میکشی و میری. مستندات بد اینگونه کار می کند. چه چیزی آن را به این شکل می کند و چگونه آن را تعمیر می کند - در زیر برش بخوانید.
در اسناد قدیمی ما کاستی های زیادی وجود داشت. تقریباً یک سال است که در حال کار مجدد آن هستیم تا سناریویی که در بالا توضیح داده شد بر مشتریان ما تأثیر نگذارد. نگاه کن، и .
مشکل 1: مقالات نامشخص و ضعیف
اگر درک مستندات غیرممکن است، هدف آن چیست؟ اما هیچ کس عمداً مقالات نامفهوم نمی نویسد. زمانی اتفاق می‌افتند که نویسنده به مخاطب و هدف فکر نمی‌کند، آب می‌ریزد و متن را از نظر خطا بررسی نمی‌کند.
- مخاطب. قبل از نوشتن مقاله، باید به سطح آمادگی خواننده فکر کنید. منطقی است که در یک مقاله برای یک مبتدی مراحل اولیه را رد نکنید و اصطلاحات فنی را بدون توضیح رها کنید، بلکه در مقاله ای در مورد یک ویژگی نادر که فقط متخصصان به آن نیاز دارند، باید معنای کلمه PHP را توضیح دهید.
- هدف. یک چیز دیگر که باید از قبل به آن فکر کنید. نویسنده باید هدف مشخصی را تعیین کند، تأثیر مفید مقاله را مشخص کند و تصمیم بگیرد که خواننده پس از خواندن آن چه خواهد کرد. اگر این کار انجام نشود، به خاطر توصیف، با توضیحاتی مواجه خواهید شد.
- آب و حشرات. اطلاعات غیر ضروری زیادی وجود دارد و بوروکراسی، اشتباهات و اشتباهات تایپی در ادراک اختلال ایجاد می کند. حتی اگر خواننده نازی گرامری نباشد، بی دقتی در متن می تواند او را خاموش کند.
نکات بالا را در نظر بگیرید، و مقالات واضح تر خواهند شد - تضمین شده است. برای بهتر کردن آن، از ما استفاده کنید .
مشکل 2. مقالات به همه سؤالات پاسخ نمی دهند
زمانی که مستندات با توسعه هماهنگ نباشد، به سؤالات واقعی پاسخ ندهد، و خطاهای موجود در آن برای سال‌ها تصحیح نشود، بد است. اینها مشکلات نه چندان مربوط به نویسنده، بلکه مربوط به سازماندهی فرآیندهای درون شرکت است.
مستندات با توسعه همخوانی ندارد
این ویژگی در حال حاضر منتشر شده است، بازاریابی قصد دارد آن را پوشش دهد، و سپس معلوم می شود که مقاله یا ترجمه جدید هنوز در مستندات نیست. حتی به این دلیل مجبور شدیم انتشار را به تعویق بیندازیم. می‌توانید از همه بخواهید تا هر چقدر که می‌خواهید وظایف را به موقع به نویسندگان فنی بسپارند، اما این کار نمی‌کند. اگر فرآیند خودکار نباشد، وضعیت دوباره تکرار خواهد شد.
ما تغییراتی در YouTrack ایجاد کرده ایم. وظیفه نوشتن مقاله در مورد یک ویژگی جدید در همان لحظه ای که آزمایش شروع می شود به عهده نویسنده فنی است. سپس بازاریابی در مورد آن یاد می گیرد تا برای ارتقاء آماده شود. اعلان‌ها همچنین به پیام‌رسان شرکتی Mattermost می‌رسند، بنابراین از دست دادن اخبار توسعه‌دهندگان به سادگی غیرممکن است.
اسناد درخواست های کاربر را منعکس نمی کند
ما عادت کرده ایم اینگونه کار کنیم: یک ویژگی ظاهر شد، ما در مورد آن صحبت کردیم. نحوه روشن کردن، خاموش کردن و انجام تنظیمات دقیق را توضیح دادیم. اما اگر مشتری از نرم افزار ما به گونه ای استفاده کند که ما انتظارش را نداشتیم چه؟ یا خطاهایی دارد که ما به آنها فکر نکرده ایم؟
برای اطمینان از کامل بودن مستندات تا حد امکان، تجزیه و تحلیل درخواست‌های پشتیبانی، سؤالات در انجمن‌های موضوعی و سؤالات در موتورهای جستجو را توصیه می‌کنیم. محبوب ترین موضوعات به نویسندگان فنی منتقل می شود تا بتوانند مقالات موجود را تکمیل کنند یا مقالات جدیدی بنویسند.
اسناد بهبود نمی یابد
انجام آن بلافاصله به طور کامل دشوار است؛ هنوز هم اشتباهاتی وجود خواهد داشت. شما می توانید به بازخورد مشتریان امیدوار باشید، اما بعید است که آنها هر مقاله تایپی، نادرستی، نامفهوم یا نامفهوم را گزارش کنند. علاوه بر مشتریان، کارمندان اسناد را می خوانند، به این معنی که خطاهای مشابهی را مشاهده می کنند. این قابل استفاده است! فقط باید شرایطی را ایجاد کنید که در آن گزارش مشکل آسان باشد.
ما یک گروه در پورتال داخلی داریم که در آن کارکنان نظرات، پیشنهادات و ایده‌های خود را در مورد مستندات می‌گذارند. آیا پشتیبانی نیاز به مقاله دارد، اما وجود ندارد؟ آیا تستر متوجه عدم دقت شده است؟ آیا شریک از مدیران توسعه در مورد اشتباهات شکایت کرده است؟ همه در این گروه! نویسندگان فنی فوراً برخی چیزها را اصلاح می کنند، برخی چیزها را به YouTrack منتقل می کنند و به دیگران زمان می دهند تا در مورد آنها فکر کنند. برای جلوگیری از خاموش شدن موضوع، هر از چند گاهی وجود گروه و اهمیت بازخورد را به شما یادآوری می کنیم.
مشکل 3. یافتن مقاله مناسب زمان زیادی می برد.
مقاله ای که یافت نمی شود بهتر از مقاله ای نیست که یافت نمی شود. شعار مستندسازی خوب باید «جستجوی آسان، یافتن آسان» باشد. چگونه می توان به این امر دست یافت؟
ساختار را سازماندهی کنید و اصل را برای انتخاب موضوعات تعیین کنید. ساختار باید تا حد امکان شفاف باشد تا خواننده فکر نکند "این مقاله را از کجا می توانم پیدا کنم؟" به طور خلاصه، دو رویکرد وجود دارد: از رابط و از وظایف.
- از رابط. محتوا قسمت های پانل را کپی می کند. این مورد در اسناد قدیمی سیستم ISP بود.
- از وظایف. عناوین مقالات و بخش ها منعکس کننده وظایف کاربران است. عناوین تقریباً همیشه حاوی افعال و پاسخ به سؤال «چگونه» هستند. اکنون به سمت این قالب می رویم.
هر رویکردی که انتخاب می کنید، مطمئن شوید که موضوع با آنچه کاربران به دنبال آن هستند مرتبط است و به گونه ای پوشش داده شده است که به طور خاص به سؤال کاربر پاسخ می دهد.
یک جستجوی متمرکز راه اندازی کنید. در یک دنیای ایده‌آل، جستجو باید حتی زمانی که املای اشتباه یا اشتباهی با زبان داشته باشید، کار کند. جستجوی ما در Confluence تاکنون نمی تواند ما را با این مورد خوشحال کند. اگر محصولات زیادی دارید و مستندات کلی هستند، جستجو را مطابق با صفحه ای که کاربر در آن قرار دارد تنظیم کنید. در مورد ما، جستجو در صفحه اصلی برای همه محصولات کار می کند، و اگر قبلاً در یک بخش خاص هستید، فقط برای مقالات موجود در آن.
محتوا و پودر سوخاری اضافه کنید. وقتی هر صفحه دارای یک منو و خرده نان باشد خوب است - مسیر کاربر به صفحه فعلی با قابلیت بازگشت به هر سطح. در مستندات قدیمی سیستم ISP، برای رسیدن به محتوا باید از مقاله خارج می‌شد. ناخوشایند بود، بنابراین ما آن را در جدید تعمیر کردیم.
لینک ها را در محصول قرار دهید. اگر افراد بارها و بارها با یک سوال مشابه به پشتیبانی مراجعه کنند، منطقی است که یک راهنمایی با راه حل آن به رابط اضافه کنید. اگر اطلاعات یا بینشی در مورد زمانی که کاربر مشکلی را تجربه می‌کند دارید، می‌توانید با یک لیست پستی به او اطلاع دهید. به آنها نگرانی نشان دهید و بار حمایت را از دوش بردارید.
در سمت راست در پنجره پاپ آپ پیوندی به مقاله ای در مورد راه اندازی DNSSEC در بخش مدیریت دامنه ISPmanager وجود دارد.
ارجاعات متقابل را در اسناد تنظیم کنید. مقالاتی که به یکدیگر مرتبط هستند باید "پیوند" شوند. اگر مقاله‌ها پشت سر هم هستند، حتماً فلش‌های رو به جلو و عقب را در انتهای هر متن اضافه کنید.
به احتمال زیاد، یک فرد ابتدا به دنبال پاسخ سؤال خود نه به شما، بلکه به یک موتور جستجو می‌رود. حیف است اگر به دلایل فنی لینکی به مستندات وجود نداشته باشد. پس مراقب بهینه سازی موتورهای جستجو باشید.
مشکل 4. چیدمان قدیمی با ادراک تداخل دارد
علاوه بر متون بد، مستندات را می توان با طراحی خراب کرد. مردم به خواندن مطالب خوش نوشته عادت کرده اند. وبلاگ ها، شبکه های اجتماعی، رسانه ها - همه مطالب نه تنها زیبا، بلکه به راحتی قابل خواندن و چشم نواز هستند. بنابراین، به راحتی می توانید درد شخصی را که متنی را مانند تصویر زیر می بیند، درک کنید.
اسکرین شات ها و هایلایت های زیادی در این مقاله وجود دارد که کمکی نمی کند، بلکه فقط در درک اختلال ایجاد می کند (تصویر قابل کلیک است)
شما نباید از مستندات با مجموعه ای از افکت ها نتیجه بگیرید، اما باید قوانین اساسی را در نظر بگیرید.
چیدمان. عرض متن متن، فونت، اندازه، عنوان، و بالشتک را تعیین کنید. یک طراح استخدام کنید و برای پذیرش کار یا انجام آن خودتان، کتاب «تایپوگرافی و چیدمان» اثر آرتیوم گوربونوف را بخوانید. این فقط یک نمای از طرح را ارائه می دهد، اما کاملاً کافی است.
تخصیص. مشخص کنید که چه چیزی در متن نیاز به تاکید دارد. معمولاً این یک مسیر در رابط، دکمه‌ها، درج‌های کد، فایل‌های پیکربندی، بلوک‌های «لطفاً توجه داشته باشید» است. تعیین تخصیص این عناصر و ثبت آنها در آیین نامه. به خاطر داشته باشید که هر چه ترشحات کمتر باشد، بهتر است. وقتی تعداد آنها زیاد باشد، متن نویز دارد. حتی گیومه ها در صورت استفاده بیش از حد صدا ایجاد می کنند.
تصاویر. با تیم موافقت کنید که در چه مواردی به اسکرین شات نیاز است. قطعاً نیازی به نشان دادن هر مرحله نیست. تعداد زیادی اسکرین شات از جمله دکمه های جداگانه، تداخل با ادراک، خراب کردن طرح. اندازه، و همچنین فرمت هایلایت ها و امضاهای روی اسکرین شات ها را تعیین کنید و آنها را در مقررات ثبت کنید. به یاد داشته باشید که تصاویر همیشه باید با آنچه نوشته شده مطابقت داشته باشند و مرتبط باشند. باز هم، اگر محصول به طور منظم به روز شود، پیگیری همه افراد دشوار خواهد بود.
طول متن. از مقالات بیش از حد طولانی خودداری کنید. آنها را به قسمت‌هایی تقسیم کنید و اگر این امکان وجود نداشت، محتوایی با لینک‌های لنگر به ابتدای مقاله اضافه کنید. یک راه ساده برای کوتاه‌تر کردن مقاله از نظر بصری، پنهان کردن جزئیات فنی مورد نیاز یک دایره باریک از خوانندگان در زیر یک اسپویلر است.
فرمت ها. چندین قالب را در مقالات خود ترکیب کنید: متن، ویدیو و تصاویر. این ادراک را بهبود می بخشد.
سعی نکنید مشکلات را با چیدمان زیبا بپوشانید. راستش را بخواهید، ما خود امیدوار بودیم که "لفاف" اسناد قدیمی را ذخیره کند - درست نشد. متن ها آنقدر نویز بصری و جزئیات غیر ضروری داشتند که مقررات و طراحی جدید بی قدرت بود.
بسیاری از موارد فوق توسط پلتفرمی که برای مستندسازی استفاده می کنید تعیین می شود. مثلا Confluence داریم. من هم مجبور شدم با او سر و کله بزنم. اگر علاقه مند هستید، داستان توسعه دهنده وب ما را بخوانید: .
از کجا باید بهبود را شروع کرد و چگونه زنده ماند
اگر اسناد شما به اندازه ISP Systems گسترده است و نمی دانید از کجا شروع کنید، با بزرگترین مشکلات شروع کنید. مشتریان سند را درک نمی کنند - متون را بهبود ببخشند، مقررات وضع کنند، نویسندگان را آموزش دهند. اسناد قدیمی است - از فرآیندهای داخلی مراقبت کنید. با محبوب ترین مقالات در مورد محبوب ترین محصولات شروع کنید: از پشتیبانی بپرسید، به تجزیه و تحلیل سایت و پرس و جو در موتورهای جستجو نگاه کنید.
بیایید بلافاصله بگوییم - آسان نخواهد بود. و بعید است که به سرعت کار کند. مگر اینکه تازه شروع کرده باشید و فوراً کار درست را انجام دهید. یک چیزی که ما با اطمینان می دانیم این است که با گذشت زمان بهتر می شود. اما این روند هرگز به پایان نمی رسد :-).
منبع: www.habr.com