दस्तावेज़ीकरण को परिवर्तन का हिस्सा मानें
जब व्यवहार बदलता है, तो दस्तावेज़ अपडेट करने का सबसे विश्वसनीय समय उसी पुल रिक्वेस्ट में होता है। समीक्षक कार्यान्वयन और व्याख्या को एक साथ तुलना कर सकते हैं, और वर्ज़न टैग दस्तावेज़ों को जारी किए गए कोड के साथ संरेखित रखते हैं।
- जिस घटक की वह व्याख्या करता है उसके पास एक केंद्रित README रखें।
- जब सार्वजनिक व्यवहार, कॉन्फ़िगरेशन या परिचालन चरण बदलते हैं तो दस्तावेज़ अपडेट आवश्यक करें।
- सतत एकीकरण में लिंक और शैली जाँच का उपयोग करें।
- उच्च-जोखिम वाली रनबुक और संदर्भ पृष्ठों के लिए स्पष्ट स्वामित्व तय करें।
लिखने से पहले दस्तावेज़ का प्रकार चुनें
ट्यूटोरियल अनुक्रम के माध्यम से सिखाता है। हाउ-टू गाइड एक कार्य हल करता है। संदर्भ सामग्री सटीक व्यवहार का वर्णन करती है। स्पष्टीकरण संदर्भ और व्यापार-नाप प्रदान करता है। चारों को एक लंबे README में मिलाने से प्रत्येक का उपयोग कठिन हो जाता है।
आर्किटेक्चर निर्णय रिकॉर्ड एक और उपयोगी पैटर्न है: जब तर्क अभी ताज़ा हो, संदर्भ, निर्णय, विकल्प और परिणामों को रिकॉर्ड करें। मार्कडाउन रिकॉर्ड को कोड के निकट रखता है, बिना अलग प्रकाशन वर्कफ़्लो की आवश्यकता के।
कोड उदाहरणों को परीक्षण योग्य और ईमानदार बनाएँ
पाठक उदाहरणों को कॉपी करते हैं। आवश्यक import, यथार्थवादी नाम, अपेक्षित आउटपुट और प्रासंगिक त्रुटि पथ शामिल करें। यदि स्निपेट जानबूझकर अधूरा है, तो उसे बताएँ। एक छोटा परीक्षण किया हुआ उदाहरण उस बड़े ब्लॉक से अधिक मूल्यवान है जो केवल प्रशंसनीय दिखता है।
```bash # Validate docs before opening a pull request npm run lint npm run typecheck ``` Expected result: both commands exit with status 0.
समीक्षा योग्य डिफ़ के लिए अनुकूलन करें
प्रति पंक्ति एक वाक्य तभी उपयोग करें जब रिपॉज़िटरी उस परंपरा को लगातार अपनाती है; अन्यथा स्वाभाविक रूप से तोड़ें और प्रस्तुति टूलिंग पर छोड़ दें। तथ्यात्मक संपादन के दौरान पूरी फ़ाइल को फिर से फ़ॉर्मेट करने से बचें। स्थिर शीर्षक और संदर्भ-शैली लिंक बड़े दस्तावेज़ों को शोर-मुक्त डिफ़ के साथ बदलना आसान बना सकते हैं।
- शीर्षकों को विशिष्ट नाम दें जो जनरेट किए गए एंकरों में उपयोगी बने रहें।
- टेबल को संकीर्ण रखें और गद्य-भारी कोशिकाओं से बचें।
- उन फ़ाइलों के लिए सापेक्ष लिंक उपयोग करें जो रिपॉज़िटरी के साथ चलती हैं।
- उदाहरणों में गोपनीयता, निजी लॉग या असंपादित उत्पादन डेटा न चिपकाएँ।
रूपांतरण को प्रवास के प्रारंभ बिंदु के रूप में उपयोग करें
एक Word फ़ाइल, स्प्रेडशीट, PDF या स्लाइड डेक में मूल्यवान ज्ञान हो सकता है जो अभी docs-as-code वर्कफ़्लो में नहीं बैठता। इसे मार्कडाउन में बदलने से प्रस्तुति परत का अधिकांश हिस्सा हट जाता है, लेकिन एक डेवलपर को अब भी शीर्षकों को सामान्य करना, लिंक ठीक करना, फ़ाइल सीमाएँ चुननी और तकनीकी सटीकता की पुष्टि करनी होती है।
जब तक परिवर्तित संस्करण की समीक्षा न हो जाए, स्रोत दस्तावेज़ रखें। गणना किए गए डेटा या हस्ताक्षरित रिकॉर्ड के लिए, रिपॉज़िटरी में पठनीय मार्कडाउन स्नैपशॉट जोड़ने के बाद भी मूल सत्य का स्रोत बना रह सकता है।