உங்கள் ஆவணங்களைத் திறக்க இரண்டு கிளிக்குகள் எடுத்தால், வாழ்த்துக்கள் - இது ஏற்கனவே காலாவதியானது

பல வருடங்களாக, நான் எல்லா வகையான திட்டங்களிலும் வேலை செய்துள்ளேன் - பெரிய, சிறிய, குழப்பமான, அதிகமாக வடிவமைக்கப்பட்ட, "தற்காலிகமான", நன்கு கட்டமைக்கப்பட்டதாகக் கூறப்படும், மற்றும் இடையில் உள்ள அனைத்தும். இருப்பினும் ஒரு முறை மிகவும் வேடிக்கையாக சீராக இருந்துள்ளது: ஆவணங்கள் எப்போதும் காணாமல் போகின்றன, காலாவதியாகிவிட்டன, அல்லது 2019 கால முத்திரையால் பாதுகாக்கப்பட்ட Confluence இன் சில மறக்கப்பட்ட மூலையில் புதைந்துள்ளன. ஒவ்வொரு திட்டமும் ஆவணங்களைக் கொண்டிருப்பதாக . கூறுகிறது ஒவ்வொரு குழுவும் அதை புதுப்பித்த நிலையில் வைத்திருப்பதாக அளிக்கிறது. வாக்குறுதி மற்றும் ஒவ்வொரு டெவலப்பரும் நம்பிக்கையுடன் கூறுகிறார், "கவலைப்படாதீர்கள், நான் அதை பின்னர் எழுதுவேன்," இது, நாம் அனைவரும் அறிந்தபடி, " " என்று சொல்வதற்கு சமமான ஆவணம் ஆகும். கடன் அஞ்சலில் உள்ளது இந்த சுழற்சி நான் ஒப்புக்கொள்வதை விட பல முறை மீண்டும் மீண்டும் நடப்பதைப் பார்த்த பிறகு, நான் எளிமையான ஆனால் கொடூரமான உண்மையை உணர்ந்தேன்: ஆவணங்கள் குறியீட்டிற்கு முடிந்தவரை நெருக்கமாக வாழ்ந்தால் மட்டுமே நிலைத்திருக்கும் - ஏனெனில் டெவலப்பர்கள் (என்னை உட்பட) சோம்பேறித்தனமான உயிரினங்கள். அதிலிருந்து, மற்றொரு உணர்தல் வந்தது - காலாவதியான ஆவணங்களின் முக்கிய பிரச்சனை என்னவென்றால், பெரும்பாலான குழுக்கள் அதை முக்கிய மேம்பாட்டு சுழற்சியின் ஒரு பகுதியாக கருதவில்லை, அதை பின்னர் விட்டுவிடுகின்றன அல்லது ஏற்கனவே Confluence இல் எங்காவது வைத்திருந்த சில முந்தைய மேம்பாட்டு விவரக்குறிப்புகளுடன் சமாளிக்கின்றன. பொருள் பொதிந்த ஆவணங்களை எழுத, ஒரு மென்பொருள் கூறுக்கான என்ன வகையான ஆவணங்கள் உள்ளன என்பதை முதலில் விவாதிப்போம்: டெவலப்பர்கள் உண்மையில் பயன்படுத்தக்கூடிய குறியீட்டை ஆவணப்படுத்தும் வழிகள் ஆவணங்கள் குறியீட்டிற்கு நெருக்கமாக வாழ வேண்டும் என்று நீங்கள் ஏற்றுக்கொண்டவுடன், அடுத்த கேள்வி அதை எவ்வாறு கட்டமைப்பது என்பதாகும். நடைமுறையில், நல்ல ஆவணம் என்பது ஒரு ஒற்றை கலைப்பொருள் அல்ல - இது அடுக்குகளின் ஒரு சிறிய சுற்றுச்சூழல் அமைப்பு, ஒவ்வொன்றும் ஒரு வித்தியாசமான நோக்கம் மற்றும் பார்வையாளருக்கு சேவை செய்கிறது. நான் குறிப்பிட்ட அந்த திட்டத்திற்கு (Java + Spring Boot இல் எழுதப்பட்டது), நாங்கள் நான்கு முக்கிய வகையான ஆவணங்களை அடையாளம் கண்டோம்: 1. வாடிக்கையாளர் விவரக்குறிப்புகள் இவை ஒரு கள நிபுணரால் வழக்கமாக தொகுக்கப்படும் வழக்கமான ஆவணங்கள். இலட்சியமாக, அவை பொதுவான மொழியுடன் வளமானவையாகவும், குறியீடு-சாராத வணிக நிகழ்வுகளின் விளக்கங்களாகவும் இருக்கும் - அதாவது, பொறியியலாளர் உண்மையில் கையிலிருக்கும் சிக்கலைப் புரிந்துகொள்ளத் தேவையான அனைத்தும். துரதிர்ஷ்டவசமாக, உண்மையில், இந்த ஆவணங்கள் பெரும்பாலும் Confluence இல் எங்காவது சேமிக்கப்படுகின்றன, திட்டத்தின் தொடக்கத்தில் குழுவுடன் பகிரப்படுகின்றன, பின்னர் கிட்டத்தட்ட ஒருபோதும் புதுப்பிக்கப்படுவதில்லை. என்னை தவறாகப் புரிந்து கொள்ளாதீர்கள்: இந்த ஆவணங்கள் . முக்கியமானவை கள நிபுணர்களிடமிருந்து அறிவை பிரித்தெடுப்பது எந்தவொரு பொறியியல் குழுவிற்கும் ஒரு முக்கிய முன்னுரிமையாக இருக்க வேண்டும். ஆனால் விவரக்குறிப்புகள் உருவாகின்றன, காலக்கெடு அனைவருக்கும் மன அழுத்தத்தை ஏற்படுத்துகிறது, மேலும் அந்த அசல் ஆவணங்கள் மெதுவாக ஆனால் நிச்சயமாக காலாவதியான அடித்தளமாக மாறும். மாறும் தேவைகள், விளிம்பு நிலைகள் மற்றும் திட்ட திருப்பங்கள் பற்றிய அறிவு குறியீட்டில் - அல்லது மோசமாக! - மூத்த டெவலப்பர்களின் மனதில் வாழ்கிறது. இதை நிவர்த்தி செய்ய, நாங்கள் சீரற்ற Word கோப்புகள் அல்லது Confluence பக்கங்களில் விவரக்குறிப்புகளை எழுதுவதை நிறுத்தினோம், அவை மறக்கப்பட உள்ளன, மேலும் அவற்றை முன்புற வரிசைக்கு முடிந்தவரை நெருக்கமாக மாற்றினோம்: குறியீடு களஞ்சியம். நாங்கள் அவற்றை களஞ்சியத்திற்குள் Markdown (.md) கோப்புகளாக சேமிக்க ஆரம்பித்தோம், பொதுவாக ஒரு docs/ கோப்புறையில். பெரிய மைக்ரோசர்வீஸ் சூழல்களில், இந்த ஆவணங்கள் ஒரு பிரத்யேக களஞ்சியத்தை Git submodule ஆக இணைக்க நியாயப்படுத்தக்கூடும். Submodules பெரும்பாலும் புறக்கணிக்கப்படுகின்றன, ஆனால் அவை பல-களஞ்சிய சூழல்களை ஒழுங்கமைக்க ஒரு சக்திவாய்ந்த வழியாகும். Submodules பற்றிய மேலதிக வாசிப்பிற்கு, நான் இந்த வலைப்பதிவு இடுகையை மிகவும் பரிந்துரைக்கிறேன் - . link 2. README – மனிதர்களுக்கான முன் கதவு வாடிக்கையாளர் விவரக்குறிப்புகள் கலைக்களஞ்சியம் என்றால், README என்பது முன் கதவு. ஆனாலும், இது மென்பொருள் திட்டங்களில் மிகவும் புறக்கணிக்கப்பட்ட ஆவணங்களில் ஒன்றாகும். முரணாக, கிட்டத்தட்ட எல்லா பதிப்பு-கட்டுப்பாட்டு தளங்களும் - GitHub, GitLab, Bitbucket - தானாகவே README ஐ முக்கிய திட்டப் பக்கத்தில் காண்பிக்கின்றன. களஞ்சியத்தில் தரையிறங்கும் எந்த டெவலப்பரும் பார்க்கும் முதல் விஷயம் இதுதான். இதை மீறி, READMEகள் பெரும்பாலும் அதிர்ச்சியூட்டும் வகையில் காலியாகவோ, வேதனையாகவோ காலாவதியானவையாகவோ, அல்லது "TODO: பின்னர் ஆவணம் எழுது" என்ற பயங்கரமான வார்த்தைகளால் நிரப்பப்பட்டவையாகவோ இருக்கும், இது நிச்சயமாக நடக்காது. ஒரு நல்ல README விருப்பத்தேர்வு அல்ல. இது உண்மையில் படிக்கப்படக்கூடிய ஒற்றை ஆவணமாகும், ஏனெனில் அதற்கு தேவை. மேலும் இது களஞ்சியத்தின் மூலத்தில் இருப்பதால், குறியீட்டில் வேலை செய்யும் போது டெவலப்பர்கள் அதை புதுப்பிக்க அதிக வாய்ப்புள்ளது. இது குறைந்தபட்ச எதிர்ப்பின் பாதையில் வாழும் ஆவணம். பூஜ்ஜிய கிளிக்குகள் நன்கு எழுதப்பட்ட README ஒரு டெவலப்பர் ஒரு திட்டத்தை எதிர்கொள்ளும் முதல் சில நிமிடங்களில் கொண்டிருக்கும் மிக முக்கியமான கேள்விகளுக்கு பதிலளிக்க வேண்டும்: ஒரு சுருக்கமான நோக்கம் மற்றும் சூழல் அறிக்கை - சந்தைப்படுத்தல் அலங்காரம் இல்லை. இந்த சேவை/திட்டம்/கூறு என்ன செய்கிறது? - இயக்க நேர வழிமுறைகள், சூழல் மாறிகள், சார்பு அமைப்பு, மற்றும் ஏதேனும் திட்ட-குறிப்பிட்ட கட்டளைகள். இதை உள்ளூரில் எவ்வாறு இயக்குவது? - அலகு சோதனைகள், ஒருங்கிணைப்பு சோதனைகள், சோதனை தரவு அமைப்பு, மற்றும் ஏதேனும் சோதனை-தொடர்பான கருவிகள். இதை எவ்வாறு சோதிப்பது? - அடைவு தளவமைப்பு, முக்கிய தொகுதிகள், மற்றும் குறியீட்டின் முக்கியமான பகுதிகளை எங்கு கண்டுபிடிப்பது என்பது பற்றிய ஒரு குறுகிய விளக்கம். திட்டம் எவ்வாறு கட்டமைக்கப்பட்டுள்ளது? - வரிசைப்படுத்தல் ஸ்கிரிப்ட்கள், CI/CD குறிப்புகள், தேவைப்படும் அனுமதிகள், அல்லது தளம் நுணுக்கங்கள். இதை எவ்வாறு வரிசைப்படுத்துவது? உருவாக்கப்பட்ட ஆவணங்கள், கட்டமைப்பு குறிப்புகள், API குறிப்புகள், மற்றும் மையப்படுத்தப்பட்ட வடிவமைப்பு ஆவணங்களுக்கான இணைப்புகள். மேலும் எங்கு படிக்கலாம்? - README என்பது திட்டத்திற்கான நுழைவாயில். இது எதிர்பார்ப்புகளை அமைக்கிறது, பணிக்கு அமர்த்தும் நேரத்தைக் குறைக்கிறது, மேலும் ஒவ்வொரு பொறியியலாளருக்கும் - புதிய அல்லது அனுபவம் வாய்ந்த - ஒரு தெளிவான நோக்குநிலைப் புள்ளியை வழங்குகிறது. சரியாகப் பராமரிக்கப்படும் போது, இது களஞ்சியத்தில் உள்ள ஒற்றை மதிப்புமிக்க ஆவணமாக மாறும். 3. JavaDocs – தொகுப்பி உங்களை பராமரிக்க தொந்தரவு செய்யும் ஆவணங்கள் JavaDocs - பொதுவாக கண்ணுக்குத் தெரியாதவை, அடிக்கடி மறக்கப்படுபவை, ஆனால் ஏதேனும் உடைந்தால் அவசியமானவை. நடைமுறையில், Java திட்டங்களை ஆவணப்படுத்துவது பெரும்பாலும் இரண்டு உச்சநிலைகளில் விழுகிறது: ஒன்று ஒவ்வொரு அற்பமான வரியையும் , அல்லது "குறியீடு சுய-ஆவணப்படுத்தும்" என்பதால் . உண்மை, எப்பொழுதும் போல, இடையில் எங்கோ உள்ளது. அதிகமாக கருத்துரைப்பது எந்த கருத்துரைகளும் இல்லை எங்கள் திட்டத்திற்கு, ஆவணப்படுத்த ஒரு நனவான முடிவை எடுத்தோம். அதாவது: உண்மையில் தேவையானதை மட்டுமே , இதனால் கள சொற்கள் வணிக விவரக்குறிப்புகளில் இருந்தவற்றுடன் சரியாகப் பொருந்தும் பொதுவான மொழியைப் பயன்படுத்துதல் குறியீடு ஏற்கனவே வெளிப்படுத்தும் என்பதை விட, வெளிப்படையற்ற முடிவுகளுக்குப் பின்னால் உள்ள என்பதை விளக்குதல் என்ன ஏன் முக்கிய கள வகுப்புகள், இடைமுகங்கள் மற்றும் சிக்கலான வேலை ஓட்டங்களை ஆவணப்படுத்துதல் முறையின் பெயரை விவரிக்கும் வடிவத்தில் மீண்டும் கூறும் கருத்துரை சுவர்களை தவிர்த்தல் JavaDocs, சரியாகப் பயன்படுத்தப்படும் போது, குறியீட்டை குப்பைப்படுத்தாமல் நோக்கத்தை தெளிவுபடுத்தும் மைக்ரோ-நிலை ஆவணமாக செயல்படுகிறது. மேலும் Confluence பக்கங்களைப் போலல்லாமல், JavaDocs ஒரு உள்ளமைக்கப்பட்ட நன்மையுடன் வருகிறது: அவை ஒத்திசைவில் இருந்து விலகிச் சென்றால் தொகுப்பி உண்மையில் புகார் செய்கிறது. நீங்கள் ஒரு அளவுருவை மறுபெயரிட்டு, JavaDoc குறிச்சொல்லை மறந்துவிட்டால், உருவாக்கம் உங்களுக்கு நினைவூட்டுகிறது. நீங்கள் ஒரு முறையை நீக்கி, பழைய கருத்துரை குறிப்புகளை விட்டுவிட்டால், IDE ஒரு கிறிஸ்துமஸ் மரத்தைப் போல ஒளிரும். இந்த மென்மையான உராய்வுதான் JavaDocs மற்ற ஆவண வடிவங்களை விட மிகவும் துல்லியமாக இருக்க உதவுகிறது - புறக்கணிப்பது தொந்தரவாக இருக்கும். எல்லாவற்றையும் மையப்படுத்தவும் "ஆவணத் தீவுகளை" தவிர்க்கவும், நாங்கள் ஐயும் பயன்படுத்தினோம். Doxygen Doxygen என்பது மென்பொருள் மேம்பாட்டில் பரவலாகப் பயன்படுத்தப்படும் ஒரு ஆவண உருவாக்கும் கருவியாகும். முக்கியமாக C++ சமூகத்தில் பயன்படுத்தப்பட்டாலும், அதை JavaDocs ஐ ஒருங்கிணைத்து ஒரு சீரான, உலாவக்கூடிய குறிப்பை - ஒரு HTML பக்கமாக - நாங்கள் பயன்படுத்தினோம். இது JavaDoc வழங்காத பல அம்சங்களைக் கொண்டுள்ளது, எ.கா., படிநிலைகளுக்கான வகுப்பு வரைபடங்கள் மற்றும் ஒத்துழைப்பு சூழல், மேலும் பல சுருக்கப் பக்கங்கள். இது சிதறிய IDE குறிப்புகளைச் சாராமல், முழு குறியீட்டுத் தளத்தின் ஒரு சுத்தமான, ஒருங்கிணைந்த பார்வையை எங்களுக்கு வழங்கியது. 4. சுத்தமான குறியீடு – நீங்கள் பராமரிக்கத் தேவையில்லாத ஆவணம் இறுதியாக, மிகக் குறைவாக மதிப்பிடப்பட்ட ஆவண வடிவம், டெவலப்பர்கள் அதை உண்மையில் தேவைப்படும் வரை மிகக் குறைவாக மதிப்பிடும் ஒன்றாகும்: சுத்தமான குறியீடு. கருத்துரைகள் வயது. விவரக்குறிப்புகள் விலகிச் செல்லும். READMEகள் புறக்கணிக்கப்படும். JavaDocs காலாவதியானதாக மாறும். ஆனால் நன்கு எழுதப்பட்ட குறியீடு - தெளிவான, நோக்கம் கொண்ட, மற்றும் வெளிப்படையான - ஆவணம். அது மாமா பாப் பிரபலமாக கூறியது போல், "சுத்தமான குறியீடு நன்கு எழுதப்பட்ட உரை போல படிக்கிறது." மற்றும் நடைமுறையில், அதாவது: அதன் நோக்கத்தை வெளிப்படுத்தும் பெயர்களுடன் வகுப்புகள் மற்றும் முறைகள் ஒரு விஷயத்தைச் செய்து அதை நன்றாகச் செய்யும் செயல்பாடுகள் முழுவதுமாக சீராக பயன்படுத்தப்படும் கள சொற்கள் சுத்தமாக தனக்காக எந்த புத்திசாலித்தனமும் இல்லை பக்க விளைவுகளுக்குள் மறைக்கப்பட்ட "ஆச்சரியமான நடத்தைகள்" இல்லை புரிந்துகொள்ள ஒரு PhD தேவைப்படும் தேவையற்ற ஆழமான சுருக்கங்கள் இல்லை சுத்தமான குறியீடு மறுசீரமைப்புகள், ஸ்பிரிண்ட்கள், ஊழியர் திருப்பம், மற்றும் அமைப்பு ரீதியான குழப்பம் ஆகியவற்றில் நிலைத்திருக்கும் என்று உறுதியளிக்கப்பட்ட ஒரு கலைப்பொருள். இது கணினியின் நடத்தைக்கு எப்போதும் ஒத்திசைவாக உள்ளது, ஏனெனில் - இது கணினியின் ஆகும். நடத்தை காலப்போக்கில் எங்களுக்கு ஒரு எளிய விதி உருவானது: ஒரு முறையை விளக்க ஒரு பத்தி கருத்துரைகள் தேவைப்பட்டால், உண்மையான பிரச்சினை அந்த முறையாகும். குறியீடு வெளிப்படையானதாக இருக்கும்போது, மற்ற அனைத்தும் எளிதாகிறது → JavaDocs இலகுவாகவும் கவனம் செலுத்தியதாகவும் மாறும் → பணிக்கு அமர்த்தல் வெளிப்படையானதாக இருப்பதால் README சுருங்கும் → கள மாதிரி வணிக சொற்களஞ்சியத்தைப் பிரதிபலிப்பதால் விவரக்குறிப்புகள் தெளிவாகின்றன. சுத்தமான குறியீடு ஆவணங்களின் தேவையை அகற்றாது; அது அதை . நங்கூரமிடுகிறது இது விவரக்குறிப்புகள், READMEகள், JavaDocs போன்ற பிற அனைத்து ஆவண வடிவங்களும் தெளிவற்ற செயலாக்கத்திற்கு ஈடுசெய்வதற்குப் பதிலாக உண்மையை வலுப்படுத்துவதை உறுதி செய்கிறது. இறுதியில், சுத்தமான குறியீடு பராமரிப்பு, CI ஒருங்கிணைப்பு, அல்லது எந்த கருவியும் தேவையில்லாத ஆவணமாகும். கணினி உண்மையில் என்ன செய்கிறது என்பதற்கு இது மிகவும் நேர்மையான, நம்பகமான விளக்கம். அனைத்தையும் ஒன்றாகக் கொண்டுவருதல் — ஒரு வாழும் ஆவணக் குழாய் நாங்கள் ஆவணங்களை எவ்வாறு எழுதினோம் என்பதை மேம்படுத்திய பிறகு, இறுதி படி அதை உருவாக்கியது மட்டுமல்லாமல், அதை தொடர்ந்து வழங்கவும் எப்போதும் அணுகக்கூடியதாகவும் இருப்பதை உறுதி செய்வதாகும். அதற்காக, எங்கள் விவரக்குறிப்புகள், README கோப்புகள் மற்றும் JavaDocs ஐ ஒரு ஒற்றை, ஒருங்கிணைந்த மாற்றிய ஒரு ஆவணக் குழாயை நாங்கள் கட்டினோம். வாழும் ஆவண போர்ட்டலாக எங்கள் ஆவணங்கள் எங்கள் குறியீட்டிற்கு முடிந்தவரை நெருக்கமாக வாழ வேண்டும் என்று நாங்கள் விரும்பியதால், வழியாக அனைத்தையும் வரிசைப்படுத்த முடிவு செய்தோம், இது குறியீட்டுத் தளத்துடன் நேரடியாக இணைக்கப்பட்ட ஒரு சிரமமில்லாத, பதிப்பு-கட்டுப்பாட்டு ஹோஸ்டிங் தீர்வை எங்களுக்கு வழங்கியது. Github Pages Github க்கு குறிப்பிட்டது அல்ல (உதாரணமாக GitLab, GitLab Pages ஐயும் கொண்டுள்ளது) - இது நான் மேலதிக வாசிப்பிற்கு பரிந்துரைக்கும் பிரபலமான பதிப்பு கட்டுப்பாட்டு அமைப்புகளின் மற்றொரு சிறந்த அம்சமாகும் - . GitHub Pages link அனைத்தையும் ஒருங்கிணைந்த பக்கங்களின் தொகுப்பாக தொகுக்க, நாங்கள் ஐப் பயன்படுத்தினோம். Sphinx Sphinx என்பது பைத்தானில் எழுதப்பட்ட ஒரு சக்திவாய்ந்த ஆவண உருவாக்கும் கருவி. இது reStructuredText அல்லது Markdown இல் எழுதப்பட்ட மூலக் கோப்புகளை எடுத்து HTML, PDF மற்றும் ePub உள்ளிட்ட பல்வேறு வெளியீட்டு வடிவங்களுக்கு மொழிபெயர்க்கிறது. Sphinx கட்டமைப்பு, வழிசெலுத்தல் மற்றும் தீமிங்கை கையாண்டது. Doxygen, செருகுநிரலைப் பயன்படுத்தி தானாக உருவாக்கப்பட்ட JavaDocs ஐ Sphinx க்கு ஊட்டமளித்தது, இது மூலக் குறியீட்டிலிருந்து ஒரு முழுமையான உலாவக்கூடிய API குறிப்பை எங்களுக்கு வழங்கியது. இதற்கிடையில், ரூட் README களஞ்சியத்தை ஆராயும் டெவலப்பர்களுக்கு உடனடி நுழைவுப் புள்ளியாக செயல்பட்டது, இது உருவாக்கப்பட்ட ஆவண தளத்துடன் தடையின்றி இணைக்கப்பட்டது. Breathe முக்கியமான ஒன்றில் ஒவ்வொரு ஒன்றிணைப்பும் ஆவணங்களை மீண்டும் உருவாக்கும் ஒரு CI வேலையைத் தூண்டியது, போர்ட்டல் சமீபத்திய குறியீடு மாற்றங்கள், API புதுப்பிப்புகள் மற்றும் வடிவமைப்பு முடிவுகளைப் பிரதிபலிப்பதை உறுதி செய்கிறது. எதுவும் தனித்தனியாக வாழவில்லை. எதுவுமே கைமுறையாக ஒத்திசைக்க வேண்டியதில்லை. மற்றும் முக்கியமாக - எதுவும் ஒரு கிளிக்கிற்கு மேல் இல்லை. இது எங்கள் ஆவணங்களை ஒரு நிலையான கலைப்பொருளிலிருந்து டெவலப்பர்கள் உண்மையில் பயன்படுத்தும் ஒரு தொடர்ச்சியாக புதுப்பிக்கப்பட்ட சுற்றுச்சூழல் அமைப்பாக மாற்றியது, ஏனெனில் இது அவர்களின் அன்றாட பணிப்பாய்வுக்கு நேரடியாக ஒருங்கிணைக்கப்பட்டது மற்றும் குறியீட்டுக்கு அருகில் வாழ்ந்தது. முடிவுரை — ஆவணம் எங்கள் பொறுப்பு, எங்கள் சுமை அல்ல நாள் முடிவில், ஆவணங்களை எழுதுவது விருப்பத்தேர்வு அல்ல. இது பொறியியல் நிபுணர்களாக எங்கள் வேலையின் ஒரு பகுதியாகும். எதிர்கால சக ஊழியர்கள் அதை நம்பியிருக்கிறார்கள். பணிக்கு அமர்த்துவது அதை நம்பியிருக்கிறது. பராமரிப்பு, நம்பகத்தன்மை, மற்றும் கட்டடக்கலை தெளிவு கூட அதை நம்பியிருக்கிறது. ஆனால் அந்த பொறுப்பை ஏற்றுக்கொள்வது ஆவணம் வேதனையாக இருக்க வேண்டும் என்று அர்த்தமல்ல. ஆவணங்களை குறியீட்டிற்கு நெருக்கமாக வைத்திருப்பதன் மூலமும், தானியக்கமாக்கக்கூடிய எதையும் தானியக்கமாக்குவதன் மூலமும், Markdown, JavaDocs, Doxygen, மற்றும் Sphinx போன்ற புத்திசாலித்தனமான கருவிகளை நம்புவதன் மூலமும், வழக்கமாக ஆவண முயற்சிகளைக் கொல்லும் உராய்வை நாங்கள் அகற்றுகிறோம். நாங்கள் பாரம்பரியமாக ஒரு வேலையாகத் தோன்றும் ஒன்றை அன்றாட மேம்பாட்டின் இயற்கையான நீட்டிப்பாக மாற்றுகிறோம். மேலும் நாங்கள் அதை சுத்தமான குறியீடு, நல்ல READMEகள், மற்றும் கள-செறிவான விவரக்குறிப்புகளுடன் இணைக்கும்போது, முழு சுற்றுச்சூழல் அமைப்பும் சுய-நிலைத்தன்மை வாய்ந்ததாகிறது. ஆவணம் சரியானதாக இருக்கத் தேவையில்லை - அது அணுகக்கூடியதாகவும், துல்லியமாகவும், உயிருடனும் இருக்க வேண்டும். டெவலப்பர்கள் குறியீட்டை எழுதுவதைப் போலவே எளிதாக ஆவணங்களைப் புதுப்பிக்க ஊக்குவிக்கும் அமைப்புகளை நாங்கள் உருவாக்கும்போது, அனைவரும் பயனடைகிறார்கள்: குழு, தயாரிப்பு, மற்றும் மிக முக்கியமாக, ஆறு மாதங்களுக்குப் பிறகு திட்டத்தைப் பெறுபவர். நல்ல ஆவணம் நம்மை சோம்பேறியாக மாற்றாது. இது சோம்பேறியாக இருப்பதை சிறந்த மென்பொருளை உருவாக்குவதோடு இணக்கமாக ஆக்குகிறது.