इस परियोजना के बारे में

पुस्तक के लिए परियोजना दस्तावेज़ीकरण: यह कैसे जोड़ी गई है, इसे कैसे बनाएँ और जाँचें, और सत्य का स्रोत कहाँ है। पुस्तक के लिए, विषय-सूची देखें।

परियोजना का मानचित्र

पुस्तक: locales/ के अंतर्गत चार लोकेल में प्रकाशित; देखें spec/locales.md। यह लोकेल, en-gb-oxendict/topics/ (63 फ़ाइलें), en-gb-oxendict/front-matter/ और भाग 9 के परिशिष्ट हाथ से लिखा स्रोत हैं; en-001, en-gb और en-us इससे व्युत्पन्न हैं।
सत्य का स्रोत: रिपॉज़िटरी की जड़ में spec/ (साइट पर प्रकाशित नहीं)। संरचना spec/structure.md में घोषित है, लेखन नियम spec/conventions.md में, और वर्तनी spec/oxford-spelling.md में। बाकी सब कुछ इसके अनुरूप बनाया जाता है।
टूलिंग: tools/localize.py अन्य तीन लोकेल व्युत्पन्न करता है; tools/gen_nav.py नेविगेशन बनाता है; tests/validate.py स्पेक लागू करता है; justfile इन्हें जोड़ता है।
योगदानकर्ता मार्गदर्शन: रिपॉज़िटरी की जड़ में AGENTS.md, और योगदान अनुभाग की मार्गदर्शिकाएँ।

बनाना और जाँचना

सत्यापन सूट Python 3 पर बिना किसी अन्य निर्भरता और बिना नेटवर्क पहुँच के चलता है। कार्य just से चलते हैं।

just test    # validate structure, style, links, and spec-vs-disk
just nav     # regenerate the generated navigation files
just check   # nav, then test
just stats   # topic and word counts

इस रिपॉज़िटरी में पुस्तक की सामग्री और विनिर्देश हैं। इसे अलग software-engineering-metrics.github.io रिपॉज़िटरी वेबसाइट में बदलती है।

यहाँ विनिर्देश-संचालित विकास कैसे काम करता है

विनिर्देश पहले आता है। spec/structure.md बताता है कि कौन से विषय हैं और उनकी संख्या कैसे तय है। spec/conventions.md बताता है कि उन्हें कैसे लिखा जाना चाहिए। विषय दोनों को पूरा करने के लिए लिखे जाते हैं। tools/gen_nav.py विषयों से नेविगेशन व्युत्पन्न करता है, और tests/validate.py परिणाम को विनिर्देश के विरुद्ध वापस जाँचता है। यदि विषय और विनिर्देश कभी असहमत हों, तो परीक्षण विफल होते हैं, जो उन्हें फिर से मिलाने का संकेत है।

यह बहाव को दूर रखता है: कोई बदलाव तभी “पूरा” है जब विनिर्देश, विषय, उत्पन्न नेविगेशन और परीक्षण सब सहमत हों।

जानने योग्य डिज़ाइन निर्णय

सपाट, दशमलव-क्रमांकित विषय। फ़ाइलें locales/<locale>/topics/PP-CC-slug.md हैं, हर लोकेल में वही slug। भाग एक पूर्ण संख्या है; विषय एक दशमलव; N.0 भाग का परिचय है। यह स्थिर पहचानकर्ता रखता है और टूल्स को निर्देशिका वृक्ष के बिना क्रमबद्ध और समूहित करने देता है।
एक हाथ से लिखा लोकेल, तीन व्युत्पन्न। en-gb-oxendict ऑक्सफ़ोर्ड वर्तनी है, अधिकांश अंतरराष्ट्रीय मानक संस्थाओं की हाउस शैली (देखें spec/oxford-spelling.md); en-001, en-gb और en-us इससे यांत्रिक रूप से व्युत्पन्न हैं, इसलिए अनुवाद कभी स्रोत से नहीं भटकता।
उत्पन्न नेविगेशन। विषय-सूची, सामग्री पृष्ठ और विषयगत अनुक्रमणिका उत्पन्न होती हैं, इसलिए वे विषयों से कभी नहीं भटकतीं।
ऑफ़लाइन, निर्भरता-मुक्त परीक्षण। सूट केवल मानक लाइब्रेरी का उपयोग करता है इसलिए CI और प्री-कमिट हुक सहित कहीं भी चलता है।
क्रॉस-रेफ़रेंस सादा टेक्स्ट रहते हैं। गद्य विषयों को दशमलव संख्या से संदर्भित करता है (“देखें विषय 2.1”), जैसा विनिर्देश चाहता है; रेंडर करने वाली साइट उन संदर्भों को लिंक में बदलने की ज़िम्मेदार है।
कोई एम-डैश नहीं, नियम से और परीक्षण से। एक सोचा-समझा शैली चुनाव, जो पुस्तक के बढ़ने पर भी सही रहे इसलिए लागू किया गया।
हर मेट्रिक परिवार अपना हेरफेर का रास्ता स्वयं बताता है। यह टेम्पलेट का वह एकमात्र नियम है जिसका सहोदर software-engineering-guide परियोजना में कोई समतुल्य नहीं: यह इसलिए है क्योंकि इस पुस्तक का पूरा विषय ही मापन है, इसलिए मापन का जोखिम स्वयं प्रथम श्रेणी का होना चाहिए, निहित नहीं।

आगे पढ़ें