लाइव दिशानिर्देश - एमडीएक्स और अन्य रूपरेखा

आपके पास एक बेहतर ओपन सोर्स प्रोजेक्ट हो सकता है, लेकिन अगर इसके पास अच्छे दस्तावेज़ नहीं हैं, तो संभावना है कि यह कभी भी बंद नहीं होगा। कार्यालय में, अच्छा प्रलेखन आपको समान प्रश्नों का उत्तर देने की अनुमति नहीं देगा। प्रलेखन यह भी सुनिश्चित करता है कि लोग परियोजना को समझ सकते हैं यदि प्रमुख कर्मचारी कंपनी छोड़ देते हैं या भूमिका बदलते हैं। लाइव दिशानिर्देश डेटा अखंडता सुनिश्चित करने में मदद करते हैं।

यदि आपको लंबा पाठ लिखने की आवश्यकता है, तो एचटीएमएल के लिए मार्कडाउन एक बढ़िया विकल्प है। कभी-कभी मार्कडाउन सिंटैक्स पर्याप्त नहीं होता है। इस मामले में, हम इसके अंदर HTML का उपयोग कर सकते हैं। उदाहरण के लिए, कस्टम तत्व। इसलिए, यदि आप मूल वेब घटकों के साथ एक डिज़ाइन सिस्टम का निर्माण कर रहे हैं, तो उन्हें पाठ प्रलेखन में शामिल करना आसान है। यदि आप React (या Preact या Vue जैसे किसी अन्य JSX ढांचे) का उपयोग करते हैं, तो आप MDX के साथ भी ऐसा कर सकते हैं।

यह लेख प्रलेखन लेखन और दिशानिर्देश उपकरणों का एक व्यापक अवलोकन है। यहां सूचीबद्ध सभी उपकरण एमडीएक्स का उपयोग नहीं करते हैं, लेकिन यह तेजी से प्रलेखन टूल में शामिल किया जा रहा है।

MDX क्या है?

.mdx फ़ाइल में Markdown के समान सिंटैक्स है, लेकिन आपको JSX इंटरेक्टिव घटकों को आयात करने और उन्हें अपनी सामग्री में एम्बेड करने की अनुमति देता है। Vue घटकों के लिए समर्थन अल्फा में है। MDX के साथ काम करना शुरू करने के लिए, बस "क्रिएट रिएक्ट ऐप" इंस्टॉल करें। Next.js और Gatsby के लिए प्लगइन्स हैं। Docusaurus के अगले संस्करण (संस्करण 2) में अंतर्निहित समर्थन भी होगा।

Docusaurus के साथ लेखन दस्तावेज़

Docusaurus ने फेसबुक पर लिखा है। वे रिएक्ट को छोड़कर हर ओपन सोर्स प्रोजेक्ट पर इसका इस्तेमाल करते हैं। कंपनी के बाहर, Redux, Prettier, Gulp और Babel इसका उपयोग करते हैं।

Docusaurus का उपयोग करने वाली परियोजनाएँ।

Docusaurus का उपयोग किसी भी प्रलेखन को लिखने के लिए किया जा सकता है, न कि केवल दृश्यपटल का वर्णन करने के लिए। उसके हुड के नीचे रिएक्ट है, लेकिन इसका उपयोग करने के लिए, उसके साथ परिचित होना आवश्यक नहीं है। यह आपकी मार्कडाउन फाइलें, एक चुटकी जादू और अच्छी तरह से संरचित, स्वरूपित और पठनीय प्रलेखन के साथ एक सुंदर डिजाइन तैयार करता है।

Redux वेबसाइट पर आप मानक Docusaurus टेम्पलेट देख सकते हैं

Docusaurus का उपयोग करके बनाई गई साइटों में एक मार्कडाउन-आधारित ब्लॉग भी शामिल हो सकता है। Prism.js तुरंत सिंटैक्स हाइलाइटिंग से जुड़ा हुआ है। इस तथ्य के बावजूद कि Docusaurus अपेक्षाकृत हाल ही में दिखाई दिया, इसे स्टाकेसर में 2018 के सर्वश्रेष्ठ उपकरण के रूप में मान्यता दी गई थी।

अन्य सामग्री निर्माण विकल्प

Docusaurus को विशेष रूप से प्रलेखन बनाने के लिए डिज़ाइन किया गया है। बेशक, एक साइट बनाने के लिए एक लाख और एक तरीका है - आप किसी भी भाषा, सीएमएस में अपने स्वयं के समाधान को तैनात कर सकते हैं या स्टेटिक जनरेटर जनरेटर का उपयोग कर सकते हैं।

उदाहरण के लिए, रिएक्ट के लिए प्रलेखन, आईबीएम, अपोलो और घोस्ट सीएमएस की डिजाइन प्रणाली गैट्सबी का उपयोग करती है - एक स्थिर साइट जनरेटर जो अक्सर ब्लॉगों के लिए उपयोग किया जाता है। यदि आप Vue के साथ काम करते हैं, तो VuePress आपके लिए एक अच्छा विकल्प है। एक अन्य विकल्प पायथन में लिखे जनरेटर का उपयोग करना है - MkDocs। यह एक एकल YAML फ़ाइल के साथ खुला और कॉन्फ़िगर करने योग्य है। GitBook भी एक अच्छा विकल्प है, लेकिन यह केवल खुली और गैर-लाभकारी टीमों के लिए मुफ़्त है। और आप सिर्फ जीथ का उपयोग करके मर्डाउन फाइल अपलोड कर सकते हैं और उनके साथ जीथब पर काम कर सकते हैं।

घटक प्रलेखन: Docz, स्टोरीबुक, और स्टाइलगाइडिस्ट

दिशानिर्देश, सिस्टम डिज़ाइन, घटक लाइब्रेरी - जो भी आप उन्हें कॉल करते हैं, लेकिन यह हाल ही में बहुत लोकप्रिय हो गया है। घटक रूपरेखाओं के आगमन, जैसे रिएक्ट और यहां उल्लिखित उपकरण, ने उन्हें कल्पनाशील परियोजनाओं से उपयोगी उपकरणों में बदलना संभव बना दिया है।

स्टोरीबुक, डॉक्ज़ और स्टाइलग्यूडिस्ट - एक ही काम करते हैं: इंटरैक्टिव तत्वों को प्रदर्शित करते हैं और उनके एपीआई का दस्तावेजीकरण करते हैं। एक परियोजना में दर्जनों या सैकड़ों घटक हो सकते हैं - सभी विभिन्न राज्यों और शैलियों के साथ। यदि आप चाहते हैं कि घटकों का पुन: उपयोग किया जाए, तो लोगों को यह जानना होगा कि वे मौजूद हैं। ऐसा करने के लिए, बस घटकों को सूचीबद्ध करें। दिशानिर्देश आपके सभी घटकों का खोज करने योग्य अवलोकन प्रदान करते हैं। यह दृश्य स्थिरता बनाए रखने और दोहराव वाले काम से बचने में मदद करता है।

ये उपकरण विभिन्न राज्यों को देखने का एक सुविधाजनक तरीका प्रदान करते हैं। एक वास्तविक एप्लिकेशन के संदर्भ में प्रत्येक घटक स्थिति को पुन: पेश करना मुश्किल हो सकता है। वास्तविक एप्लिकेशन पर क्लिक करने के बजाय, आपको एक अलग घटक विकसित करना चाहिए। आप हार्ड-टू-पहुंच राज्यों (उदाहरण के लिए, बूट स्थिति) का अनुकरण कर सकते हैं।

विभिन्न राज्यों के दृश्य प्रदर्शन और गुणों की एक सूची के साथ, अक्सर सामग्री का एक सामान्य विवरण लिखना आवश्यक होता है - डिजाइन के लिए औचित्य, केस अध्ययन या उपयोगकर्ता परीक्षण के परिणामों का विवरण। मार्कडाउन सीखना बहुत आसान है - आदर्श रूप से, दिशानिर्देश डिजाइनरों और डेवलपर्स के लिए एक साझा संसाधन होना चाहिए। Docz, Styleguidist और Storybook घटकों के साथ मार्कडाउन को आसानी से मिलाने का एक तरीका है।

Docz

अब Docz केवल React के साथ काम करता है, लेकिन Preact, Vue और वेब घटकों के लिए समर्थन पर एक सक्रिय कार्य है। Docz तीन उपकरणों में सबसे नया है, लेकिन गितुब पर वह 14,000 से अधिक सितारों को इकट्ठा करने में सक्षम था। 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> 

आप अंतर्निहित PlayPen या CodeSandbox का एक एनालॉग बनाने के लिए <Playground> साथ अपने स्वयं के रिएक्ट घटकों को लपेट सकते हैं - अर्थात, आप अपने घटक को देखते हैं और आप इसे संपादित कर सकते हैं।

 <Playground> <Button>click</Button> </Playground> 

<Props> इस रिएक्ट घटक के लिए सभी उपलब्ध गुण दिखाएगा, डिफ़ॉल्ट मान, और क्या एक संपत्ति की आवश्यकता है।

 <Props of={Button} /> 

व्यक्तिगत रूप से, मुझे लगता है कि यह एमडीएक्स-आधारित दृष्टिकोण समझने में सबसे आसान है और इसके साथ काम करना सबसे आसान है।

यदि आप गैट्सबी स्थिर साइट जनरेटर के प्रशंसक हैं, तो डोकज़ महान एकीकरण प्रदान करता है।

Styleguidist

Docz की तरह, Markdown सिंटैक्स का उपयोग करके उदाहरण लिखे जाते हैं। स्टाइलगाइडिस्ट मार्कडाउन कोड ब्लॉक (ट्रिपल कोट्स) का नियमित रूप से .md फाइलों में उपयोग करता है, MDX में नहीं।

 ```js <Button onClick={() => console.log('clicked')>Push Me</Button> 

मार्कडाउन में कोड के ब्लॉक आमतौर पर केवल कोड दिखाते हैं। Styleguidist का उपयोग करते समय, एक js , jsx या javascript भाषा टैग के साथ कोड के किसी भी ब्लॉक को एक प्रतिक्रिया घटक के रूप में प्रदर्शित किया जाएगा। जैसा कि डॉकज़ में, कोड संपादन योग्य है - आप गुण बदल सकते हैं और तुरंत परिणाम देख सकते हैं।

स्टाइलगाइडिस्ट स्वचालित रूप से प्रोपटीपेस, फ्लो, या टाइपस्क्रिप्ट घोषणाओं से एक संपत्ति तालिका बनाएगा।

Styleguidist अब React और Vue का समर्थन करता है।

कहानियों का संग्रह

स्टोरीबुक खुद को "यूआई घटकों के लिए विकास का माहौल" के रूप में स्थान देता है। मार्कडाउन या एमडीएक्स फ़ाइलों के अंदर घटक उदाहरण लिखने के बजाय, आप जावास्क्रिप्ट फ़ाइलों के अंदर कहानियां लिखते हैं। इतिहास घटक की विशिष्ट स्थिति द्वारा प्रलेखित है। उदाहरण के लिए, एक घटक बूट राज्य और अक्षम राज्य के लिए इतिहास हो सकता है।

 storiesOf('Button', module) .add('disabled', () => ( <Button disabled>lorem ipsum</Button> )) 

स्टाइलबुडिस्ट और डॉकज़ की तुलना में स्टोरीबुक बहुत अधिक जटिल है। लेकिन एक ही समय में यह सबसे लोकप्रिय विकल्प है, गितुब पर इस परियोजना में 36,000 से अधिक सितारे हैं। यह एक ओपन सोर्स प्रोजेक्ट है, इसमें 657 प्रतिभागी शामिल हैं और यह पूर्णकालिक कर्मचारियों के साथ है। इसका उपयोग Airbnb, Algolia, Atlassian, Lyft और Salesforce द्वारा किया जाता है। स्टोरीबुक अपने प्रतिद्वंद्वियों की तुलना में अधिक रूपरेखाओं का समर्थन करती है - रिएक्ट, रिएक्टिव नेटिव, व्यू, एंगुलर, मिथ्रिल, एम्बर, दंगा, स्वेलेट और नियमित एचटीएमएल।

भविष्य के रिलीज में, डॉकज़ से चिप्स होंगे और एमडीएक्स पेश किया जाएगा।

 # Button Some _notes_ about your button written with **markdown syntax**. <Story name="disabled"> <Button disabled>lorem ipsum</Button> </Story> 

स्टोरीबुक की नई सुविधाएँ अगले कुछ महीनों में धीरे-धीरे दिखाई देंगी और, जाहिर है, यह एक बड़ा कदम होगा।

परिणाम

मध्यम पर लाखों लेखों में पैटर्न लाइब्रेरी के लाभों का विस्तार किया गया है। जब अच्छी तरह से किया जाता है, तो वे संबंधित उत्पादों को बनाना और पहचान बनाए रखना आसान बनाते हैं। बेशक, इनमें से कोई भी उपकरण जादुई रूप से एक डिज़ाइन सिस्टम नहीं बनाएगा। इसके लिए सावधान डिजाइन और सीएसएस डिजाइन की आवश्यकता होती है। लेकिन जब डिजाइन कंपनी को पूरी कंपनी को उपलब्ध कराने का समय आता है, तो Docz, Storybook और Styleguidist बढ़िया विकल्प हैं।

अनुवादक से। यह हैबे पर मेरा पहला अनुभव है। यदि आप पाते हैं कि कुछ सटीक नहीं हैं, या लेख में सुधार के लिए सुझाव हैं - एक व्यक्तिगत में लिखें।