امروزه به عنوان یک توسعه دهنده وب با استفاده از زبان برنامه نویسی جاوا اسکریپت به ندرت پیش می آید که شما چیزی را از ابتدا بسازید. کار روزانه شما احتمالا این است که کتابخانه های مختلف جاوا اسکریپت را با یکدیگر ادغام کنید. اگر شما در حال ساخت یک اپلیکیشن تحت وب باشید شما احتمالا از فریم ورک های زبان برنامه نویسی جاوا اسکریپت مانند React، Vue و یا انگولار برای فرانت اند استفاده می کنید. برای انتقال و مدیریت داده ها نیز شما می توانید از Redux و یا GraphQL استفاده کنید. برای سمت بک اند شما احتمالا می توانید از Express و یا Loopback استفاده کنید. در انتها نیز شما نیاز دارید که برنامه های خود را تست کنید که در این مسیر Jest، Mocha و یا Jasmine  می تواند برای شما کمک کننده باشد. در انتها فریم ورک های مربوط به UI مانند بوت استرپ و احتمالا برخی از فریم ورک های نموداری دیگر برای شما وجود خواهد داشت. من در این مطلب کوتاه تقریبا 7 مورد از فریم ورک های اصلی زبان را برای شما نام بردم که تمامی این ها در یک پروژه وجود دارند. در کنار این موارد تکنولوژی هایی مانند خود زبان برنامه نویسی جاوا اسکریپت، Node.js و Typescript نیز هستند که می توانید از آنها نیز استفاده کنید.

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

چرا داکیومنتیشن در زبان برنامه نویسی جاوا اسکریپت مهم است؟

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

بسیاری از افراد اگر پروژه شما داکیومنت نداشته باشد پروژه شما را نمی بینند

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

شما نمی توانید کدهای جاوا اسکریپت خود را بعد از 6 ماه بفهمید

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

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

چه چیزی باید در داکیومنت های جاوا اسکریپت بنویسیم؟

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

مخاطبان خود را تعیین کنید

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

پروژه جاوا اسکریپت شما چه مسائلی را حل می کند؟

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

گام های سریع برای شروع و نصب پروژه شما

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

داشتن یک لیست از گام هایی که کاربران شما برای نصب محیط و اجرای پروژه شما نیاز دارند می تواند باعث شود تا پروژه شما بسیار جذاب تر به نظر بیاید.

امیدواریم تا به اینجای کار این مطلب برای شما مفید بوده باشد. حال زمان آن است که کمی عمیق تر این موضوع را برای شما بررسی کنیم.

داکیومنت جاوا اسکریپت برای کامپوننت ها و ویژگی های مختلف( بخش اول)

توجه داشته باشید تنها نکته ای که درباره پروژه خود باید به آن دقت داشته باشید این نیست که کاربران بتوانند به سرعت آن را اجرا کنند و شروع به کار کردن با آن کنند. قسمت های بسیار مهم دیگری نیز هستند که از جمله آنها میتوان به ماژول ها، کامپوننت ها، ویژگی ها، کلاس ها و ... اشاره کرد که شما باید درباره تک تک این موارد توضیح دهید. به عنوان مثال ممکن است بخشی از نرم افزار شما به زبان جاوا اسکریپت نیازمند داکیومنت جداگانه ای باشد که یک API برای تعامل با آن فراهم کرده است.

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

داکیومنت جاوا اسکریپت برای کامپوننت ها و ویژگی های مختلف( بخش دوم)

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

رعایت قواعد مربوط به لایسنس و توزیع ( بخش اول)

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

رعایت قواعد مربوط به لایسنس و توزیع ( بخش دوم)

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

نکاتی مهم برای نوشتن داکیومنت پروژه های جاوا اسکریپت( بخش اول)

به صورت کلی ما نمی توانیم تمامی موارد استفاده از داکیومنت های پروژه های جاوا اسکریپت را متوجه شویم. به صورت یک قاعده کلی می توانید به این موضوع توجه داشته باشید که خودتان را به جای کاربران قرار دهید و براساس این دیدگاه موارد مورد نیاز را در داکیومنت پروژه های جاوا اسکریپت خود قرار دهید. با این وجود ما در این بخش و بخش بعدی سعی می کنیم یک سری از نکات را به صورت کلی برای شما بیان کنیم که می تواند برای شما مفید باشد.

اولین نکته این است که افراد باید بتوانند به راحتی کدها را کپی و پیست کنند. بنابراین حتما سعی کنید این مورد را به خاطر داشته باشید و با اجرای پروژه خود حتما آن را دوباره بررسی کنید. از قرار دادن برخی از موارد نامرئی در مثال های کدهای خود خودداری کنید.

نکاتی مهم برای نوشتن داکیومنت پروژه های جاوا اسکریپت( بخش دوم)

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

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

ابزارهایی که سرعت این پروسه را افزایش می دهند

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

آشنایی با ابزار JSDoc

JSDoc یکی از محبوب ترین سازنده های داکیومنت برای زبان برنامه نویسی جاوا اسکریپت می باشد. تنها کاری که شما برای استفاده از این ابزار باید انجام دهید این است که دستور jsdoc را به همراه نام فایل مد نظر خود به عنوان یک آرگومان اجرا کنید. این دستور می تواند یک فایل HTML را به همراه داکیومنت آن که آماده استفاده است را برای شما ایجاد می کند.

Docusaurus از بهترین ابزارهای جاوا اسکریپت

Docusaurus یک ابزار پیچیده است که به شما این اجازه را می دهد یک داکیومنت کامل برای فایل های خود براساس محتوای آنها ایجاد کنید. این ابزار بر پایه React کار می کند و از ورژن های مختلف آن پشتیبانی می کند. بنابراین شما با استفاده از آن می توانید نسخه های مختلفی از داکیومنت های تولید شده خود را نگهداری کنید. از دیگر مزایای استفاده از این ابزار پشتیبانی از زبان های مختلف برنامه نویسی از جمله جاوا اسکریپت می باشد.

ابزار apiDoc

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

مثال هایی فوق العاده از داکیومنت سازی برای پروژه ها

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

خلاصه و جمع بندی

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