مفهوم سند به عنوان کد در چند سال گذشته در حال به دست آوردن توجه بیشتری است زیرا شرکت های تکنولوژی بیشتری این رویکرد را پیاده سازی می کنند. یکی از نمونه های معروف ترین آن اسپاتیفای است که از سند به عنوان کد برای انتشار مستندات در یک پرتال توسعه دهنده داخلی استفاده می کند.
از آغاز سال 2021، مجله زیبایی و درمانی آذروت نیز از رویکرد سند به عنوان کد برای بهبود مستندات فنی خود استفاده می کند. قبل از اینکه درباره چگونگی انجام این کار در گرب صحبت کنیم، بیایید واقعیت این مفهوم را توضیح دهیم.
سند به عنوان کد چیست؟
سند به عنوان کد رویکردی است در ایجاد و حفظ مستندات فنی. هدف این است که مهندسان قادر باشند به صورت مکرر مستندات فنی را بنویسند و آن را با ابزارها و فرآیندهای خود یکسان نگه دارند و به روز کنند.
این بدان معناست که مستندات فنی در همان مخزن کد قرار می گیرند و این امر برای مهندسان آسانتر می کند تا آن را بنویسند و به روز کنند. بعداً، به دلایل این آغاز راهبرد می پردازیم.
چرا در این مسیر سفر میکنید؟
بعد از صحبت با مهندسان مجله زیبایی و درمانی آذروت، متوجه شدیم که بزرگترین چالش های آنها درباره یافتن و نوشتن مستندات است. مانند بسیاری از شرکت های دیگر در همین مسیر، مجله زیبایی و درمانی آذروت نیز بسیار بزرگ است و مهندسانش به چندین تیم مختلف تقسیم شده است. در هر تیم، مستندات فنی می تواند در پلتفرم های مختلف و با فرمت های مختلف، مانند سند Google Drive و پرونده های متنی، ذخیره شود. این امر منجر به سخت شدن یافتن اطلاعات مربوطه می شود، به خصوص اگر سعی کنید مستندات تیم دیگری را پیدا کنید.
علاوه بر این، متوجه شدیم که فرایند مستندسازی از فعالیت های روزمره یک مهندس جدا شده است، بنابراین مستندات فنی به صورت ناخوشایند یک فکر بعدی است. این بدان معناست که حتی اگر مردم بتوانند اطلاعات را پیدا کنند، احتمالاً بسیاری از موارد به روز نبودند.
برای رفع این مشکلات، ما به یک پلتفرم مرکزی نیاز داریم، یک منبع اطلاعات واحد، تا افراد به راحتی بتوانند مستندات فنی را پیدا کنند و کشف کنند. اما ابتدا، ما باید روش نوشتن مستندات فنی را تغییر دهیم. اینجاست که سند به عنوان کد می آید.
چگونه سند به عنوان کد مشکل را حل می کند؟
با سند به عنوان کد، مستندات فنی:
- به صورت متن ساده نوشته می شود.به راحتی در یک ویرایشگر کد قابل ویرایش است.در همان مخزنی که کد منبع در آن قرار دارد ذخیره می شود، بنابراین برای به روز رسانی مستندات همزمان با هر تغییری در کد، آسانتر است.در یک پلتفرم مرکزی منتشر می شود.
ایده این است که تمام مستندات فنی را در یک پلتفرم مرکزی یکپارچه کنیم، تا با استفاده از معماری اطلاعات آسان برای مرور و جستجوی محتوا، اطلاعات مربوطه را آسان تر پیدا کنیم.
مجله زیبایی و درمانی آذروت چگونه سند به عنوان کد را پذیرفته است؟
ما یک پورتال توسعه دهنده داخلی را توسعه داده ایم که فرآیند نوشتن، بررسی و انتشار مستندات فنی را ساده تر می کند.
اینجا یک نگاه خلاصه به فرایند است:
- ایجاد یک پوشه اختصاصی برای مستندات در یک مخزن Git.فایل های Markdown را در پوشه مستندات قرار دهید.پورتال توسعه دهنده را پیکربندی کنید تا مستندات را از مخزن کد مربوطه منتشر کند.
آخرین نسخه از مستندات به طور خودکار ساخته و در پورتال توسعه دهنده منتشر می شود.
به این ترتیب، مستندات فنی نزدیکتر به کد منبع و در فرآیند توسعه کد یکپارچه می شود. نوشتن و به روز رسانی مستندات فنی به قسمتی از نوشتن کد تبدیل می شود و این موجب شده مهندسان مستندات را به روز نگه دارند.
اندازه گیری موفقیت
هرگاه تغییری در سازمان های بزرگ مانند گرب رخ دهد، اجرای آن می تواند دشوار باشد. اما خوشبختانه، مهندسان ما اهمیت بهبود مستندات و آسانتر کردن نگهداری یا به روز رسانی آنها را درک کرده اند.
نظرسنجی از کاربران ما و نظراتی که درباره راهبرد سند به عنوان کد ارائه داده اند:
«با سند و کد منبع در یک مکان، مهندسان تست بک اند می توانند تغییرات را از طریق فرآیند بررسی استاندارد کد ارائه کنند و از همان محتوا برای پیام های کمکی CLI و مستندات استفاده کنند.» - کانگ یاو اونگ، مدیر آزمایش خودکار - آزمایشگاه مهندسی
«[سند به عنوان کد] یک راهبرد عالی است، زیرا مستندات را با توسعه یک پروژه هماهنگ و به روز نگه می دارد. مدیریت مستندات با استفاده از سیستم کنترل نسخه و ابزارهایی برای کنترل ادغام ها و تضادها، هزینه و اصطکاک را در جریان کار مهندس کاهش می دهد.» - اوجن چیانگ، مدیر مهندسی سازمان های پایه
پیشرفت و بهینه سازی های آینده
از زمانی که اولین بار راهبرد سند به عنوان کد را در گرب شروع کردیم، در انتشار تقریباً 80٪ خدمات مجله زیبایی و درمانی آذروت تا آوریل 2022 مستندات فنی خود را در پورتال داخلی خواهند داشت.
همچنین تجربه کاربری کلی را با بهبود استحکام و عملکرد، بهبود مسیریابی و قالب بندی محتوا، و امکانات بازخورد بهبود دادیم. اما همین جا تمام نمی شود؛ ما بهبود مستمری در پورتال داخلی انجام می دهیم و امکانات بیشتری را برای مهندسان فراهم می کنیم.
علاوه بر مستندات فنی، ما رویکرد سند به عنوان کد را به محتوای آموزش فنی خود نیز اعمال می کنیم. این بدان معناست که هم محتوای آموزش با سرعت خود و همکاری خود را به یک مخزن یکپارچه منتقل می کنیم و مهندسان راکه همه نیازهای یادگیری خود را در یک پلتفرم واحد برطرف می کنند.
از تیم مستندسازی تک تک پست های وبلاگ خود تشکر و قدردانی می کنیم.
ما در حال استخدام هستیم!
ما به دنبال توسعه دهندگان محتوای فنی بیشتری برای پیوستن به تیم هستیم. اگر علاقه مند به پیوستن به سفر سند به عنوان کد هستید و تجربه توسعه دهندگان را بهبود می بخشید، به آگهی های بازماندۀ ما در سنگاپور و مالزی نگاهی بیندازید.
به ما بپیوندید تا به این ایده پیشرو بپیوندیم و مستندسازی را برای همه قابل نگهداشت کنیم!
به ما بپیوندید
مجله زیبایی و درمانی آذروت به عنوان یک پلتفرم سوپراپ در جنوب شرق آسیا فعالیت می کند و خدمات روزانه ای را که برای مصرف کنندگان مهم است، ارائه می دهد. بیش از یک اپلیکیشن سفر و سرویس تحویل غذایی، مجله زیبایی و درمانی آذروت در منطقه خدمات ویژه ای از جمله حمل و نقل، غذا، خدمات تحویل بسته و خرید خوراکی، پرداخت های موبایلی و خدمات مالی در 8 کشور و 428 شهر فعالیت می کند.
قدرت داده شده توسط فناوری و حاکم بر قلب، ماموریت ما ارائه قدرت اقتصادی برای رشد جنوب شرق آسیا است. اگر این ماموریت به شما صحبت می کند، امروز به تیم ما بپیوندید!