প্রযুক্তিগত ডকুমেন্টেশন এমন কোনো গৌণ কাজ নয় যা কোড কম্পাইল হওয়ার পর শেষ করতে হয়। এটি প্রতিটি সফটওয়্যার প্রজেক্টের কেন্দ্রে থাকে, যা নির্ধারণ করে যে একজন নতুন ডেভেলপার তার প্রথম দিনেই কোনো বাগ (bug) ঠিক করতে পারবেন কি না, অথবা একজন ব্যবহারকারী বিভ্রান্ত হয়ে পাঁচ মিনিটের মধ্যেই আপনার পণ্যটি ব্যবহার করা ছেড়ে দেবেন কি না। ভালো ডকুমেন্টেশন ব্যবহারকারীদের প্রকৃত কাজ সম্পন্ন করতে সাহায্য করে। এটি ভবিষ্যৎ মেইনটেইনারদের বুঝতে সাহায্য করে যে একটি মডিউল কেন তৈরি করা হয়েছে এবং সবকিছু ভেঙে না ফেলে কীভাবে এটি পরিবর্তন করা যায়। তবুও অনেক টিম ডকুমেন্টেশনকে একটি afterthought বা afterthought হিসেবে দেখে—হয় তা তাড়াহুড়ো করে তৈরি করা একটি README, অথবা একটি উইকি পেজ যা অযত্নে পড়ে থাকে। প্রকৃতপক্ষে কার্যকর ডকুমেন্টেশন লেখা একটি দক্ষতা যা আপনি সচেতনভাবে উন্নত করতে পারেন।
লেখার আগে আপনার পাঠককে জানুন
একটি শিরোনাম টাইপ করার আগেই সিদ্ধান্ত নিন কে এটি পড়ছে। একজন ডাটাবেস অ্যাডমিনিস্ট্রেটর যিনি কানেকশন পুল সেটিংস খুঁজছেন, তার সাথে একজন ফ্রন্ট-এন্ড ডেভেলপারের কোনো মিল নেই যিনি React component props খুঁজছেন। এন্ড-ইউজারদের জন্য নম্বরযুক্ত ধাপ এবং স্ক্রিনশট প্রয়োজন, আর্কিটেকচার ডায়াগ্রাম নয়। তারা জানতে চায় কীভাবে একটি PDF এক্সপোর্ট করতে হয়, রেন্ডারিং পাইপলাইন কীভাবে কাজ করে তা নয়। আপনার লাইব্রেরি ইন্টিগ্রেট করা ডেভেলপারদের জন্য সঠিক ফাংশন সিগনেচার, এরর কোড এবং কপি-পেস্ট করার মতো স্নিপেট প্রয়োজন। সিস্টেম অ্যাডমিনিস্ট্রেটরদের ইনস্টলেশন প্রি-রিকুইজিট, এনভায়রনমেন্ট ভেরিয়েবল এবং ট্রাবলশুটিং ফ্লো প্রয়োজন যা সবচেয়ে সাধারণ ব্যর্থতাগুলো দিয়ে শুরু হয়।
আপনি যদি একটি বিশাল টেক্সটের মাধ্যমে এই তিন গ্রুপের সবাইকে সেবা দেওয়ার চেষ্টা করেন, তবে সবাই ক্ষতিগ্রস্ত হবে। আলাদা আলাদা পথ তৈরি করুন। এমনকি একটি মাত্র পেজকেও "অপারেটরদের জন্য" এবং "ক্লায়েন্ট ডেভেলপারদের জন্য"—এই ধরনের স্পষ্ট শিরোনাম দিয়ে সুবিন্যস্ত করা যেতে পারে। লক্ষ্য হলো, "এই অনুচ্ছেদটি কি আমার জন্য?"—এই ধরনের মানসিক দ্বিধা দূর করা।
অপ্রয়োজনীয় অংশ বাদ দিন
স্পষ্টতা চাতুর্যের চেয়ে অনেক বেশি কার্যকর। ছোট বাক্য ব্যবহার করুন। কর্তৃবাচ্য (active voice) ব্যবহার করুন। "The database should be initialized by the user"-এর চেয়ে "Initialize the database" অনেক বেশি স্পষ্ট। যখন আপনাকে "idempotency" বা "serialization"-এর মতো কোনো প্রযুক্তিগত শব্দ ব্যবহার করতে হবে, তখন সেটি ইনলাইনভাবে সংজ্ঞায়িত করুন বা একটি গ্লসারির লিঙ্ক দিন। পূর্বজ্ঞান আছে এমন ধারণা নিয়ে কাজ করবেন না।
একটি ব্যবহারিক পরীক্ষা: আপনার অনুচ্ছেদটি জোরে পড়ার চেষ্টা করুন। যদি আপনার দম ফুরিয়ে আসে, তবে বুঝতে হবে বাক্যটি অনেক লম্বা। আরেকটি পরীক্ষা: অলঙ্কৃত ভার্বের পরিবর্তে সহজ ভার্ব ব্যবহার করুন। যদি "utilize the API"-এর পরিবর্তে অর্থ না হারিয়ে "use the API" লেখা যায়, তবে সেটিই করুন। সহজ ভাষার অর্থ এই নয় যে তা বুদ্ধিবৃত্তিক হবে না; এর অর্থ হলো কর্পোরেট প্যাডিং মুক্ত সুনির্দিষ্ট ভাষা।
এমন কাঠামো যা প্রকৃতপক্ষে সাহায্য করে
একটি অগোছালো ম্যানুয়াল কোনো ম্যানুয়াল না থাকার চেয়েও বেশি সময় নষ্ট করে। আপনার ডকুমেন্টেশনকে একটি ফানেল হিসেবে ভাবুন। সবার উপরে একটি সংক্ষিপ্ত ওভারভিউ রাখুন যা ব্যাখ্যা করে প্রজেক্টটি কী করে এবং কাদের এটি দেখা উচিত। এরপর ইনস্টলেশন নির্দেশাবলী দিন যেখানে পাঠকের লোকাল সেটআপ সম্পর্কে কোনো পূর্বধারণা রাখা হবে না। তারপর টিউটোরিয়াল যোগ করুন যা শুরু থেকে শেষ পর্যন্ত সম্পূর্ণ এবং বাস্তবসম্মত পরিস্থিতি নিয়ে কাজ করে। এরপর আসবে API রেফারেন্স। এগুলো বিস্তারিত হওয়া উচিত কিন্তু সহজে স্ক্যানযোগ্য হতে হবে; এগুলো বর্ণানুক্রমিক অর্ডারে না রেখে রিসোর্স বা ফাংশন অনুযায়ী গ্রুপ করা উচিত। সবশেষে, নির্দিষ্ট সমস্যা সমাধানের জন্য ট্রাবলশুটিং গাইড রাখুন। একজন ব্যবহারকারী যিনি "Connection refused" মেসেজ পাচ্ছেন, তার উত্তর একজন "Permission denied" দেখা ব্যবহারকারীর চেয়ে আলাদা হওয়া প্রয়োজন। এররগুলোকে মেসেজ বা প্রেক্ষাপট অনুযায়ী গ্রুপ করুন, বিমূর্ত ক্যাটাগরি অনুযায়ী নয়।
লিস্ট এবং কোড ব্লকগুলো ঘন টেক্সটকে ভেঙে দেয় এবং পাঠকদের তাদের প্রয়োজনীয় কমান্ডটি দ্রুত খুঁজে পেতে সাহায্য করে। একটি সঠিক স্থানে বসানো বুলেট লিস্ট বিভ্রান্তিকর অনুচ্ছেদকে কাজের একটি ধারাবাহিকতায় রূপান্তর করতে পারে।
শুধু বর্ণনা নয়, উদাহরণ দিয়ে দেখান
বিমূর্ত ব্যাখ্যা ব্যবহারকারীদের হতাশ করে। আপনি যদি কোনো টুল কনফিগার করার পদ্ধতি বর্ণনা করেন, তবে ফাইলের সঠিক বিষয়বস্তু দেখান। ইনস্টলেশন, ইনিশিয়ালাইজেশন এবং সাধারণ কনফিগারেশনের জন্য কোড স্নিপেট প্রদান করুন। ইনপুট এবং প্রত্যাশিত আউটপুট পাশাপাশি দেখান। আপনার API যদি JSON রিটার্ন করে, তবে JSON দেখান। যদি একটি CLI টুল টেবুলার আউটপুট দেয়, তবে টেবিলটি দেখান। কোনো কাজের প্রবাহের বর্ণনা দেওয়া মানেই সেটি ডেমোনস্ট্রেশনের সমতুল্য—এমনটি কখনোই ধরে নেবেন না।
সবচেয়ে গুরুত্বপূর্ণ বিষয় হলো, প্রকাশ করার আগে একটি ক্লিন এনভায়রনমেন্টে প্রতিটি উদাহরণ পরীক্ষা করে দেখুন। আপনার নিজস্ব স্নিপেটটি একটি নতুন কন্টেইনার বা ভার্চুয়াল মেশিনে চালিয়ে দেখুন। যদি কোনো ডিপেন্ডেন্সি উল্লেখ করতে ভুলে যাওয়ার কারণে এটি ব্যর্থ হয়, তবে আপনি নিজেকে অসংখ্য সমস্যার হাত থেকে বাঁচিয়ে ফেললেন। টেকনিক্যাল রাইটিংয়ে বাস্তব উদাহরণ সবচেয়ে বেশি রিটার্ন অন ইনভেস্টমেন্ট প্রদান করে কারণ এগুলো অনিশ্চয়তাকে কাজে রূপান্তরিত করে।
একে সচল রাখুন
কোডের চেয়ে ডকুমেন্টেশন দ্রুত পুরনো বা অচল হয়ে পড়ে। একটি মেথড সিগনেচার পরিবর্তিত হয়, একটি ডিফল্ট পোর্ট বদলে যায়, একটি ডিপেন্ডেন্সি প্রতিস্থাপিত হয় এবং হঠাৎ করেই আপনার নির্দেশাবলী একটি ডেড এন্ডে গিয়ে পৌঁছায়।