मैं किसी और के पिछले काम का दस्तावेज कैसे दे सकता हूं? [बन्द है]

Question

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

वर्तमान प्रलेखन आम तौर पर कुछ इस तरह से पढ़ता है:

यह कार्यक्रम चालान से पहले चलाया जाता है। ज्ञात बग: कोई नहीं।

सॉफ़्टवेयर X स्थापित करने के बाद इस प्रोग्राम को चलाएँ।

इस रिपोर्ट में निम्नलिखित फ़ील्ड्स बदल दिए गए हैं: (कैसे या क्यों की कोई व्याख्या नहीं)

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

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

जब मैं नहीं जानता कि पिछले बदलावों को दस्तावेजीकरण के बारे में कैसे जाना जा सकता है? मैं जो कुछ भी हम बदल रहा है, उसे दस्तावेजीकरण से शुरू कर सकता हूं : फाइलें, डेटाबेस टेबल ect जो हमें काम करने के लिए सिस्टम के लिए चाहिए। मैं यह भी दस्तावेज कर सकता हूं कि हम क्या करते हैं ; जब रिपोर्ट चलाई जाती है, तो लोगों को एक्स रिपोर्ट / कार्यक्रम का उपयोग करने के लिए क्यों कहा गया। लेकिन जब इन अनुकूलित चीजों में से एक समस्या होती है, तो मैं हमेशा एक वर्ग में वापस आ जाता हूं।

मैं अपने और दूसरों के लिए इस सामान का दस्तावेज़ कैसे बना सकता हूँ?

Answer 1

मुझे लगता है कि यह एक निरर्थक अभ्यास है। यदि यह काम करता है तो यह काम करता है, अगर यह काम नहीं करता है, तो आपको इसे ठीक करना होगा।

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

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

Comments

हाँ, यह लड़का स्काउट नियम के लिए एक और है , लेकिन मैं आपके स्रोत भंडार में दस्तावेज़ भी जोड़ूंगा, विकी में नहीं। आपका दस्तावेज़ आपके स्रोत कोड के नज़दीक है (उदाहरण के लिए Visual Studio में JavaDoc या XML द्वारा) अधिक संभावना यह है कि इसे अद्यतित रखा जाए, साथ ही यह आपके कोड के साथ संस्करणित हो जाता है। मैं केवल एक ही नहीं है जो की तरह rstऔर sphinxके लिए कोड के लिए लेखन प्रलेखन पास रखने ।

— मार्क बूथ

Answer 2

दस्तावेज़ परिवर्तनों के लिए अपने प्रयास को छोड़ दें ।

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

Answer 3

क्या आपके पास स्रोत नियंत्रण है?

क्या आप यह पता लगा सकते हैं कि इससे क्या बदल गया है?

यदि ऐसा है, तो आप मैप कर सकते हैं कि व्यवसाय में बदलाव हो, चाहे नई सुविधाएँ हों या बग ठीक हों।

क्या पुराने डेवलपर्स मेलबॉक्स को फिर से जीवित करना संभव है? (सुनिश्चित नहीं है कि यह गोपनीयता की चिंताओं के साथ व्यवहार्य है या नहीं)। वहाँ के माध्यम से प्राप्त करके बहुत सारी जानकारी प्राप्त की जा सकती है।

Comments

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

— बेन ब्रोका

Answer 4

पहली चीजें पहले। आप अपने दस्तावेज कहां रख रहे हैं? यदि आप पहले से ही नहीं है, तो विकी सेट करें। मैं अपने आप को डॉक्युवीकी पसंद करता हूं, और यहां तक ​​कि एक पूर्वनिर्मित वीएम भी है , अगर आप इतने इच्छुक हैं।

यह कुछ महत्वपूर्ण विशेषताएं प्रदान करता है:

• डॉक्स को कंपनी के लैन पर कहीं भी एक्सेस किया जा सकता है (नए कंप्यूटर पर स्थापित ...)
• सभी डॉक्स एक ही स्थान पर हैं
• सभी डॉक्स खोज योग्य हैं
• आप सहयोग कर सकते हैं (नए सहयोगी, सॉफ्टवेयर के उपयोगकर्ता)

अब, यदि आपका दस्तावेज़ कागज के रूप में है, तो मैं आपको शुभकामनाएँ देता हूँ। यदि आपके पास शब्द डॉक्स हैं, तो आयात स्क्रिप्ट बनाएँ ।

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

अधिक विशिष्ट प्रलेखन के लिए आगे बढ़ते हुए, यदि आपको विभिन्न परियोजनाओं के लिए स्रोत के साथ काम करने की आवश्यकता है, तो सुनिश्चित करें कि आपके पास समुचित विकास का माहौल है ! सामान की एक चेकलिस्ट के लिए आपके पास होना चाहिए:

• संस्करण नियंत्रण ( git , व्यापारिक , जीवाश्म )
• बग ट्रैकिंग ( trac , mantis , redmine , जीवाश्म )
• प्रणाली बिल्ड ( autotools , SCons , buildbot )
• परियोजना नियंत्रण ( ग्रहण , निर्दिष्ट निर्देशिका संरचना, संपादक प्लगइन )
• स्रोत प्रलेखन (README, TODO, INSTALL, स्रोत टिप्पणियाँ)

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

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

संपादित करें:

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

Comments

एक बात जिसका आपने उल्लेख नहीं किया (जो मैंने ईआरबी परियोजनाओं के साथ कभी काम नहीं किया था) जो मैंने .NET के साथ अतीत में किया है और जावा स्वचालित रूप से वर्ग आरेख और अनुक्रम आरेख का उत्पादन करने के लिए एक रिवर्स इंजीनियरिंग टूल का उपयोग कर रहा है। वे इसके लिए काफी मददगार थे। क्या इस मामले में ऐसा कुछ है?

— रिग

+1, बढ़िया जानकारी, क्या आप मुझे डॉक्यूविक के बारे में बता सकते हैं?

— प्रेस्लीडियस

@PresleyDias लिंक में क्या है इसके अलावा? सुविधा सूची की जाँच करें । हमारा सेटअप आर्कटिक टेम्पलेट का उपयोग करता है इसलिए विकी एक मिनी सीएमएस के रूप में कार्य करता है। यदि आप एक डेबियन सिस्टम पर हैं, तो apt-get का उपयोग करने के बजाय मैन्युअल रूप से इंस्टॉल करें ! डेबियन गैर मानक स्थानों का उपयोग करता है, जो इसे प्रबंधित करने के लिए एक दर्द बनाता है।

— स्पेंसर रथबुन

Answer 5

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

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

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

सौभाग्य!

Comments

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

— बेन ब्रोका

Answer 6

जब मैं कुछ ऐसा दस्तावेज करने की कोशिश करता हूं, जो किसी और के पास नहीं है, जो परियोजना या कंपनी के साथ नहीं है, तो मैं हमेशा इस तरह का रवैया शुरू करता हूं: यह मेरे सहित सभी के लिए एक ब्लैकबॉक्स है जब तक मुझे कुछ बदलने या किसी और को समझाने की आवश्यकता नहीं है।

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

Answer 7

आप स्वचालित खोज परीक्षण लिख सकते हैं। इसके कई फायदे हैं:

• आप सीखते हैं कि सिस्टम कैसे काम करता है जैसे आप उन्हें लिखते हैं

• वे बाद के लिए निष्पादन योग्य दस्तावेज के रूप में काम करते हैं

• यदि आप उन्हें नियमित या निरंतर आधार पर चलाते हैं, तो वे यह पता लगाने के लिए एक अच्छा सुरक्षा जाल प्रदान करते हैं कि कब कुछ टूट जाए या कब उन्हें अपडेट करने की आवश्यकता हो

मुझे नहीं पता कि यह आपके विशेष वातावरण में उस तरह के परीक्षण को लिखने के लिए संभव है या नहीं।