தொழில்நுட்ப ஆவணமாக்கல் என்பது குறியீடு தொகுக்கப்பட்ட பிறகு நீங்கள் முடிக்கும் ஒரு துணைப் பணி அல்ல. இது ஒவ்வொரு மென்பொருள் திட்டத்தின் மையத்திலும் உள்ளது.

தொழில்நுட்ப ஆவணமாக்கல் (Technical documentation) என்பது குறியீடு (code) வெற்றிகரமாக இயங்கிய பிறகு செய்து முடிக்க வேண்டிய ஒரு துணைப்பணி அல்ல. இது ஒவ்வொரு மென்பொருள் திட்டத்தின் மையப்பகுதியிலும் அமைகிறது; ஒரு புதிய டெவலப்பர் தனது முதல் நாளிலேயே ஒரு பிழையை (bug) சரிசெய்ய முடியுமா அல்லது குழப்பத்தினால் ஒரு பயனர் உங்கள் தயாரிப்பை ஐந்து நிமிடங்களிலேயே விட்டுவிடுகிறாரா என்பதை இதுவே தீர்மானிக்கிறது. சிறந்த ஆவணங்கள் பயனர்கள் உண்மையான பணிகளைச் செய்து முடிக்க உதவுகின்றன. எதிர்காலப் பராமரிப்பாளர்கள் (maintainers) ஒரு மாட்யூல் (module) ஏன் உருவாக்கப்பட்டது என்பதையும், அனைத்தையும் உடைக்காமல் அதை எவ்வாறு மாற்றுவது என்பதையும் புரிந்துகொள்ள அவை உதவுகின்றன. இருப்பினும், பல குழுக்கள் ஆவணமாக்கலை ஒரு தேவையற்ற விஷயமாகக் கருதுகின்றனர்; அவசரமாகத் தயார் செய்யப்பட்ட ஒரு README அல்லது காலாவதியாகிப் போன ஒரு wiki பக்கம் போல அதை நடத்துகின்றனர். உண்மையாகப் பயனுள்ள ஆவணங்களை எழுதுவது என்பது நீங்கள் திட்டமிட்டு மேம்படுத்திக்கொள்ளக்கூடிய ஒரு திறமையாகும்.

எழுதுவதற்கு முன் உங்கள் வாசகர்களைத் தெரிந்து கொள்ளுங்கள்

நீங்கள் ஒரு தலைப்பைக் கூடத் தட்டச்சு செய்வதற்கு முன், யார் இதைப் படிக்கப் போகிறார்கள் என்பதைத் தீர்மானிக்கவும். connection pool settings-களைத் தேடும் ஒரு database administrator-க்கும், React component props-களைத் தேடும் ஒரு front-end developer-க்கும் இடையில் எந்த ஒற்றுமையும் இல்லை. இறுதிப் பயனர்களுக்கு (End-users) வரிசைப்படுத்தப்பட்ட படிகள் மற்றும் ஸ்கிரீன்ஷாட்டுகள் தேவைப்படலாம், கட்டமைப்பு வரைபடங்கள் (architecture diagrams) அல்ல. அவர்கள் ஒரு PDF-ஐ எவ்வாறு ஏற்றுமதி (export) செய்வது என்பதை அறிய விரும்புகிறார்களே தவிர, rendering pipeline எவ்வாறு செயல்படுகிறது என்பதை அல்ல. உங்கள் library-யை ஒருங்கிணைக்கும் டெவலப்பர்களுக்குத் துல்லியமான function signatures, error codes மற்றும் எளிதாக நகலெடுத்துப் பயன்படுத்தக்கூடிய (copy-pasteable) சிறு குறியீடுகள் (snippets) தேவை. சிஸ்டம் அட்மினிஸ்ட்ரேட்டர்களுக்கு (System administrators) நிறுவல் தேவைகள் (installation prerequisites), environment variables மற்றும் பொதுவான தோல்வி முறைகளில் இருந்து தொடங்கும் சிக்கலைத் தீர்க்கும் வழிமுறைகள் (troubleshooting flows) தேவை.

ஒரே நீண்ட உரையால் இந்த மூன்று குழுக்களையும் திருப்திப்படுத்த முயன்றால், அனைவரும் ஏமாற்றமடைவார்கள். தனித்தனி வழிகளை உருவாக்கவும். ஒரு தனிப் பக்கத்தையே கூட "இயக்குபவர்களுக்காக" (For operators) மற்றும் "கிளையண்ட் டெவலப்பர்களுக்காக" (For client developers) போன்ற தெளிவான தலைப்புகளுடன் பிரிக்கலாம். "இந்த பத்தி எனக்காகத் தான் எழுதப்பட்டதா?" என்ற மனக் குழப்பத்தைத் தவிர்ப்பதே இதன் இலக்காகும்.

தேவையற்றவற்றைத் தவிர்க்கவும்

தெளிவு என்பது நுணுக்கமான சொற்களை விட மேலானது. குறுகிய வாக்கியங்களைப் பயன்படுத்தவும். செய்வினை (active voice) பயன்படுத்தவும். "The database should be initialized by the user" என்பதை விட "Initialize the database" என்பது தெளிவானது. "idempotency" அல்லது "serialization" போன்ற தொழில்நுட்பச் சொற்களைப் பயன்படுத்த வேண்டியிருக்கும் போது, அவற்றை அந்த இடத்திலேயே விளக்கவும் அல்லது ஒரு கலைச்சொல் பட்டியலுக்கு (glossary) இணைக்கவும். வாசகருக்கு ஏற்கனவே இதைப் பற்றிய அறிவு இருக்கும் என்று assumptions வைக்காதீர்கள்.

ஒரு நடைமுறைச் சோதனை: உங்கள் பத்தியை சத்தமாக வாசித்துப் பாருங்கள். உங்களுக்கு மூச்சுத் திணறினால், அந்த வாக்கியம் மிக நீளமானது என்று அர்த்தம். மற்றொரு சோதனை: அலங்காரமான வினைச்சொற்களுக்குப் பதிலாக எளிய வினைச்சொற்களைப் பயன்படுத்தவும். "utilize the API" என்ற சொற்றொடரை அர்த்தம் மாறாமல் "use the API" என்று மாற்ற முடிந்தால், அந்த மாற்றத்தைச் செய்யுங்கள். எளிய மொழி என்பது அறிவற்ற மொழி என்று பொருளல்ல; அது நிறுவன ரீதியான தேவையற்ற சொற்கள் நீக்கப்பட்டு, துல்லியமாக இருக்கும் மொழியைக் குறிக்கிறது.

உண்மையில் உதவும் கட்டமைப்பு

முறையற்ற ஒரு கையேடு (manual), கையேடு இல்லையிருப்பதை விட அதிக நேரத்தை வீணடிக்கும். உங்கள் ஆவணத்தை ஒரு விளிம்புநிலை வடிகட்டி (funnel) போலக் கருதுங்கள். அதன் உச்சியில், அந்தத் திட்டம் என்ன செய்கிறது மற்றும் யார் அதைப் பயன்படுத்த வேண்டும் என்பதை விளக்கும் ஒரு சிறிய மேலோட்டத்தை (overview) வைக்கவும். அதைத் தொடர்ந்து, வாசகரின் உள்ளூர் அமைப்பைப் (local setup) பற்றி எதையும் எதிர்பார்க்காமல், நிறுவல் வழிமுறைகளை (installation instructions) வழங்கவும். பின்னர், தொடக்கத்திலிருந்து இறுதி வரை முழுமையான, யதார்த்தமான சூழல்களை விளக்கும் பயிற்சிகளை (tutorials) சேர்க்கவும். அடுத்து API குறிப்புகள் (API references) வர வேண்டும். இவை விரிவானதாகவும், ஆனால் எளிதில் ஸ்கேன் செய்யக்கூடியதாகவும் இருக்க வேண்டும்; அகரவரிசைப்படி கொட்டுவதற்குப் பதிலாக, resource அல்லது function அடிப்படையில் குழுவாக்கப்பட வேண்டும். இறுதியாக, குறிப்பிட்ட சிக்கல்களைக் கையாளும் troubleshooting வழிகாட்டிகளை வைக்கவும். "Connection refused" என்ற செய்தியைப் பெறும் பயனருக்கு, "Permission denied" என்று காண்பதைக் காண்பவருக்குத் தேவையான பதில் வேறாக இருக்கும். பிழைகளைச் செய்தியின் அடிப்படையில் அல்லது சூழலின் அடிப்படையில் குழுவாக்கவும், பொதுவான வகைகளின் அடிப்படையில் அல்ல.

பட்டியல்கள் (Lists) மற்றும் code blocks ஆகியவை அடர்த்தியான உரையை உடைத்து, வாசகர்கள் தங்களுக்குத் தேவையான சரியான கட்டளையைத் தேடி எடுக்க உதவுகின்றன. சரியாகப் பயன்படுத்தப்பட்ட ஒரு bullet list, குழப்பமான ஒரு பத்தியைத் தொடர்ச்சியான செயல்களாக மாற்றும்.

வெறும் விளக்கமாக மட்டும் இல்லாமல், செய்து காட்டுங்கள்

அருவமான விளக்கங்கள் (Abstract explanations) பயனர்களைக் குழப்பமடையச் செய்யும். ஒரு கருவியை எவ்வாறு कॉन्ஃபிகர் செய்வது என்று விவரித்தால், அதன் துல்லியமான கோப்பு உள்ளடக்கங்களைக் (file contents) காட்டுங்கள். நிறுவல், தொடக்கம் (initialization) மற்றும் பொதுவான कॉन्ஃபிகரேஷன்களுக்கான code snippets-களை வழங்கவும். மாதிரி உள்ளீடுகள் (sample inputs) மற்றும் எதிர்பார்க்கப்படும் வெளியீடுகளை (expected outputs) அருகருகே காட்டுங்கள். உங்கள் API JSON-ஐத் திருப்பிக் கொடுத்தால், அந்த JSON-ஐயே காட்டுங்கள். ஒரு CLI கருவி அட்டவணை வடிவ வெளியீட்டைத் (tabular output) தந்தால், அந்த அட்டவணையைத் காட்டுங்கள். ஒரு பணிப்பாய்வு (workflow) பற்றிய விளக்கம், ஒரு செயல்முறை விளக்கத்திற்கு (demonstration) இணையானது என்று ஒருபோதும் நம்பாதீர்கள்.

மிக முக்கியமாக, நீங்கள் வெளியிடுவதற்கு முன் ஒவ்வொரு உதாரணத்தையும் ஒரு சுத்தமான சூழலில் (clean environment) சோதித்துப் பாருங்கள். உங்கள் சொந்தச் சிறு குறியீட்டை ஒரு புதிய container அல்லது virtual machine-இல் நகலெடுத்துச் சோதிக்கவும். ஒரு dependency-யைக் குறிப்பிட மறந்துவிட்டதால் அது தோல்வியடைந்தால், நீங்கள் பல சிக்கல்களில் இருந்து உங்களைக் காப்பாற்றிக் கொண்டீர்கள் என்று அர்த்தம். தொழில்நுட்ப எழுத்தில் உறுதியான உதாரணங்கள் மிகச்சிறந்த பலனைத் தருகின்றன, ஏனெனில் அவை நிச்சயமற்ற தன்மையைச் செயலாக மாற்றுகின்றன.

அதை உயிர்ப்புடன் வைத்திருங்கள்

குறியீட்டை விட ஆவணங்கள் மிக வேகமாகப் பழையதாகிவிடுகின்றன. ஒரு method signature மாறுகிறது, ஒரு default port மாறுகிறது, ஒரு dependency மாற்றப்படுகிறது, திடீரென்று உங்கள் வழிமுறைகள் ஒரு முட்டுச்சந்தையை நோக்கி உங்களை அழைத்துச் செல்கின்றன...