प्रलेखन के साथ शुरुआत करना

Question

हम अपने कार्यस्थल पर कोई दस्तावेज नहीं कर रहे हैं। मैं इसके लिए पूरी तरह से नया हूं और कुछ मार्गदर्शन प्राप्त करने के लिए कहता हूं।

मेरे कुछ प्रश्न हैं:

• क्या आवश्यक दस्तावेज हैं जो एक sysadmin को लिखना और बनाए रखना चाहिए? और ये इतने महत्वपूर्ण क्यों हैं?

• आप अपने दस्तावेज़ को सिस्टम के साथ कैसे तालमेल रखते हैं? आप जानकारी के दोहराव को कैसे कम करते हैं?

• अनुशंसित गाइड, सर्वोत्तम अभ्यास, विरोधी पैटर्न?

Comments

संबंधित: आप एक नेटवर्क का दस्तावेज कैसे बनाते हैं?

— Zoredache

Answer 1

2003 के बाद से मैं हमारे इनडोर विकी में सब कुछ डॉक्यूमेंट कर रहा हूं ।

सर्वर

• हार्डवेयर चश्मा
• वारंटी जानकारी
• नेटवर्क जानकारी
• और निश्चित रूप से स्थापित सॉफ्टवेयर और कॉन्फ़िगरेशन

वर्कफ़्लो

उदाहरण के लिए, किसी उपयोगकर्ता को जोड़ने या हटाने के लिए कैसे और उसे सभी संबंधित सेवाओं तक पहुंच प्रदान करें

महत्वपूर्ण लिंक

• आपके सभी वेब इंटरफेस के लिए लिंक
• मॉनिटरिंग URL से लिंक (nagios, munin, apc-monitor ...)
• विकी से लिंक (मुद्रित संस्करण के लिए!)

आपातकालीन निर्देश

इंट्रानेट सर्वर / इंटरनेट / वेब सर्वर / आदि नीचे हैं तो क्या करें

महत्वपूर्ण:

पीडीएफ के लिए आसान निर्यात के साथ एक विकी इंजन चुनें!
यह उपयोगी नहीं है यदि आप छुट्टी में हैं, तो आपका विकि चलाने वाला सर्वर डाउन है और किसी को नहीं पता कि क्या करना है क्योंकि आपका दस्तावेज़ ऑफ़लाइन है

Twiki, Dirwiki या Mediawiki पर एक नज़र डालें।

Btw:

वहाँ एक OpenOffice.org प्लगइन है जो सीधे मीडियाविकी को लिखने के लिए है - बहुत सुविधाजनक है।

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

इसके बारे में कुछ infos लिखने के लिए भी अच्छा है /home/adminuser/maintenance। यह त्वरित किया जाता है और बहुत सहायक हो सकता है, अगर कई व्यवस्थापक एक सर्वर पर काम करते हैं। उदाहरण के लिए:

2009-06-27 -thorsten-
          running aptitude update && aptitude full-upgrade
          everything seems ok
2009-06-25 -andreas-
          cups-pdf wasn't reachable. restarted cups
2009-06-23 -thorsten-
          deleted old log under /var/log/squid
etc.

Comments

अगर विकी नीचे है तो फॉलबैक संकेत के लिए +1।

— मैनुअल फॉक्स

OOo क्या है? ओपनऑफ़िस जैसा दिखता है, लेकिन मैं अंतिम "ओ" का पता नहीं लगा सकता। यदि आप प्लगइन का नाम दे सकते हैं, तो यह बहुत अच्छा होगा।

— डैनियल सी। सोबरल

दाईं ओर, OOo OpenOffice.org ;-) विस्तार है: Extension.services.openoffice.org/de/project/wikipublisher

— ThorstenS

Answer 2

जब आप महसूस करते हैं कि जब सभी चाहते हैं (और आवश्यकताएं) प्रलेखन, तो आपको यह भी पहचानना होगा कि किसी के पास सामान को पढ़ने और अध्ययन करने का समय नहीं है।

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

इसे ध्यान में रखते हुए, कुछ सुझाव ...

• पाठ के बड़े ब्लॉक से बचें
• बुलेट सूची आपके मित्र हैं
• एक स्पष्ट आरेख सुनहरा है
• दोहराव एक अच्छा विचार है (1)
• अपडेट और विस्तारित करना आसान बनाएं

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

Comments

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

— मार्क

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

— बेवन

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

— टॉम एच

मैं सहमत हूँ - जब तक यह अच्छी तरह से जाना जाता है और आसानी से पहुँचा जा सकता है - एक एकल आधिकारिक रहस्य स्रोत एक बहुत ही सामान्य एंटीपैटर्न है।

— बेवन

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

— गाल्डो

Answer 3

आवश्यक दस्तावेज़:

• सर्वर प्रलेखन - चश्मा / डिस्क लेआउट / स्थापित सॉफ्टवेयर / नोट का कुछ भी
• सामान्य प्रक्रियाएं - ऐसा कुछ भी जो 'तुच्छ' नहीं है, एक प्रक्रिया प्रलेखित होनी चाहिए, खासकर अगर यह ऐसा कुछ है जो पहले नहीं किया गया है।

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

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

Answer 4

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

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

अपना दस्तावेज़ बनाते समय बस यह ध्यान रखें कि यह किस लिए है। बाद में किसी को इसका उपयोग करने की आवश्यकता होगी। क्या पूर्व ज्ञान के बिना काम करना उपयोगी होगा?

Answer 5

आपके प्रश्न का सीधा उत्तर नहीं, लेकिन सही दिशा में एक सूचक:

मुझे लिमोनसेल्टी और होगन (उर्फ सिसडमिन बाइबल) द्वारा द प्रैक्टिस ऑफ सिस्टम एंड नेटवर्क एडमिनिस्ट्रेशन मिला , क्योंकि यह "बेस्ट प्रैक्टिस" मुद्दों के बारे में है, जैसे कि डॉक्यूमेंटेशन। यदि आप इसके बारे में पहले से नहीं जानते हैं, तो सुनिश्चित करें कि जब भी आपको मौका मिले, आप इसकी जाँच करें।

Comments

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

— टॉमऑन टाईम

Answer 6

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

• बिल्कुल मध्य में स्थित।

  किसी भी एक दस्तावेज़ की एक से अधिक सक्रिय प्रतिलिपि भ्रम की ओर ले जाती हैं। यदि आप सभी को एक ही स्थान, दोनों योगदानकर्ताओं और दर्शकों के लिए संदर्भित करने में सक्षम हैं, तो आप प्रक्रिया को सरल बना सकते हैं।

• सरल संपादन और प्रारूपण।

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

• ऑडिट इतिहास।

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

Comments

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

— थोरस्टनS