एक बार फिर प्रलेखन के बारे में

स्तर: शुरुआत, निरंतर, आलसी

फिर क्या? लेकिन क्यों?

प्रलेखन के बारे में बहुत कुछ कहा गया है, जिसमें हैबे भी शामिल है, जहां मुझे कई लेख मिले। हालाँकि, उन लेखों को जो मैंने देखा ( एक , दो , तीन , चार ) क्यों और क्या दस्तावेज होने की आवश्यकता के सवालों का जवाब देते हैं। मैं यह दिखाते हुए दो सरल उदाहरण देना चाहता हूं कि कैसे, और यह प्रदर्शित करते हुए कि प्रलेखन नरम और रेशमी प्रकाश और सुखद हो सकता है।

दस्तावेज क्या है?

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

सर्वर प्रलेखन

मैं जिस प्रलेखन का संचालन करता हूं, वह मुख्यतः पाठ्य है। लेकिन अब मैं इस विषय से हटकर योजना के बारे में बात करूंगा।

ग्राफिक योजनाओं के बारे में मूर्खता

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

तो पाठ

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

इसलिए, पाठ के साथ काम करने के लिए कुछ सिद्धांत:
1. इसे पढ़ने के लिए डॉक्यूमेंटेशन लिखा जाता है। इसलिए, प्रलेखन प्रारूप विकसित करते समय, पूरी तरह से शुरुआत करें क्योंकि यह आपके काम में आपकी मदद कर सकता है। अपने आप से पूछें, “मुझे इस सेवा के बारे में क्या पता होना चाहिए? इस कार के बारे में? "
2. संक्षेप में लिखें। अगर कुछ लिखा नहीं जा सकता है, क्योंकि यह पहले से ही कहीं है, तो लिखो मत, क्योंकि अनुभव से हमें पाठ के विली मिलते हैं, जो तब बस मारे जाते हैं। उदाहरण के लिए, सर्वर विनिर्देशों को निर्माता की वेबसाइट पर एक दस्तावेज़ द्वारा संदर्भित किया जा सकता है। तो, कोई अतिरेक और अनावश्यक काम नहीं है!
3. लिखो नहीं, कॉपी करो! अगर कुछ सीधे विन्यास से लिया जा सकता है, तो इसे सीधे विन्यास से लें। कमांड का आउटपुट भी जाएगा। यदि आप एक स्क्रिप्ट बना सकते हैं कि वह सूचनाओं को विन्यास से बाहर निकालता है और इसे विकि पर रखता है (जो आसान है) - इसे करें। स्वयं सर्वर के लिए प्रलेखन को / etc / motd में डाला जा सकता है और फिर विकी पर अपलोड किया जा सकता है, फिर परिवर्तनों का दस्तावेज़ीकरण करना सभी के लिए बहुत आसान होगा।
3. स्ट्रक्चरिंग ही हमारा सब कुछ है। इंडेंट अधीनस्थ। आप सूचियों का उपयोग कर सकते हैं, लेकिन सूचियां अच्छी हैं, और इंडेंटेशन बेहतर है।
4. दस्तावेज़ीकरण मानक होना चाहिए, लेकिन सामान्य ज्ञान अधिक महत्वपूर्ण है। उदाहरण के लिए, यदि सर्वर के कामकाज में कुछ निहित विशेषताएं हैं, तो एक नया उपधारा और लिखें। यदि सर्वर में कुछ गड़बड़ है, तो इसे उठाएं और इसे लाल रंग में हाइलाइट करें।
5. निगरानी प्रलेखन नहीं है। कॉन्फ़िगरेशन प्रबंधन सिस्टम भी दस्तावेज़ नहीं हैं। यह स्पष्ट है कि यदि एक ही प्रकार के 100 सर्वर हैं, तो केवल एक ही दस्तावेज किया जा सकता है, लेकिन दूसरी ओर, यदि आपके पास एक ही प्रकार के 100 सर्वर हैं, तो आप पहले से ही जानते हैं।

सर्वर विवरण टेम्पलेट

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

टेम्पलेट में निम्नलिखित आइटम शामिल हैं:
1. सर्वर का नाम
2. सेवाएं प्रदान की गईं
3. जिम्मेदार
4. प्रणाली
5. निगरानी करना
6. बैकअप

सर्वर का नाम

powerconsumer.site 

प्रदान की गई सेवाएं

    --------------------------- :  ,        10^100  .   ,      memeater. : Memory eating service, socket http://bofh.ntk.net/BOFH/ 80/tcp : /usr/local/bin/cpueater init-: /etc/init.d/cpueater  : /srv/bofh/cpueater : /var/log/cpueater[1,7] : every day, keeping last 7 days : http://zabbix.site/cpueater/ : /etc/cpueater/cpueater.conf    ----------------------- :  ,          . : Memory eating service, socket http://bofh.ntk.net/BOFH/ 80/tcp : /usr/local/bin/memeater init-: /etc/init.d/memeater  : /srv/bofh/memeater : /var/log/memeater[1,7] : every day, keeping last 7 days : http://zabbix.site/memeater/ : /etc/memeater/memeater.conf 

समर्पित

 BOFH 

प्रणाली

 Debian Squeeze 6.04 Disk subsystem -------------- RAID-6 on LSI-based controller with 10 active disks and 2 hot-spares. 10.0GB ext4 / boot 10.0GB linux-swap(v1) swap 10.0GB ext4 /tmp 10.0GB ext4 /usr 20.0GB ext4 /var 40.0GB ext4 /home 20.0GB /opt 2300GB /srv/bofh Network subsystem ----------------- iface eth0 inet static address 192.168.1.10 netmask 255.255.255.0 network 129.168.1.0 gateway 192.168.1.1 up sleep 5; /sbin/ethtool -s eth0 autoneg off speed 100 duplex full 

निगरानी

 Zabbix-agent with custom scripts: /opt/zabbix/cpueater.py /opt/zabbix/memeater.py 

बैकअप

 /srv/bofh/cpueater/ /srv/bofh/memeater/ 

सर्वर इंटरऑपरेबिलिटी

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

इसलिए, यदि आप प्रलेखन रखने के लिए बहुत आलसी हैं, तो कम से कम करें!

प्रलेखन का प्रारूप सरल है। होस्ट पर प्रत्येक सेवा (डेमॉन) के लिए, सभी होस्ट और सेवाओं को रिकॉर्ड किया जाता है जिसके साथ वर्णित सेवा इंटरैक्ट करती है।

  balancer.site ------------- ngnix: --> webserver0.site/ngnix: 80/tcp ngnix: --> webserver1.site/ngnix: 80/tcp webserver0.site --------------- php-fpm: --> sql.site/postgresql: 5423/tcp webserver1.site --------------- php-fpm: --> sql.site/postgresql: 5423/tcp sql.site -------- postgresql: --> backup.sql.site/postgresql: 22/tcp backup.sql.site --------------- amanda.site ----------- amanda-server: --> balancer.site/amanda-client: 30000-30100/tcp, 10800/udp amanda-server: --> webserver0.site/amanda-client: 30000-30100/tcp, 10800/udp amanda-server: --> sql.site/amanda-client: 30000-30100/tcp, 10800/udp zabbix.site ----------- zabbix-server: --> balancer.site/zabbix-agent: 10050/tcp zabbix-server: --> webserver0.site/zabbix-agent: 10050/tcp zabbix-server: --> webserver1.site/zabbix-agent: 10050/tcp zabbix-server: --> sql.site/zabbix-agent: 10050/tcp zabbix-server: --> backup.sql.site/zabbix-agent: 10050/tcp zabbix-server: --> amanda.site/zabbix-agent: 10050/tcp 

अंत में

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

खैर, यह सब है। सभी को नमस्कार!

अद्यतन: VolCh के रूप में, और फिर powerman भी यथोचित टिप्पणियों में नोट किया, यह प्रलेखन के लिए संस्करण नियंत्रण प्रणाली का उपयोग करने और कोड के साथ प्रलेखन के साथ काम करने के लिए सुविधाजनक है। टिप्पणियों में क्यों है इसका स्पष्टीकरण। तो फिर आप यहाँ बताए अनुसार कर सकते हैं, मेरी राय में एक बहुत अच्छा समाधान: habrahabr.ru/post/12/3

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

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

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

UPDATE3: टिप्पणियों में, dyadyavasya ने कहा कि उनके पास Google डॉक्स का उपयोग करने का सकारात्मक अनुभव है। इसलिए यदि आप बीवर कॉर्पोरेशन को अपना डेटा देने से डरते नहीं हैं - इसके लिए जाएं।