قد يكون لديك مشروع مفتوح المصدر أفضل ، ولكن إذا لم يكن لديه وثائق جيدة ، فمن المحتمل ألا ينطلق. في المكتب ، ستتيح لك الوثائق الجيدة عدم الإجابة عن الأسئلة نفسها. تضمن الوثائق أيضًا أن يتمكن الأشخاص من فهم المشروع في حالة مغادرة الموظفين الرئيسيين للشركة أو تغيير الأدوار. تساعد الإرشادات المباشرة في ضمان تكامل البيانات.
إذا كنت بحاجة إلى كتابة نص طويل ، فإن Markdown هو بديل رائع لـ HTML. في بعض الأحيان بناء الجملة تخفيض السعر لا يكفي. في هذه الحالة ، يمكننا استخدام HTML داخلها. على سبيل المثال ، العناصر المخصصة. لذلك ، إذا كنت تقوم ببناء نظام تصميم مع مكونات الويب الأصلية ، فمن السهل أن تدرج في الوثائق النصية. إذا كنت تستخدم React (أو أي إطار JSX آخر مثل Preact أو Vue) ، فيمكنك فعل الشيء نفسه باستخدام MDX.
هذه المقالة هي لمحة عامة واسعة عن وثائق التوثيق وأدوات التوجيه. لا تستخدم جميع الأدوات المدرجة هنا MDX ، ولكن يتم تضمينها بشكل متزايد في أدوات التوثيق.
ما هو MDX؟
يحتوي ملف .mdx على نفس بناء جملة Markdown ، لكنه يسمح لك باستيراد مكونات JSX التفاعلية وتضمينها في المحتوى الخاص بك. دعم مكونات Vue في ألفا. لبدء العمل مع MDX ، فقط قم بتثبيت "إنشاء تطبيق React App". هناك ملحقات ل Next.js و Gatsby. سيكون للإصدار التالي من Docusaurus (الإصدار 2) دعم مدمج أيضًا.
كتابة الوثائق مع Docusaurus
كتب Docusaurus على Facebook. يستخدمونه في كل مشروع مفتوح المصدر باستثناء React. خارج الشركة ، يستخدمه Redux و Prettier و Gulp و Babel.
المشاريع التي تستخدم Docusaurus.
يمكن استخدام Docusaurus لكتابة أي وثائق ، ليس فقط لوصف الواجهة الأمامية. لقد كان رد فعله تحت غطاء رأسه ، ولكن من أجل استخدامه ، ليس من الضروري أن يكون على دراية به. يستغرق الأمر ملفات Markdown الخاصة بك ، قليلًا من الوثائق السحرية والمُنسَّقة جيدًا والتنسيقات والقراءة مع تصميم جميل جاهز.
على موقع Redux على الويب ، يمكنك رؤية قالب Docusaurus القياسي
قد تتضمن المواقع التي تم إنشاؤها باستخدام Docusaurus أيضًا مدونة قائمة على تخفيض السعر. Prism.js متصل مباشرة لتسليط الضوء على بناء الجملة. على الرغم من حقيقة أن Docusaurus ظهر مؤخرًا نسبيًا ، فقد تم الاعتراف به كأفضل أداة لعام 2018 في StackShare.
خيارات إنشاء المحتوى الأخرى
تم تصميم Docusaurus خصيصًا لإنشاء الوثائق. بالطبع ، هناك مليون وطريقة واحدة لإنشاء موقع - يمكنك نشر الحل الخاص بك بأي لغة أو CMS أو استخدام منشئ موقع ثابت.
على سبيل المثال ، تستخدم وثائق React ونظام تصميم IBM و Apollo و Ghost CMS Gatsby ، وهو منشئ موقع ثابت يستخدم غالبًا للمدونات. إذا كنت تعمل مع Vue ، فإن VuePress يعد خيارًا جيدًا لك. خيار آخر هو استخدام مولد مكتوب في بيثون - MkDocs. إنه مفتوح وقابل للتكوين باستخدام ملف YAML واحد. يعد GitBook أيضًا خيارًا جيدًا ، لكنه مجاني فقط للفرق المفتوحة وغير الربحية. ويمكنك فقط تحميل ملفات mardown باستخدام gith والعمل معهم على Github.
وثائق المكون: Docz ، Storybook ، و Styleguidist
إرشادات ، تصميم النظام ، مكتبات المكونات - كل ما تسمونه ، لكنها أصبحت شائعة جدًا مؤخرًا. أتاح ظهور الأطر المكونة ، مثل React والأدوات المذكورة هنا ، تحويلها من مشاريع مغرورة إلى أدوات مفيدة.
Storybook و Docz و Styleguidist - قم بالشيء نفسه: عرض العناصر التفاعلية وتوثيق API الخاصة بهم. يمكن أن يحتوي المشروع على العشرات أو حتى المئات من المكونات - كل ذلك مع حالات وأنماط مختلفة. إذا كنت تريد إعادة استخدام المكونات ، فيجب أن يعرف الناس أنها موجودة. للقيام بذلك ، فقط كتالوج المكونات. توفر الإرشادات نظرة عامة على جميع مكوناتك القابلة للبحث. هذا يساعد في الحفاظ على الاتساق البصري وتجنب العمل المتكرر.
توفر هذه الأدوات طريقة ملائمة لعرض الحالات المختلفة. قد يكون من الصعب إعادة إنتاج كل حالة مكون في سياق تطبيق حقيقي. بدلاً من النقر فوق تطبيق حقيقي ، يجب عليك تطوير مكون منفصل. يمكنك محاكاة حالات يصعب الوصول إليها (على سبيل المثال ، حالة التمهيد).
جنبا إلى جنب مع عرض مرئي لمختلف الحالات وقائمة من الخصائص ، غالبا ما يكون من الضروري كتابة وصف عام للمحتوى - مبرر للتصميم ، ودراسات الحالة أو وصف لنتائج اختبار المستخدم. من السهل جدًا تعلم عملية تخفيض السعر - من الناحية المثالية ، يجب أن تكون الإرشادات مورداً مشتركًا للمصممين والمطورين. توفر Docz و Styleguidist و Storybook طريقة لمزج Markdown مع المكونات بسهولة.
Docz
يعمل Docz الآن مع React فقط ، ولكن هناك عمل نشط على دعم مكونات Preact و Vue والشبكة. Docz هو الأحدث من بين الأدوات الثلاثة ، لكن على جيثب استطاع جمع أكثر من 14000 نجم. يمثل Docz مكونين - <Playground> و < Props > . يتم استيرادها واستخدامها في ملفات .mdx .
import { Playground, Props } from "docz"; import Button from "../src/Button"; ## You can _write_ **markdown** ### You can import and use components <Button>click</Button>
يمكنك التفاف مكونات React الخاصة بك مع <Playground> لإنشاء تمثيلي لـ CodePen أو CodeSandbox المدمج - أي أنك ترى المكون الخاص بك ويمكنك تحريره.
<Playground> <Button>click</Button> </Playground>
سيعرض <Props> جميع الخصائص المتاحة لمكون React هذا والقيم الافتراضية وما إذا كانت الخاصية مطلوبة أم لا.
<Props of={Button} />
شخصياً ، أعتقد أن هذا النهج المستند إلى MDX هو الأسهل في الفهم والأسهل في العمل معه.
إذا كنت من محبي مولد الموقع الثابت Gatsby ، فإن Docz يقدم تكاملًا رائعًا.
Styleguidist
مثل Docz ، تتم كتابة الأمثلة باستخدام بناء جملة Markdown. يستخدم Styleguidist كتل تعليمات برمجية Markdown (علامات اقتباس ثلاثية) في ملفات .md عادية ، وليس في MDX.
```js <Button onClick={() => console.log('clicked')>Push Me</Button>
كتل التعليمات البرمجية في تخفيض السعر عادة ما تظهر فقط رمز. عند استخدام Styleguidist ، سيتم عرض أي كتلة من التعليمات البرمجية مع علامة لغة js أو jsx أو javascript jsx . كما في Docz ، الكود قابل للتعديل - يمكنك تغيير الخصائص ورؤية النتيجة على الفور.
سيقوم Styleguidist تلقائيًا بإنشاء جدول خصائص من إعلانات PropTypes أو Flow أو Typescript.
يدعم Styleguidist الآن React و Vue.
القصص القصيرة
تعتبر Storybook نفسها "بيئة تطوير لمكونات واجهة المستخدم". بدلاً من كتابة أمثلة المكونات داخل ملفات Markdown أو MDX ، تكتب قصصًا داخل ملفات Javascript. يتم توثيق المحفوظات بواسطة الحالة المحددة للمكون. على سبيل المثال ، قد يحتوي المكون على تاريخ لحالة التمهيد والحالة المعطلة.
storiesOf('Button', module) .add('disabled', () => ( <Button disabled>lorem ipsum</Button> ))
Storybook هو أكثر تعقيدا بكثير من Styleguidist و Docz. ولكن في الوقت نفسه هذا هو الخيار الأكثر شعبية ، في جيثب يحتوي المشروع على أكثر من 36000 نجم. هذا مشروع مفتوح المصدر ، ويشمل 657 مشاركًا ويرافقه موظفون بدوام كامل. يتم استخدامه بواسطة Airbnb و Algolia و Atlassian و Lyft و Salesforce. تدعم Storybook أطرًا أكثر من منافسيها - React و React Native و Vue و Angular و Mithril و Ember و Riot و Svelte و HTML العادي.
في إصدار مستقبلي ، سيكون هناك رقائق من Docz وسيتم تقديم MDX.
# Button Some _notes_ about your button written with **markdown syntax**. <Story name="disabled"> <Button disabled>lorem ipsum</Button> </Story>
ستظهر الميزات الجديدة لـ Storybook تدريجيًا على مدار الأشهر القليلة القادمة ، ويبدو أنها ستكون خطوة كبيرة للأمام.
النتائج
يتم تقدير فوائد مكتبة النماذج في ملايين المقالات حول "المتوسط". عندما تتم بشكل جيد ، فإنها تجعل من السهل إنشاء المنتجات ذات الصلة والحفاظ على الهوية. بالطبع ، لن تقوم أي من هذه الأدوات بإنشاء نظام تصميم بطريقة سحرية. وهذا يتطلب تصميم دقيق وتصميم CSS. ولكن عندما يحين الوقت لإتاحة نظام التصميم للشركة بأكملها ، فإن Docz و Storybook و Styleguidist هي خيارات رائعة.
من المترجم. هذه هي تجربتي الأولى في حبري. إذا وجدت أن بعضها غير دقيق ، أو أن هناك اقتراحات لتحسين المقال - اكتب شخصيًا.