این صفحه حاوی جزئیات یک پروژه نگارش فنی است که برای فصل اسناد Google پذیرفته شده است.
خلاصه ی پروژه
- سازمان متن باز:
- ESLint
- نویسنده فنی:
- خاور
- نام پروژه:
- سازماندهی مجدد/بازنویسی اسناد پیکربندی
- طول پروژه:
- طول استاندارد (3 ماه)
شرح پروژه
خلاصه
هدف این پروژه بازسازی اسناد پیکربندی برای ESLint و ایجاد یک معماری اطلاعات موثر است. این امر ناوبری را آسان تر می کند و همچنین قابلیت استفاده و سودمندی اسناد را بهبود می بخشد.
خلاصه پروژه مستندات پیکربندی ESLint (https://eslint.org/docs/user-guide/configuring)، در وضعیت فعلی، اطلاعات زیادی را در یک صفحه فراهم می کند. علیرغم وجود سرفصل‌ها، عنوان‌های فرعی و پاراگراف‌بندی مناسب در صفحه، مستندات می‌توانند بسیار زیاد شوند. هیچ راهی برای پیمایش به بخش خاصی از صفحه که برای کاربر علاقه مند به یک بخش خاص خسته کننده باشد وجود ندارد. اطلاعات، به دلیل این عدم سازماندهی، می تواند از بین برود و در خدمت هدف خود قرار نگیرد و از کاربران بخواهد تلاش بیشتری انجام دهند.
با این حال، این مسائل را می توان با یک سری اقدامات دقیق حل کرد. من یک حسابرسی محتوا را به عنوان اولین گام در این سازماندهی مجدد پیشنهاد می کنم. ممیزی محتوا نه تنها به شناسایی مسائل در ارائه اطلاعات کمک می کند، بلکه کاستی های خود محتوا را نیز برجسته می کند (به عنوان مثال اطلاعات قدیمی یا ناقص). سپس قصد دارم معماری اطلاعات (IA) را برای رونمایی از شبکه دانش ایجاد کنم. این ما را قادر می سازد تا اطلاعات را بر اساس موضوعات مختلف خوشه بندی کنیم و پیوندهایی را بین موضوعات مختلف مرتبط با هم پیدا کنیم. سپس بینش‌های به‌دست‌آمده از این دو روش برای تقسیم اسناد تک صفحه‌ای به چندین صفحه استفاده می‌شود. سپس کل بسته را می توان در Markdown پیوند داد و ارجاع داد. در نتیجه، یک نسخه سازمان‌یافته‌تر از اسناد پیکربندی وجود خواهد داشت، نسخه‌ای که پیمایش و درک آن آسان‌تر است.
انگیزه علیرغم این واقعیت که من مدت زیادی است که از نرم افزار منبع باز استفاده می کنم، آشنایی من با این اصطلاح تقریباً جدید است، مشابه دانش من در مورد نرم افزار Linting. وقتی شروع به یادگیری پایتون کردم (از طریق edX)، تعجب کردم که چگونه خطاهای کوچک می توانند کل کد را به هم بریزند. من فکر کردم خوب است که کدهای شما به نحوی آزمایش شود و خطاهای شما شناسایی شود، و سپس با اصطلاح "linting" آشنا شدم. من هنوز به درستی از نرم افزارهای لینتینگ استفاده نکرده ام، اما مطمئن هستم که این نرم افزارها در روزهای آینده زندگی من را بسیار آسان تر خواهند کرد.
با سابقه ای که در مهندسی برق دارم و کمی تجربه در برنامه نویسی دارم، می توانم مشکلات کدنویسی و نیازهای برنامه نویسان را به نحو بهتری درک کنم. علاوه بر این، مدرک تحصیلات تکمیلی من در ارتباطات فنی و حرفه ای باعث می شود که من مدافع کاربران باشم و سعی کنم زندگی را برای مردم آسان تر کنم. مهارت ها و تخصص من به عنوان یک ترکیب خوب برای این پروژه عمل می کند و به اسناد ESLint ارزش می بخشد.
اهداف هدف کلی این پروژه این است که اطمینان حاصل شود که اسناد موجود در صفحه پیکربندی ESLint به راحتی قابل درک است و کاربران را تحت فشار قرار نمی دهد. برای موفقیت پروژه مهم است که پیمایش در محتوا آسان و عاری از هرگونه پیچیدگی باشد. اهداف مهم پروژه به شرح زیر می باشد. - انجام ممیزی جامع محتوا - ایجاد یک معماری اطلاعاتی برای درک جریان اطلاعات - بهبود معماری اطلاعات برای سازماندهی مجدد اسناد - شناسایی پیوندها و مراجع بین بخش های مختلف محتوا - بازنویسی/ویرایش بخش هایی از اسناد، در صورت لزوم برای برآورده شدن الزامات پیکربندی مجدد
- اطمینان حاصل کنید که محتوا انعطاف پذیر و قابل استفاده مجدد است
توضیحات پروژه پیکربندی ESLint یک ویژگی مهم است که ESLint را قابل تنظیم می کند. کاربرانی که به پیکربندی علاقه مند هستند مطمئناً در یک زمان معین به یک یا دو جنبه علاقه مند خواهند بود. بنابراین، مهم است که کاربر به موضوع خاص مورد علاقه خود هدایت شود، بنابراین راه حل را به روشی کارآمد در اختیار آنها قرار دهد. وضعیت فعلی اسناد پیکربندی برای ESLint حاوی اطلاعات مفید زیادی است، اما به گونه ای سازماندهی شده است که می تواند باعث شود کاربران احساس ناراحتی، ناامیدی و گم شدن کنند. به عنوان مثال، اگر کسی علاقه مند به یادگیری در مورد استفاده از افزونه های شخص ثالث در ESLint است، باید از طریق بحث در مورد تعیین تجزیه کننده، محیط ها و جهانی ها به پایین پیمایش کند. کل این تمرین برای کاربران خسته کننده است و می تواند آنها را از وب سایت دور کند. به همین ترتیب، اگر کاربر جایی در وسط صفحه باشد و بخواهد به بخش خاصی برود یا صرفاً موضوعات مشابه را بررسی کند، کار آسانی برای او نخواهد بود، زیرا چنین کمکی به کاربران ارائه نمی شود. این مسائل نیاز به توجه فوری دارند زیرا کیفیت هر مستندی، مهم نیست که چقدر خوب پیش‌نویس شده باشد، به مفید بودن آن بستگی دارد. من راه حل هایی را برای این موارد و سایر مسائل مرتبط در بحث بعدی پیشنهاد می کنم.
حسابرسی محتوا اولین گام در فرآیند سازماندهی مجدد اسناد پیکربندی، انجام ممیزی محتوای جامع خواهد بود. هدف ممیزی شناسایی برخی مسائل کلیدی مانند محتوای قدیمی، تکراری، محتوای گمشده، و غیره خواهد بود. صفحه گسترده ممیزی محتوا که در نتیجه ایجاد شده است برای بازخورد با تیم های مدیریت و مستندسازی به اشتراک گذاشته می شود. این به ارائه یک استراتژی جدید برای ساختار و ارائه مستندات کمک خواهد کرد.
ایجاد معماری اطلاعات برای درک شبکه دانش یا جریان اطلاعات در اسناد پیکربندی، ایجاد معماری اطلاعات (IA) می تواند ارزشمند باشد. یافته های ممیزی محتوا به عنوان یک پایه خوب برای درک و توسعه جریان اطلاعات عمل می کند. سپس یک نسخه بهبود یافته از IA برای سازماندهی و ارائه اسناد به روشی بهتر ایجاد می شود. این IA بهبودیافته نه تنها محتوای فعلی را بازسازی می‌کند، بلکه پیوندها و فورک‌ها را بین بخش‌های مختلف اسناد شناسایی می‌کند و در نتیجه یک شبکه کارآمد ایجاد می‌کند. به عنوان مثال، محتوای مربوط به "پیکربندی قوانین" را می توان با پیوندی به "غیرفعال کردن قوانین با نظرات درون خطی" دنبال کرد. سایر پیوندهای این چنینی نیز قابل شناسایی هستند، بنابراین روابط بین بخش های مختلف اسناد ایجاد می شود.
فهرست مطالب ممیزی محتوا و IA اطلاعات کافی را برای ایجاد فهرست مطالب مفصل با پیوندهای منتهی به بخشها و زیربخش‌های خاص اسناد ارائه می‌کنند. ایجاد فایل های جداگانه برای هر بخش و افزودن ارجاع مناسب به بخش های دیگر می تواند ارزش کل مجموعه اسناد را بیافزاید. برای کاربرانی که روی اسناد پیکربندی قرار می گیرند، می توان فهرستی از محتویات ایجاد کرد، بنابراین به سفر آنها در هنگام حضور در وب سایت کمک می کند. فهرست مطالب می تواند شامل تمام سرفصل های سطح اول و دوم باشد تا مختصر و در عین حال جامع باشد. به عنوان مثال، یکی از این روش ها، روشی است که توسط Prettier (https://prettier.io/docs/en/index.html) برای سازماندهی اسناد استفاده می شود.
تمام مستندات با استفاده از Markdown ایجاد می شود تا همه چیز ساده و منظم باشد. مراقبت ویژه برای اطمینان از اینکه اسناد قابل استفاده مجدد هستند زیرا ممکن است در آینده رشد کنند و تغییر کنند، انجام می شود.
ابزارهایی برای استفاده برخی از ابزارهای مهمی که می توانند در حین کار بر روی پروژه مفید باشند عبارتند از - Draw.io برای ایجاد تصاویر برای IA در صورت نیاز - Atom (یا ویرایشگر مشابه) برای نوشتن و ویرایش اسناد در Markdown
- GitHub برای اطمینان از کنترل نسخه اسناد
نقاط عطف از ارائه پیشنهاد تا تکمیل پروژه، نقاط عطف آزمایشی زیر تضمین می‌کند که پروژه در زمان مقرر تکمیل می‌شود و جریان صحیح را در فرآیند حفظ می‌کند.
10 ژوئیه 2020 - 16 آگوست 2020: بررسی و انتخاب پیشنهاد من مستندات ESLint را بررسی می کنم و مهارت های مورد نیاز برای تکمیل پروژه را توسعه خواهم داد (مانند نوشتن Markdown، همکاری در GitHub). من همچنین از طریق GitHub به مستندات کمک خواهم کرد و با افراد دیگر تعامل خواهم داشت تا درک بهتری از مستندات داشته باشم.
17 آگوست 2020 - 13 سپتامبر 2020: پیوند جامعه در طول دوره پیوند با جامعه، من پیشنهاد خود را طبق بحث با مربیان و تیم های مربوطه اصلاح خواهم کرد. همچنین در صورت نیاز اهداف و نقاط عطف را ویرایش خواهم کرد. علاوه بر این، من مطمئن می شوم که ابزارهایی را که برای کار بر روی پروژه مورد استفاده قرار می گیرند، لیست کوتاهی می کنم.
14 سپتامبر 2020 - 19 سپتامبر 2020: ممیزی محتوا برای شروع پروژه، من یک ممیزی محتوای جامع از اسناد پیکربندی انجام خواهم داد. هدف برجسته کردن مسائل مربوط به محتوا و ارائه آن خواهد بود.
20 سپتامبر 2020 - 25 سپتامبر 2020: معماری اطلاعات (IA) پس از ممیزی محتوا، IA اسناد پیکربندی را ایجاد خواهم کرد. من بر ارائه شبکه دانش به شیوه ای قابل فهم تمرکز خواهم کرد. سپس این به بهبود جریان اطلاعات کمک خواهد کرد.
26 سپتامبر 2020 - 30 سپتامبر 2020: پیوندها و مرجع من IA را در این مرحله تجزیه و تحلیل خواهم کرد تا پیوندها و ارجاعات بین بخش های مختلف اسناد را ترسیم کنم. من همچنین یک سلسله مراتب از تمام بخش ها ایجاد می کنم، بنابراین IA را در این فرآیند بهبود می بخشم.
01 اکتبر 2020 - 03 اکتبر 2020: نقشه نهایی با کمک بینش های به دست آمده از طریق ممیزی محتوا و IA، سپس نقشه نهایی را ایجاد خواهم کرد تا در اسناد پیکربندی مجدد اجرا شود. این نقشه جامع شامل فهرست مطالب، سلسله مراتب موضوعات و فهرستی از پیوندها و ارجاعات متقابل بین بخش‌های مستندات است.
04 اکتبر 2020 - 05 اکتبر 2020: بحث در این مرحله، یعنی قبل از ویرایش اسناد، یافته ها و برنامه های خود را به مربیان و تیم های مربوطه ارائه خواهم کرد. بازخورد آنها به اصلاح طرح و ایجاد تغییرات در صورت لزوم کمک خواهد کرد.
06 اکتبر 2020 - 20 اکتبر 2020: بازنویسی و ویرایش در این دوره، بخش هایی از اسناد را که نیاز به کار است ویرایش و به روز می کنم. برخی از بخش‌های اسناد پیکربندی ممکن است بازنویسی شوند یا موارد جدیدی به آن اضافه شوند. تمرکز در این مرحله بر این خواهد بود که اطمینان حاصل شود که اسناد دقیق، به روز، انعطاف پذیر و قابل استفاده مجدد هستند.
21 اکتبر 2020 - 25 اکتبر 2020: اصلاحات و پیوندها در این مرحله، من کارهای خودم را مرور می کنم تا از شر اشتباهات گرامری و ساختاری خلاص شوم و همچنین صحت کارم را دوباره بررسی کنم. من همچنین پیوندها و ارجاعاتی را بین بخشها، طبق IA اضافه می کنم تا اطمینان حاصل کنم که اسناد از نقشه دانشی که قبلاً طراحی شده است پیروی می کند.
26 اکتبر 2020 - 31 اکتبر 2020: نسخه نهایی برای ارسال، همه فایل‌های Markdown را پیوند می‌دهم، فهرستی از مطالب ایجاد می‌کنم و پیش‌نویس‌ها را با مربیان به اشتراک می‌گذارم. این به عنوان ارائه اولین پیش نویس، در قالب یک بسته کامل عمل می کند.
01 نوامبر 2020 - 05 نوامبر 2020: اولین بررسی در طی این پنج روز، اولین پیش نویس را با مربیانم بحث خواهم کرد. بازخورد آنها را دریافت خواهم کرد و ایده هایم را با آنها در میان خواهم گذاشت تا فهرستی از ویرایش هایی که باید انجام شوند ایجاد کنم.
06 نوامبر 2020 - 12 نوامبر 2020: اولین ویرایش ها با کمک بازخورد مربیان، اولین پیش نویس مستندات را ویرایش خواهم کرد. ویرایش‌های واقعی به ماهیت نظرات و بازخوردها بستگی دارد، اما اهداف استفاده مجدد، دقت و انعطاف‌پذیری به عنوان منبع مرحله ویرایش عمل می‌کنند.
13 نوامبر 2020 - 15 نوامبر 2020: بررسی دوم پس از تکمیل ویرایش های اولیه، یک بار دیگر با مربیان خود و تیم های مربوطه درباره پیشرفت صحبت خواهم کرد. این بحث‌ها بر ویرایش‌های انجام‌شده در نسخه اول متمرکز می‌شود و همچنین هر موضوع دیگری را که ممکن است در فرآیند ویرایش مطرح شده باشد برجسته می‌کند.
16 نوامبر 2020 - 19 نوامبر 2020: ویرایش های دوم سپس یک دوره چهار روزه را به ویرایش سند اختصاص خواهم داد. نسخه های تولید شده در نتیجه با مربیان بحث خواهد شد تا شکل نهایی به آنها داده شود. اسناد، در پایان این مرحله، به شکل نهایی خواهند بود و آماده آپلود در وب سایت و مخزن GitHub خواهند بود.
20 نوامبر 2020 - 23 نوامبر 2020: بارگذاری در وب سایت پس از انجام کلیه ویرایش های لازم، اسناد در وب سایت بارگذاری می شوند. هر گونه مشکلی که در این فرآیند با آن مواجه شود بر این اساس رسیدگی خواهد شد زیرا ما هنوز چند روز فرصت داریم تا روی مستندات کار کنیم.
24 نوامبر 2020 - 28 نوامبر 2020: گزارش پروژه گزارش مفصلی از پروژه در این دوره پنج روزه ایجاد خواهد شد. اهداف، مبارزات، مسائل و راه حل های ارائه شده بخشی از گزارش پروژه را تشکیل می دهند. گزارش برای بازخورد با مربیان به اشتراک گذاشته خواهد شد.
29 نوامبر 2020 - 30 نوامبر 2020: ارسال نهایی پروژه به همراه کلیه پرونده ها و گزارش پروژه به مربیان ارائه می شود. بررسی کل پروژه از طریق یک جلسه/بحث با مربیان و تیم های مربوطه انجام خواهد شد.
در طول پروژه، من همچنان با مربیان مشورت خواهم کرد تا بازخورد ارزشمند آنها را دریافت کنم. همه این نقاط عطف را می توان بر اساس بحث با مربیان در دوره های پیوند جامعه و بررسی پیشنهادات تغییر داد.
درباره من من مدرک کارشناسی در مهندسی برق و مدرک کارشناسی ارشد در ارتباطات فنی و حرفه ای از دانشگاه ایالتی کارولینای شمالی دارم. در زمینه های نویسندگی و ویرایش فنی و حرفه ای، مدیریت ارتباطات و محتوا، مطالعات کاربردی وب و موبایل و طراحی دستورالعمل تجربه دارم. من به عنوان سردبیر فرعی برای یک نشریه آنلاین (فضای دهکده جهانی) و به عنوان کارآموز ارتباطات برای دوک فورج در دانشگاه دوک کار کرده ام. در کنار آن به نوشتن خلاقانه نیز علاقه دارم.