मैंने लोगों को मेरी README का पालन करने की कोशिश करने के लिए पैसे दिए
किसी project की README को script की तरह follow करने के लिए लोगों को पैसे देना यह उजागर करता है कि developer documentation में कितनी assumptions, omissions, और distractions घुस आती हैं। टिप्पणीकारों का तर्क है कि READMEs को साफ़-साफ़ बताना चाहिए कि software क्या करता है, prerequisites सूचीबद्ध करनी चाहिए, और एक minimal, end-to-end setup path देना चाहिए; साथ ही कई लोग emoji clutter, अंदरूनी jokes, और AI-generated “slop” की आलोचना करते हैं जो ज़रूरी जानकारी को ढक देते हैं। कई लोग बताते हैं कि इस तरह का real-user testing UX usability practices जैसा है और automated checks या LLM-based reviews का पूरक है, जो फिर भी clarity, boredom, या confusion का मूल्यांकन इंसानों की तरह नहीं कर सकते।
“मेरी README का पालन करने के लिए लोगों को पैसे देने” पर समग्र प्रतिक्रिया
- कई लोग इसे तकनीकी दस्तावेज़ों पर लागू की गई सामान्य usability testing मानते हैं।
- कई लोगों ने इस विचार की सराहना की और कहा कि इसी तरह की आंतरिक प्रक्रियाएँ (नई नियुक्तियों को README के ज़रिए onboarding कराना, friction logs) कई समस्याओं को जल्दी पकड़ लेती हैं।
- कुछ का तर्क है कि आप अक्सर अपनी ही मशीन पर अपनी ही निर्देशावली को सख्ती से follow करके ज़्यादातर समस्याएँ खुद ही पकड़ सकते हैं।
विस्तार का स्तर और पूर्व-आवश्यकताएँ
- प्रबल भावना यह है कि READMEs अक्सर महत्वपूर्ण “zeroth steps” छोड़ देती हैं (जैसे php-fpm, runtimes, या tools इंस्टॉल करना)।
- इस बात पर सहमति है कि एक स्पष्ट “Prerequisites” section key है, भले ही आप हर dependency कैसे install करनी है, यह न समझाएँ।
- इस पर बहस है कि कितना पीछे जाना चाहिए: कुछ लोग
git cloneसे शुरू होने वाले commands चाहते हैं; दूसरे कहते हैं कि आप हर OS/package manager की सूची नहीं बना सकते।
शैली: संक्षिप्तता, संरचना, और software क्या करता है
- बार-बार शिकायत: ऐसी READMEs जो कभी साफ़ तौर पर नहीं बतातीं कि project क्या करता है, बल्कि सिर्फ़ इसे install करने का तरीका या buzzwords list करती हैं।
- कई लोग छोटी, task-oriented READMEs को पसंद करते हैं जो लंबे “novels” या FAQs के बजाय richer docs के लिए entrypoint का काम करें।
- Diataxis जैसे frameworks और tutorial बनाम reference का split docs को संरचित करने के लिए उपयोगी माने जाते हैं।
टोन: emojis, jokes, और personality
- emojis का ज़्यादा उपयोग व्यापक रूप से नापसंद किया जाता है; कई लोग emoji-heavy READMEs को LLM-generated content या childishness से जोड़ते हैं।
- कुछ लोगों को हल्का humor स्वीकार्य है अगर वह meaning को अस्पष्ट न करे; दूसरे तर्क देते हैं कि jokes और culture-specific references confusing होते हैं और जोखिम के लायक नहीं।
- कई लोग note करते हैं कि लेखक को जो मज़ेदार लगता है, वह अक्सर readers पर असर नहीं करता।
डॉक्यूमेंटेशन परीक्षण में इंसान बनाम AI/agents
- कई लोग सुझाव देते हैं कि LLMs और agents अच्छे हैं:
- sandboxes में step-by-step instructions follow करने में।
- missing steps और inconsistencies को उजागर करने में।
- लेकिन humans को आवश्यक माना जाता है:
- boredom, clarity, और overall UX का आकलन करने में।
- assumptions, confusing language, और सांस्कृतिक/ज्ञान gaps को सामने लाने में।
Installation friction और automation
- कई लोग उन projects पर अफ़सोस जताते हैं जो README होने के बावजूद भी “just run” नहीं करते।
- Containerization (Docker) और environment tooling (Nix, direnv) को reproducible, low-friction setups के लिए सराहा जाता है।
- कुछ का तर्क है कि वास्तव में polished software को manual READMEs पर बहुत निर्भर रहने के बजाय setup को automate करना चाहिए।