यांडेक्स में एपीआई और एसडीके दस्तावेज करने पर एक नया रूप। हाइपरबेटन पर व्याख्यान

मेरा नाम एंड्री पोलाकोव है, मैं यैंडेक्स में एपीआई और एसडीके प्रलेखन समूह का प्रमुख हूं। आज मैं आपके साथ एक रिपोर्ट साझा करना चाहूंगा कि मैं और मेरे सहयोगी, वरिष्ठ प्रलेखन डेवलपर जूलिया पिवोवेरोवा, कुछ हफ्ते पहले छठे हाइपरबेटन में पढ़े थे।


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

- सभी को नमस्कार! आज, जूलिया और मैं आपको बताऊंगा कि कैसे यैंडेक्स में हमें एपीआई और एसडीके दस्तावेज करने पर एक नया रूप मिला। रिपोर्ट में चार भाग होंगे, वॉच रिपोर्ट, हम चर्चा करेंगे, हम बात करेंगे।

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

अंत में, हम यह वर्णन करेंगे कि हमारी प्रक्रियाएँ कैसे बनीं।

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

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

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



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

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

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

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

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



जब एक तकनीकी लेखक आता है, तो वह एक नई तकनीक सीखता है और उसे प्रलेखित करना शुरू करता है।

हमने प्रौद्योगिकियों का वर्णन करने के बाद, हम HTTP एपीआई की संरचना का वर्णन करने के लिए आगे बढ़े।

हमारे पास कई अलग-अलग HTTP एपीआई हैं, और सभी अलग-अलग वर्णित हैं। चलो एक समझौता करते हैं और वही करते हैं!

हमने उन मुख्य वर्गों की पहचान की है जो प्रत्येक HTTP एपीआई में होंगी:



"अवलोकन" या "परिचय": इस API की आवश्यकता क्यों है, यह आपको क्या करने की अनुमति देता है, किसी प्रकार का उत्तर प्राप्त करने के लिए किस होस्ट तक पहुंच होनी चाहिए।

"त्वरित शुरुआत" जब कोई व्यक्ति कुछ चरणों से गुजरता है और यह समझने के लिए अंत में एक सफल परिणाम प्राप्त करता है कि यह एपीआई कैसे काम करता है।

"कनेक्शन / प्राधिकरण"। कई एपीआई को एक प्राधिकरण टोकन या एपीआई कुंजी की आवश्यकता होती है। यह एक महत्वपूर्ण बिंदु है, इसलिए हमने फैसला किया कि यह सभी एपीआई का अनिवार्य हिस्सा है।

"सीमाएँ / सीमाएँ" जब हम अनुरोधों की संख्या या अनुरोध निकाय के आकार, आदि पर सीमाओं के बारे में बात करते हैं।

"संदर्भ", संदर्भ। एक बहुत बड़ा हिस्सा, जिसमें सभी HTTP हैंडल होते हैं जिन्हें उपयोगकर्ता खींच सकता है और किसी प्रकार का परिणाम प्राप्त कर सकता है।



नतीजतन, हमारे पास कई अलग-अलग एपीआई थे, उन्हें अलग तरह से वर्णित किया गया था, अब हम सब कुछ उसी तरह से लिखने की कोशिश करते हैं। ऐसा लाभ

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



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



यह पता चला है कि कई पेन थे, उन्हें अलग-अलग तरीकों से वर्णित किया गया था, और अब हम इसे एक एकल रूप में लाना चाहते हैं।

HTTP API के साथ समाप्त होने के बाद, हम मोबाइल SDK पर चले गए।

एक सामान्य दस्तावेज़ संरचना है, यह लगभग समान है:

- "परिचय", जहां हम कहते हैं कि, यहां, इस एसडीके का उपयोग ऐसे उद्देश्यों के लिए किया जाता है, इस तरह के उद्देश्यों के लिए इसे अपने लिए एकीकृत करें, यह ऐसे ऑपरेटिंग सिस्टम के लिए उपयुक्त है, हमारे पास ऐसे और ऐसे संस्करण हैं, आदि।

- "कनेक्शन"। HTTP एपीआई के विपरीत, हम सिर्फ एसडीके का उपयोग करने के लिए कुंजी प्राप्त करने के लिए बात नहीं कर रहे हैं, यदि आपको इसकी आवश्यकता है, तो हम इस बारे में बात कर रहे हैं कि लाइब्रेरी को हमारी परियोजना में कैसे एकीकृत किया जाए।

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



- "निर्देशिका", संदर्भ, लेकिन HTTP एपीआई संदर्भ के विपरीत, हम यहां सब कुछ एकजुट नहीं कर सकते, क्योंकि हम मुख्य रूप से निर्देशिका उत्पन्न करते हैं और हम रिपोर्ट में इस बारे में बाद में बात करेंगे।

- "जारी करता है," या इतिहास को बदल देता है, चैंज। मोबाइल एसडीके में आमतौर पर एक छोटा रिलीज चक्र होता है, हर दो सप्ताह में एक नया संस्करण जारी किया जाता है। और उपयोगकर्ता के लिए यह बात करना बेहतर होगा कि क्या बदल गया है, क्या यह अद्यतन करने या नहीं करने के लिए इसके लायक है।

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



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

इसलिए, हम टेम्प्लेट के साथ आए, गाइड बनाए, अब हमारी कार्य योजना क्या है? हमने फैसला किया कि अगर हम एपीआई को स्केल करते हैं, पेन को बदलते हैं या एसडीके को बदलते हैं, तो हम नए टेम्प्लेट लेते हैं, एक नया स्ट्रक्चर लेते हैं और उस पर काम करना शुरू करते हैं।

यदि हम खरोंच से प्रलेखन लिखते हैं, तो, निश्चित रूप से, हम फिर से एक नई संरचना लेते हैं, नए टेम्पलेट लेते हैं और उन पर काम करते हैं।

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

एकीकरण के क्या लाभ हैं? वे सभी के लिए स्पष्ट होना चाहिए:

"UX", हम अपने प्रलेखन में उपयोगकर्ता को घर पर महसूस कराने के बारे में सोच रहे हैं। वह आया था, और जानता है कि उन अनुभागों में क्या वर्णित है जहां वह प्राधिकरण, उपयोग के उदाहरण, कलम का वर्णन पा सकता है। यह महान है।

तकनीकी लेखकों के लिए, प्रौद्योगिकी का वर्णन आपको एक निश्चित प्रवेश बिंदु निर्धारित करने की अनुमति देता है जहां वह आता है, और इस तकनीक से परिचित होना शुरू कर देता है, अगर वह नहीं जानता था, तो शब्दावली को समझना शुरू कर देता है, इसमें डुबकी लगाता है।

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

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

गाइड विकि पृष्ठों में लिखे गए थे, इसलिए यदि भाषा, तकनीक, प्रोटोकॉल अपडेट किए जाते हैं, तो यह सब आसानी से एक मौजूदा दस्तावेज़ में जोड़ दिया जाता है। सुखद जीवन।

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

डेवलपर्स को आकर्षित करें। ये वे लोग हैं जिनके लिए आप दस्तावेज लिख रहे हैं। यदि आप स्वयं किसी प्रकार के मार्गदर्शक लिखते हैं, तो शायद वे इसे पसंद नहीं करेंगे। उनके साथ सहमत होना बेहतर है ताकि आपको शब्दावली की एक आम समझ हो: आप दस्तावेज़ में क्या लिखते हैं, आप इसे कैसे लिखते हैं।

और अनुवादकों के साथ भी बातचीत करते हैं, उन सभी को इसका अनुवाद करना होगा। यदि वे डेवलपर्स की तुलना में अलग-अलग तरीके से अनुवाद करते हैं, तो फिर से संघर्ष होगा। ( यहां सवाल और जवाब के साथ एक वीडियो टुकड़े का लिंक दिया गया है - लगभग। एड।) हम आगे बढ़ते हैं।

जूलिया:
- हाय, मेरा नाम जूलिया है, मैं पांच साल से यांडेक्स में काम कर रहा हूं और एंड्री के समूह में एपीआई और एसडीके का दस्तावेजीकरण कर रहा हूं। आमतौर पर हर कोई एक अच्छे अनुभव के बारे में बात करता है कि यह कितना अच्छा है। मैं आपको बताऊंगा कि कैसे हमने पूरी तरह से सफल रणनीति नहीं चुनी। उस समय, यह सफल लग रहा था, लेकिन फिर एक कठोर वास्तविकता आई, और हम थोड़े अनलकी थे।

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



उस समय, हमें Doxygen पसंद था, यह हमारी जरूरतों को पूरा करता था, जैसा कि यह हमें लगता है, और हमने इसे एक एकल जनरेटर के रूप में चुना। और हमने ऐसी योजना बनाई, जिसकी हमें उम्मीद थी, हम इस पर किसी तरह काम करना चाहते थे।

हमारे पास क्या था? तकनीकी लेखक काम करने के लिए आया, डेवलपर से स्रोत कोड प्राप्त किया, अपनी टिप्पणियां, संपादन लिखना शुरू कर दिया, उसके बाद प्रलेखन को हमारे डेसरवर को भेजा जाना था, वहां हमने डॉक्सिजन चलाया, एक्सएमएल प्रारूप प्राप्त किया, लेकिन यह हमारे आईआईए एक्सएमएल मानक के अनुरूप नहीं था। हम इस बारे में पहले से जानते थे, एक निश्चित कनवर्टर लिखा था।

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

हमने यह पता लगाने का फैसला किया कि मामला क्या था। तब हमें एहसास हुआ कि Doxygen सभी भाषाओं में बिल्कुल फिट नहीं है। हमें उस कोड का विश्लेषण करना था, जिस पर वह लड़खड़ा गया, हमने ऐसे निर्माण किए कि डॉक्सिजन ने समर्थन नहीं किया और समर्थन करने की योजना नहीं बनाई।

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



हमारा चक्र इस तरह दिखने लगा। हमें स्रोत प्राप्त हुए, उन्हें डिवर्सर पर शामिल किया, फिर प्रीप्रोसेसिंग स्क्रिप्ट से जोड़ा, इसने कोड से सभी अतिरिक्त को काट दिया, फिर Doxygen ने व्यवसाय में प्रवेश किया, हमने Doxygen आउटपुट प्रारूप प्राप्त किया, कनवर्टर को भी लॉन्च किया, अंतिम DITA XML फाइलें प्राप्त कीं, फिर डॉक्यूमेंटेशन कलेक्टर से जुड़ा, और हमने अपना प्रलेखन एक बाहरी डोमेन पर प्रकाशित किया। ऐसा लगता है कि सब कुछ अच्छा लग रहा है। एक स्क्रिप्ट जोड़ा, वहाँ क्या हो रहा है? शुरू में, कुछ भी नहीं था। स्क्रिप्ट में तीन लाइनें थीं, फिर पांच, दस लाइनें और यह सभी सैकड़ों लाइनों तक बढ़ीं। हमने महसूस किया कि हम अपना अधिकांश समय दस्तावेज़ लिखने पर नहीं, बल्कि कोड का विश्लेषण करने में लगा रहे हैं, जहां क्या क्रॉल नहीं है, और बस नियमित रूप से स्क्रिप्ट को जोड़ने, पागलपन के लिए बैठे और सोचने के लिए कि क्या मामला है।

हमें एहसास हुआ कि हमें कुछ बदलने की जरूरत है, किसी तरह रुकें, इससे पहले कि बहुत देर हो जाए, और जब तक हमारी रिहाई चक्र अंत तक गिर न जाए।

एक उदाहरण के रूप में, प्रीप्रोसेसिंग स्क्रिप्ट पहले कुछ इस तरह दिखती थी, और हानिरहित थी।



हमने शुरुआत में यह रास्ता क्यों चुना? वह अच्छा क्यों लगा?



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



लेकिन यह बड़े मंत्रालयों में से एक निकला। डेवलपर्स ने हमारे सामान्य सिंटैक्स का समर्थन नहीं किया, वे अपने आईडीई का उपयोग करने के लिए उपयोग किए जाते हैं, वहां पहले से ही मूल जनरेटर हैं, और उनके सिंटैक्स हमारे मेल नहीं खाते हैं। यह एक ठोकर थी।

Doxygen ने भाषाओं में नई सुविधाओं का भी खराब समर्थन किया। उनके पास एक चयनात्मक दृष्टिकोण है, क्योंकि वे खुद सी ++ में लिखे गए हैं, वे मुख्य रूप से सी जैसी भाषाओं का समर्थन करते हैं, और शेष अवशेष सिद्धांत के अनुसार। और भाषाओं में सुधार किया जा रहा है, Doxygen उनके साथ काफी मेल नहीं खा रहा है, और यह हमारे लिए काफी असुविधाजनक हो गया है।

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

“हमने महसूस किया कि हमारे मामले में, कहीं न कहीं एक सार्वभौमिक जनरेटर सामने आया, लेकिन अधिकांश भाग के लिए, जब हमने यह सब करना शुरू किया, तो योजना काम नहीं कर पाई। वे शांत रूप से आए, सभी से सहमत थे कि चलो यह करते हैं, लेकिन यह काम नहीं किया।

परिणामस्वरूप, हम एक नई योजना के साथ आने लगे। वह देशी जनरेटर के साथ था। अब हमारे पास सर्किट में क्या है? ( , ), , Objective-C Java, , .



, DITA XML, , , , XML. HTML, . — JavaDoc, AppleDoc, Jazzy. HTML, . HTML, , . , HTML . , , , HTML, . XML , . .

.

— . Doxygen , , . Objective-C, , Java . . , , IDE , IntelliSense, , , , SDK, , . .

, , SDK , , , , HTML, . , , , , , .

. , - , . XML , XML . Doxygen , XML . HTML, XML . . — .

, , . 1500 , : HTML, CSS, .

, , .

. ( — . .)

, , .

— . , . -, . , . ? .

? -, , , , .

- , - , . .

? -, , , , .

. , , , , , , , .

, . , , , , , , .

? — , , , , , . . Bitbucket, - . , .



, . . - , - , , , , , , . , , , , .



, , .

, SDK , - , , . -, , , , .

, . . — , , .

, . . .

, , , , , , .



, .

. - , . .



, , , , . . , , , - . , . , , .

, .

. , . , , .

, , , — . , , , .



dev , (fork-dev) , . , doc-dev-en, . , , - , , .

(fork-dev) (doc-dev-ru) . , - . . , , doc-dev-ru, . , , - , .

, . (doc-dev-en). , , (doc-dev-en), , . , (fork-dev). , , , , . , , . , dev . , , , .

(fork-dev), , . (fork-dev), , (doc-dev-en), . , , , . , .



, , . dev, (fork-dev) , (doc-dev-ru) (doc-dev-en) . (doc-dev-en), (doc-dev-ru) . , .



. dev , , (branch-dev). (branch-dev-ru), (branch-dev). , . , . — , — - , , , , .

, , . , , (branch-dev) . , , .

dev. , , , , . .

(branch-dev-ru), , (branch-dev-ru), . .

. (branch-dev), . , , , , , , , , . , , . , , .



, , , , . .

, ? , , . . . , - , . . , .

, , , , , .

, . . . . , , .

— — . — .

. . , . , , , , , , . .

, . . . . , . , . - , . — . .

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