اسناد به عنوان کد

مستندات به عنوان کد (اسناد به عنوان کد) به یک فلسفه اشاره دارد که شما باید در حال نوشتن مستندات با همان ابزارهای کد باشید:

• ردیاب شماره
• کنترل نسخه (GIT)
• نشانه گذاری متن ساده (علامت گذاری ، بازسازی متن ، asciidoc)
• بررسی کد
• تست های خودکار

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

به طور کلی اسناد به عنوان رویکرد کد مزایای زیر را به شما می دهد:

• نویسندگان بهتر با تیم های توسعه ادغام می شوند
• توسعه دهندگان اغلب اولین پیش نویس اسناد را می نویسند
• اگر آنها مستندات را شامل نمی شوند ، می توانید ادغام ویژگی های جدید را مسدود کنید ، که باعث می شود توسعه دهندگان برای نوشتن در مورد ویژگی ها در حالی که تازه هستند ، بنویسند

برای ساختن اسناد مناسب به عنوان گردش کار کد چیزهای بیشتری وجود دارد. چند کتاب وجود دارد که توصیه می کنیم بررسی کنید:

• اسناد مانند کد - Ae Gentle
• نوشتن فنی مدرن - اندرو اتر

علاوه بر این ، یک زنجیره ابزار منبع باز وجود دارد که نشان می دهد چگونه می توان رویکرد Docs-as-code را اجرا کرد

اسناد به عنوان کد در نوشتن اسناد

نوشتن اسناد در طی سالها مذاکرات زیادی داشته است که در این موضوع لمس می کند.

2015 آمریکای شمالی

• Riona MacNamara در مورد چگونگی اتخاذ اسناد به عنوان کد به طور کامل تغییر کرده است که چگونه Google چگونه مستندات را انجام می دهد.

2016 آمریکای شمالی

• ما یک صفحه با افرادی از Rackspace ، Microsoft ، Balsamiq و Twitter داشتیم که همه در مورد نحوه اتخاذ این شیوه ها صحبت می کردند.

2016 اروپا

• مارگارت اکر و جنیفر دور از Rackspace & Capital One ، این یک نمای کلی از اسناد به عنوان کد بود.
• راشل ویتن از پانتئون در مورد اجرای این رویکردها صحبت می کند.

2017 آمریکای شمالی

• جودی پوترینو از F5 یک گزارش عملی از تجربه خود در زمینه توسعه اسناد مانند کد ارائه داد.

2018 اروپا

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

2019 اروپا

• جن لامبورن تجربه خدمات دیجیتال دولت انگلستان را در مورد اتخاذ اسناد به عنوان رویکرد کد به اشتراک گذاشت.

2020 اروپا

• Diana Lakatos PlatformOs های مختلف فرآیند کاملاً از راه دور را نشان داد که برای کمک به اعضای جامعه به محتوا و کد در پورتال توسعه دهنده خود کمک می کند ، از جمله اینکه چرا آنها از اسناد به عنوان رویکرد کد ، نحوه ایجاد یک گردش کار سرمقاله ای که می تواند برای همه مشارکت کنندگان کار کند ، و نحوه اجرای آن را نشان می دهد. از طریق GitHub

2021 آمریکای شمالی

• Swapnil Ogale در حال انتقال از ابزارهای نوشتن فناوری سنتی به اسناد به عنوان رویکرد کد بود.

2022 آمریکای شمالی

• مارسیا ریفر جانستون و دیو می از خدمات وب آمازون (AWS) داستان حرکت تیم خود را به اسناد به عنوان کد گفتند: چه کار کرده است ، چه کاری انجام نشده است ، چه چیزی بعدی است.

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

اسناد به عنوان کد در سایر کنفرانس ها ، بازیگران ویدیویی و مقالات

این رویکرد در چندین کنفرانس دیگر یا بازیگران ویدیویی فقط توسط بلندگوهای مختلف ارائه شده است.

2017

• اجلاس معماری نرم افزار 2017 ، برلین ، آلمان: Geot Starke ، Ralf D. Müller: راهنمای Hitchhiker برای مستندات معماری.(کارگاه نیمه روز)

2018

• من ترجیح می دهم بنویسم: تام جانسون: اسناد به عنوان ابزار کد و ارائه گردش کار
• نقض ، مادرید ، اسپانیا: Ralf D. Müller: اسناد به عنوان کد: ARC42 ، ASCIIDOC ، GRADLE & CO ترکیب شده است
• Javamagazin: Geot Starke ، Ralf D. Müller: راهنمای Hitchhiker برای اسناد به عنوان کد (آلمانی)
• Froscon ، Sankt Augustin ، آلمان: Christoph Stoettner: مستندات با هر ویراستار

نوشتن Docs یک جامعه جهانی از افرادی است که به مستندات اهمیت می دهند. ما یک جامعه Slack ، کنفرانس در 3 قاره و ملاقات های محلی داریم!