Git से नहीं, समस्या से शुरू करें
Docs-as-Code को अक्सर Markdown, Git, pull request, CI और static generator की सूची की तरह पेश किया जाता है। टीम फिर यह भूल जाती है कि पहले पूछना चाहिए: documentation workflow में असली समस्या क्या है? सामग्री पुरानी हो सकती है, review धीमा हो सकता है, terminology बदल सकती है, links टूट सकते हैं या publishing एक व्यक्ति पर निर्भर हो सकती है।
Docs-as-Code तभी उपयोगी है जब वह इन समस्याओं को कम करे, न कि केवल नया tool stack दे।
Docs-as-Code में वास्तव में क्या शामिल है
| चरण | क्या होता है | सरल विकल्प | अधिक परिपक्व विकल्प |
|---|---|---|---|
| Source | content बदलता है | Git में Markdown/AsciiDoc | structured content + metadata schema |
| Editing | author लिखता है | GitHub web editor | github.dev, VS Code, IDE या authoring UI |
| Preview | future page दिखती है | local/web build | हर change के लिए preview |
| Checks | मशीन routine पकड़ती है | links + build | style, terms, API, accessibility, locales |
| Review | meaning verify होता है | एक reviewer | SME + editorial review |
| Publish | site update होती है | manual | checks के बाद CI/CD |
हर चरण को सबसे जटिल बनाना लक्ष्य नहीं है; न्यूनतम पर्याप्त स्तर चुनिए।
Text format का अर्थ IDE की मजबूरी नहीं है
GitHub में file को browser में सीधे edit किया जा सकता है। github.dev browser में search, syntax highlighting और source control देता है और local clone की आवश्यकता नहीं होती। महीने में एक बार correction करने वाले SME को terminal और rebase सिखाना जरूरी नहीं है।
| भूमिका | आम तौर पर पर्याप्त | बिना कारण न माँगें |
|---|---|---|
| Technical writer | github.dev, VS Code या पसंदीदा editor |
कोई खास IDE |
| Occasional SME | web editor + preview | terminal, rebase, local build |
| Developer | IDE + Git | अलग CMS अगर Markdown आसान है |
| Editor | browser/authoring UI | pipeline internals |
Canonical storage format और authoring interface अलग निर्णय हैं।
एक व्यावहारिक end-to-end workflow
Product change → draft → preview → automated checks → technical review → editorial review → merge → publish → production check.
छोटी टीम में एक व्यक्ति कई roles संभाल सकता है। हर typo के लिए pull request बनाना ritual नहीं होना चाहिए। बड़ी टीम में SME facts verify करे और technical writer user task, structure, terminology और clarity पर जिम्मेदार हो।
कौन-सी checks automate करनी चाहिए
| Check | क्या पकड़ता है | उपयोगी error |
|---|---|---|
| Build | syntax, include, template | file + concrete cause |
| Internal links | removed page/anchor | source + target |
| Metadata | title, owner, locale, revision | invalid field |
| Structure | heading hierarchy | exact heading |
| Terminology | obsolete term | term + replacement |
| Style lint | editorial rules | short actionable message |
| Code examples | syntax/format | example + failure |
| API contract | schema/OpenAPI drift | field/endpoint |
| Images | asset, alt, size | file + problem |
| Locales | missing language/revision | article + locale |
| Secrets | token/key | secret को log में दिखाए बिना finding type |
जिस warning को कोई ठीक नहीं करेगा, उसे हटाइए या उपयोगी बनाइए।
इससे कितना समय बच सकता है
Docs-as-Code के लिए कोई ईमानदार universal percentage नहीं है। Visible assumptions से calculate करें। 40 changes प्रति माह और 20 minutes manual routine प्रति change = 13 घंटे 20 मिनट active work. Automation के बाद अगर results देखने में 2 minutes प्रति change लगें, तो लगभग 1 घंटा 20 मिनट रह जाता है।
Assumption: 40 × 20 minutes बनाम 40 × 2 minutes. यह planning model है, industry benchmark नहीं।
Industrial code-review research बताती है कि repetitive work automate करने से measurable benefit हो सकता है, पर वही percentage documentation पर लागू करना सही नहीं होगा।
अपना effect मापिए, study मत गढ़िए
TechWriters को कई projects पर research का दावा तभी करना चाहिए जब वह वास्तव में की गई हो। चार हफ्ते active author time, review wait, SME/editor time, post-publication defects, production lead time और false positives रिकॉर्ड करें। फिर links, metadata और build जैसी एक class automate करके measurement दोहराएँ।
तभी एक ईमानदार case study बनेगी।
Human और machine अलग चीजें review करें
| Machine | Human |
|---|---|
| link मौजूद है | क्या वही सही destination है |
| heading मौजूद है | क्या structure task के अनुसार है |
| term allowed है | क्या audience के लिए clear है |
| example schema से match है | क्या वह real task सिखाता है |
| page build होती है | क्या user सफल हो सकता है |
LLM contradictions flag कर सकती है, लेकिन facts product, specification, test या responsible expert से verify होने चाहिए।
Fanaticism कहाँ शुरू होती है
जब process purity लोगों से अधिक महत्वपूर्ण हो जाए। SME अगर browser में दो मिनट में parameter name ठीक कर सकता है, तो Node.js, local clone और rebase मत थोपिए। Browser editing, issue, assisted authoring या Git process में बदलाव ले जाने वाला व्यक्ति उपलब्ध रखिए।
Docs-as-Code को चरणों में लागू करें
- Week 1: sources Git में और साफ history.
- Week 2: preview और automated build.
- Week 3: तीन से पाँच useful checks.
- Week 4: जहाँ जरूरी हो technical और editorial review अलग करें.
- एक महीने बाद: lead time, routine work, defects और warning noise मापें.
Docs-as-Code तब सफल है जब change, review और publishing आसान हों।
