डॉक्यूमेंट करते समय GIT का उपयोग करें

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

एक विशिष्ट कार्यान्वयन के उदाहरण के साथ, यहां उल्लिखित दृष्टिकोण में कम प्रवेश सीमा है। तकनीकी रूप से, कल आप नए तरीके से काम करना शुरू कर सकते हैं।

समस्या का बयान

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

1. इस कार्य में संयुक्त कार्य, एक समूह या कर्मचारियों के कई समूहों के प्रयास शामिल हैं
2. आउटपुट पर, आप एक विशिष्ट प्रारूप में एक दस्तावेज़ रखना चाहते हैं, कॉर्पोरेट-शैली विशेषताओं के साथ, एक विशिष्ट टेम्पलेट के अनुसार बनाया गया है। निश्चितता के लिए, हम मान लेंगे कि यह एमएस वर्ड (.docx) है

10 साल पहले, दृष्टिकोण अस्पष्ट होगा: हम एक एमएस वर्ड दस्तावेज़ या दस्तावेज बनाएंगे और किसी तरह परिवर्तन पर काम को व्यवस्थित करेंगे।

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

उदाहरण

मैंने एक बड़े इंटीग्रेटर में काम करते हुए इस समस्या को काफी गंभीरता से महसूस किया। डिजाइन प्रलेखन को बदलने की प्रक्रिया इस प्रकार थी:

1. इंजीनियर MS Word (.docx) दस्तावेज़ के नवीनतम संस्करण को डाउनलोड करता है
2. नाम बदल देता है
3. ट्रैक मॉड में परिवर्तन करता है
4. वास्तुकार को सुधार के साथ दस्तावेज़ भेजता है
5. टिप्पणियों के साथ सभी सुधारों की एक सूची भी भेजता है
6. वास्तुकार परिवर्तन का विश्लेषण करता है
7. यदि सब ठीक है, तो नवीनतम संस्करण के साथ फ़ाइल में परिवर्तन डेटा को कॉपी करता है, संस्करण बदलता है, इसे एक साझा संसाधन पर रखता है
8. यदि टिप्पणियां हैं, तो एक चर्चा शुरू की गई है (ईमेल या रैलियां)
9. सहमति बन गई है
10. आगे के पैराग्राफ 3 - 9

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

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

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

गिट मार्कडाउन

ऊपर दिए गए उदाहरण में वर्णित समस्या का सामना करते हुए, मैंने इस मुद्दे पर शोध करना शुरू किया।
मैंने देखा कि दस्तावेज़ बनाते समय मार्कडाउन के साथ Git का उपयोग अधिक से अधिक लोकप्रिय हो रहा है।

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

मार्कडाउन एक सरल टेक्स्ट मार्कअप भाषा है। यह नियमित रूप से TXT फ़ाइलों में खूबसूरती से डिज़ाइन किए गए पाठ बनाने के लिए डिज़ाइन किया गया है। यदि हम Markdown में अपने दस्तावेज बनाते हैं, तो Markdown-Git लिंक स्वाभाविक दिखता है।

और सबकुछ ठीक हो जाएगा, और इस जगह पर अगर हमारी दूसरी स्थिति नहीं थी, तो इसे समाप्त करना संभव होगा: "आउटपुट में हमें एक निश्चित प्रारूप में एक दस्तावेज की आवश्यकता होती है, एक निश्चित टेम्पलेट के अनुसार कॉर्पोरेट शैली विशेषताओं के साथ" (और हम पहली बार सहमत हुए निश्चितता, यह एमएस वर्ड होगा)। यही है, अगर हमने मार्कडाउन का उपयोग करने का फैसला किया है, तो हमें किसी तरह इस फाइल को आवश्यक प्रकार के .docx में बदलने की आवश्यकता है।

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

यदि हम एक ऐसी स्क्रिप्ट लिख सकते हैं जो पंडोक अपने आप "समाप्त" नहीं कर पाएगी, तो यह एक आदर्श समाधान होगा।

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

किसी विशेष समस्या का समाधान

इसलिए, मेरे मामले में, पंडोक का उपयोग करके फ़ाइल को परिवर्तित करने के बाद, मुझे मैन्युअल रूप से अतिरिक्त फ़ाइल प्रसंस्करण करना होगा, अर्थात्

• तालिकाओं और चित्रों के कैप्शन की स्वचालित संख्या के साथ वर्ड में फ़ील्ड जोड़ें
• तालिकाओं के लिए शैली बदलें

मुझे मानक (पंडोक) या ज्ञात साधनों का उपयोग करके ऐसा करने का तरीका नहीं मिला। इसलिए, मैंने pywin32 पैकेज के साथ एक पायथन स्क्रिप्ट लागू की। नतीजतन, मुझे पूर्ण स्वचालन मिला। अब मैं अपनी मार्कडाउन फ़ाइल को एमएस वर्ड दस्तावेज़ के वांछित रूप में एक कमांड के साथ बदल सकता हूं।

यहां देखें विवरण

टिप्पणी

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

सामान्य तौर पर, pywin32 के साथ हमें MS Word दस्तावेज़ पर लगभग पूर्ण नियंत्रण प्राप्त होता है, जो हमें इसे बदलने और इसे उस रूप में लाने की अनुमति देता है जो आपके कॉर्पोरेट मानक की आवश्यकता है। बेशक, अन्य उपकरणों का उपयोग करके समान लक्ष्यों को प्राप्त किया जा सकता है, उदाहरण के लिए, वीबीए मैक्रोज़, लेकिन मेरे लिए अजगर का उपयोग करना अधिक सुविधाजनक था।

इस दृष्टिकोण के लिए एक संक्षिप्त सूत्र:

Markdown + Git -- () --> MS Word 

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

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

प्रक्रिया

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

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

हम एक साधारण गितुब प्रवाह आधारित प्रक्रिया को देखेंगे। इसका वर्णन इंटरनेट पर और हैबर दोनों में पाया जा सकता है।

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

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

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

तुलना में इस दृष्टिकोण का उपयोग क्या है, उदाहरण के लिए, उपरोक्त उदाहरण में वर्णित प्रक्रिया के साथ?

वास्तव में, प्रक्रियाएं बहुत समान हैं, आपने अभी-अभी प्रतिस्थापित किया है

फ़ाइल की प्रतिलिपि बनाना -> एक शाखा बनाना
पाठ को अंतिम फ़ाइल में कॉपी करें-> मर्ज करें (मर्ज करें)
अपने आप में नवीनतम परिवर्तनों की प्रतिलिपि बनाना -> गिट पुल / भ्रूण
पत्राचार में चर्चा -> अनुरोधों को खींचें
ट्रैक मोड -> गिट भिन्न
नवीनतम अनुमोदित संस्करण -> मास्टर शाखा
बैकअप (एक दूरस्थ सर्वर की नकल) -> गिट पुश
...

इस प्रकार, आपने वह सब कुछ स्वचालित कर दिया जो आपको पहले से करना था, लेकिन मैन्युअल रूप से।

उच्च स्तर पर, यह आपको अनुमति देता है

• दस्तावेज़ बदलने के लिए एक स्पष्ट, सरल और नियंत्रित प्रक्रिया बनाएँ।
• क्योंकि अंतिम दस्तावेज़ (हमारे उदाहरण एमएस वर्ड में) आप स्वचालित रूप से बनाते हैं, यह स्वरूपण से संबंधित त्रुटियों की संभावना को कम करता है

टिप्पणी

उपरोक्त के मद्देनजर, मुझे लगता है कि यह स्पष्ट है कि भले ही आप अकेले प्रलेखन पर काम कर रहे हों, लेकिन Git का उपयोग करने से आपके काम में बहुत आसानी हो सकती है

यह सब प्रलेखन की गुणवत्ता में सुधार करता है और इसके निर्माण का समय कम करता है। और थोड़ा सा बोनस - आप गिट सीखते हैं, जो आपके नेटवर्क को स्वचालित करने में आपकी मदद करेगा :)

नई प्रक्रिया में कैसे स्विच करें?

लेख की शुरुआत में, मैंने लिखा था कि कल आप एक नए तरीके से काम करना शुरू कर सकते हैं। अपने काम को नई दिशा में कैसे अनुवाद करें?

यहां उन चरणों का क्रम दिया गया है, जिनकी आपको सबसे अधिक संभावना है:

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

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

बाकी सब कुछ (मार्कडाउन, गिट, पंडोक, टाइपोरा) तैयार है और उनके साथ काम शुरू करने के लिए विशेष प्रयासों या समय की आवश्यकता नहीं है।