ইঞ্জিনিয়ার-লেখক ডক্সে সাধারণ ভুল এবং সেগুলি কীভাবে ঠিক করা যায়

গত ছয় মাসে, আমাদের ডেভেলপমেন্ট টিম "ডক্স-অ্যাস-কোড" পদ্ধতি গ্রহণ করেছে (আপনি এখানে আমাদের যাত্রা সম্পর্কে আরও জানতে পারেন নিবন্ধ ) কারিগরি বিভাগ থেকে আমার সহকর্মীদের দ্বারা তৈরি ডকুমেন্টেশন নিয়মিত পর্যালোচনা করে, আমি প্রযুক্তিগত ডকুমেন্টেশন লেখার ক্ষেত্রে পাওয়া সবচেয়ে সাধারণ সমস্যাগুলির একটি তালিকা সংকলন করেছি।

নিবন্ধে, আমি আপনাকে দেখাব কিভাবে "ডক্স-এ-কোড" পদ্ধতির সরঞ্জামগুলি ব্যবহার করে এই সমস্যাগুলি সমাধান করা যায়৷

সমস্যা 1. "ডক্স লেখা আমাদের দায়িত্বের অধীনে নয়"

অ্যাড-হক ভিত্তিতে ডকুমেন্টেশন নিয়ে কাজ করা পুরো ডেভেলপমেন্ট দলের জন্য নিজের পায়ে গুলি করার মতো। যদি দলটির ক্ষমতার অভাব থাকে তবে ডকুমেন্টেশন রক্ষণাবেক্ষণকে আরও প্রযুক্তি-চালিত এবং অনুমানযোগ্য করার জন্য এটি একটি বাধ্যতামূলক কারণ।

ঠিক করুন:

• ডকুমেন্টেশনের বিকাশের জন্য "ডক্স-এ-কোড" পদ্ধতিকে একীভূত করুন। এইভাবে, আপনি প্রযুক্তিগত ঋণ সঞ্চয় করার ঝুঁকি ছাড়াই কোডবেসের পাশাপাশি ডকুমেন্টেশনটি পুনরাবৃত্তিমূলকভাবে আপডেট করতে পারেন।
• একটি স্থান বা একটি প্ল্যাটফর্ম বিকাশ বা সংহত করুন যা প্রযুক্তি ডক্স রেন্ডার করতে পারে এবং তথ্যের একক উত্স হিসাবে পরিবেশন করতে পারে।
• একটি সমন্বিত উন্নয়ন পরিবেশ (IDE) ব্যবহার করুন। একটি IDE আপনাকে প্লাগইনগুলি অন্তর্ভুক্ত করতে এবং ডকুমেন্টেশন বিকাশের জন্য কাস্টম স্ক্রিপ্ট তৈরি করতে সক্ষম করে। ধারণা ডক্স লেখার জন্য একটি চমৎকার হাতিয়ার, তবে অ্যাপ্লিকেশনগুলির মধ্যে আপনার পছন্দসই থাকতে পারে।
• বানান-চেক প্লাগইন ইনস্টল করুন টাইপো থেকে রক্ষা করতে। আপনার IDE-তে প্লাগইন যোগ করা একটি দ্রুত এবং সহজ প্রক্রিয়া।
• আপনার কোম্পানির দ্বারা বিশেষভাবে তৈরি করা অভ্যন্তরীণ নির্দেশিকাগুলি গ্রহণ করুন, প্রযুক্তিগত লেখা সম্প্রদায়ের (যদি আপনার কাছে থাকে) থেকে অন্তর্দৃষ্টি গ্রহণ করে, কোম্পানির মধ্যে ডকুমেন্টেশন বিকাশের জন্য একটি প্রমিত পদ্ধতি স্থাপন করুন। এই নির্দেশিকাগুলি অনুসরণ করা ডকুমেন্টেশন প্রক্রিয়াকে স্ট্রিমলাইন করবে, কী এবং কীভাবে সঠিকভাবে লিখতে হবে তা চিন্তা করার সময় সাশ্রয় করবে।
• দস্তাবেজ পর্যালোচনার সময় উল্লেখযোগ্যভাবে কমাতে বা বাদ দিতে নির্দেশিকাগুলির উপর ভিত্তি করে স্বয়ংক্রিয় পরীক্ষাগুলি।
• সম্ভাব্য সবকিছু টেমপ্লেট করুন এবং ডকুমেন্টেশন উপাদানের মানসম্মত করার বিষয়ে দলের সাথে একমত হন।

আমি মূল্যবান সম্পদ অফার করব যা প্রযুক্তিগত ডকুমেন্টেশনের সাথে কাজ করার সময় আপনার আত্মবিশ্বাসকে বাড়িয়ে তুলবে। আমি বিশ্বাস করি যে এই সংস্থানগুলি আপনাকে প্রযুক্তিগত ডক্সগুলি কার্যকরভাবে পরিচালনা করার জন্য সজ্জিত করার জন্য যথেষ্ট বিস্তৃত:

• দ্য " গুগল ডেভেলপার ডকুমেন্টেশন স্টাইল গাইড " ডেভেলপার ডকুমেন্টেশনের জন্য একটি ব্যাপক হ্যান্ডবুক হিসাবে কাজ করে৷ এটি বিন্যাস, বিরাম চিহ্ন, তালিকাকরণ এবং কোড ব্লকগুলি যুক্ত করার বিষয়ে আপনার যা জানা দরকার তা কভার করে৷ এই নির্দেশিকাটি যথেষ্ট এবং আমাদের অভ্যন্তরীণ নির্দেশিকাগুলি বিকাশের জন্য একটি মূল্যবান রেফারেন্স হয়েছে, যেখান থেকে আমরা কিছু ধার নিয়েছি সেরা অনুশীলন.
• " বিকাশকারীদের জন্য ডক্স " ডেভেলপার ডকুমেন্টেশনের সাথে কাজ করার সাথে জড়িত যে কেউ এটির বিকাশ, লেখা বা রক্ষণাবেক্ষণের সাথে জড়িতদের জন্য একটি অবশ্যই পাঠযোগ্য বই৷ বইটিতে প্রযুক্তিগত লেখার ক্ষেত্রে বেশ কিছু স্বনামধন্য এবং সম্মানিত লেখক রয়েছে৷

• " ডক্স লাইক কোড "অ্যান জেন্টেল, একজন প্রযুক্তিগত লেখক, একটি ব্যবহারিক গাইড যা OpenStack-এ ডকুমেন্টেশন সংস্কৃতি প্রদর্শন করে। বাস্তব উদাহরণের মাধ্যমে, লেখক ব্যাখ্যা করেন কেন ডকুমেন্টেশন GitHub-এ পরিচালনা করা উচিত এবং কীভাবে কার্যকর ডকুমেন্টেশনের জন্য প্রযুক্তিগত প্রক্রিয়াগুলি বাস্তবায়ন করা যায়। বইটি মূল্যবানও অফার করে। পেশাদার ডকুমেন্টেশন লেখার অন্তর্দৃষ্টি, আপনি একজন বিকাশকারী বা প্রযুক্তিগত লেখক যাই হোক না কেন।

• আমি প্রযুক্তিগত ডকুমেন্টেশন লেখার জন্য অভ্যন্তরীণ নির্দেশিকাও উল্লেখ করব, যাতে টেমপ্লেট এবং ফর্ম্যাটিং নিয়ম অন্তর্ভুক্ত করা উচিত। এই ধরনের নির্দেশিকা প্রতিটি কোম্পানিতে বিদ্যমান। সাধারণত, তারা প্রযুক্তিগত লেখক-অগ্রগামী এবং ডেভ ডকস চ্যাম্পিয়নদের সাথে যৌথভাবে বিকশিত হয় এবং দলের মধ্যে ডকুমেন্টেশন সংস্কৃতি বৃদ্ধির সাথে সাথে বিকশিত হয়।

ইস্যু 2. একাকী ডকুমেন্টেশন লেখা

সম্পূর্ণ ডকুমেন্টেশন একা ডেভেলপ করা এবং তারপর পর্যালোচনার জন্য জমা দেওয়া অপ্রয়োজনীয় বা অপ্রাসঙ্গিক ডকুমেন্টেশন তৈরি করার ঝুঁকি বহন করে যা উদ্দেশ্যমূলক উদ্দেশ্যের সাথে সারিবদ্ধ নাও হতে পারে।

ঠিক করুন:

• সর্বদা একটি রূপরেখা দিয়ে শুরু করুন এবং এটি আপনার টিম লিড, পণ্যের মালিক, প্রযুক্তিগত লেখক, বা তাদের বিশেষজ্ঞ মতামত প্রদান করতে ইচ্ছুক যেকোনো সহকর্মীর সাথে শেয়ার করুন।
• ধাপে ধাপে লিখুন এবং একই উপরে উল্লিখিত সহকর্মীদের পর্যালোচনার জন্য পুল অনুরোধ বরাদ্দ করুন।
• ফিডব্যাক সংগ্রহ করুন এবং কাজ করুন।
• মন্তব্য বিবেচনা করুন. এবং ভয়েসের পর্যালোচনা স্বরে এটিকে সহজভাবে নিন, কখনও কখনও এটি কঠোর হতে পারে, তবে এটি পর্যালোচনা প্রক্রিয়ার একটি বিশেষত্ব মাত্র।
• ডকুমেন্টেশন প্রবাহ উপেক্ষা করবেন না. নীচে আমাদের কোম্পানিতে গৃহীত সাধারণ প্রবাহ রয়েছে, তবে এই প্রবাহের বৈশিষ্ট্যগুলি একটি উন্নয়ন দলের পাশাপাশি কোম্পানির উপর নির্ভর করতে পারে:

সমস্যা 3. "যাদের বুঝতে হবে তারা বুঝতে পারবে"

সময়ে সময়ে আমি দলগুলির কাছ থেকে শুনি: "আমি উন্নয়ন দলের জন্য লিখছি," "যাদের বুঝতে হবে," "এটি ঐতিহাসিকভাবে আমাদের দলের মধ্যে এভাবেই বিকশিত হয়েছে"।

কিন্তু পেশাদার শব্দগুচ্ছ এবং অ্যাংলিসিজমের উপযুক্ততা এবং ধারাবাহিকতা প্রয়োজন। তাদের অত্যধিক ব্যবহার একটি পাগল প্রকৌশলী নোট অনুরূপ ডকুমেন্টেশন হতে পারে.

ডকুমেন্টেশনের জন্য, সম্ভাব্য সহজতম শব্দ এবং কাঠামো ব্যবহার করুন। প্রধান নীতিগুলির মধ্যে একটি হল স্ক্রল করার জন্য লেখা। ডকুমেন্টেশন লেখার জন্য চ্যালেঞ্জিং হতে পারে কারণ এটি প্রায়শই বিস্তৃত হয়, কিন্তু পাঠকরা খুব কমই কভার থেকে কভারে যায়। পরিবর্তে, তারা স্ক্রোল বা কীওয়ার্ড অনুসন্ধান ব্যবহার করার প্রবণতা রাখে। তাই যেকোনো অংশ থেকে খোলার সময় লেখাটি সহজে বোধগম্য হওয়া উচিত।

ঠিক করুন:

• অভিধান এবং বর্তমান নিয়মগুলি ব্যবহার করে ইংরেজি পদ এবং পেশাদার পরিভাষা পরীক্ষা করুন (বা কেবল সেগুলি গুগল করুন)। অভিধানে একটি শব্দ বিদ্যমান থাকলে, আপনার ভাষার অর্থোগ্রাফির নিয়ম অনুযায়ী লিখুন।
• যদি শব্দটি ভাষাতে না থাকে, তাহলে এটি মূল ভাষায় লিখুন এবং বন্ধনীতে আপনার ভাষায় একটি অনুবাদ প্রদান করুন।
• শব্দকোষ বিভাগে শব্দ যোগ করুন, এবং সংক্ষিপ্ত রূপ এবং সংক্ষিপ্ত শব্দের তালিকায় সংক্ষিপ্ত রূপ। এটি "মালিকানা" সংক্ষেপণের জন্য বিশেষভাবে গুরুত্বপূর্ণ (পিও সম্পর্কে যতই উল্লেখ করা বা লেখা হোক না কেন, ডকুমেন্টেশন পড়ার সময় এর অর্থ এখনও সাধারণ প্রশ্নগুলির মধ্যে একটি)।
• সামঞ্জস্যতা - সমস্ত ডকুমেন্টেশন জুড়ে নির্বাচিত লেখার শৈলী এবং সংক্ষিপ্ত রূপের সাথে লেগে থাকুন (আপনার কোম্পানিতে উপলব্ধ সমস্ত ডকুমেন্টেশনের জন্য ভাল)।
• নথি নেভিগেশন সাবধানে পরিকল্পনা. সম্পূর্ণ নথিটি না পড়েই প্রাসঙ্গিক বিভাগটি খুঁজে বের করার একটি দ্রুত উপায় হওয়া উচিত। অতএব, পরিষ্কার এবং সংক্ষিপ্ত শিরোনামগুলির সাথে বিষয়বস্তুকে ভেবেচিন্তে গঠন করা অপরিহার্য। অভ্যন্তরীণ ডকুমেন্টেশন টেমপ্লেটগুলি সরলতা এবং সুবিধার জন্য তৈরি করা উচিত।

ইস্যু 4. একাধিক জায়গায় একই সাথে ডকুমেন্টেশন লেখা

ডকুমেন্টেশনের জন্য, সত্যের একটি একক উত্স থাকা - এমন একটি স্থান যেখানে আপনি প্রয়োজনীয় তথ্য খুঁজে পেতে পারেন তার নির্ভুলতা সম্পর্কে চিন্তা না করেই গুরুত্বপূর্ণ। আমাদের প্রযুক্তিগত ডকুমেন্টেশনের জন্য, একটি অভ্যন্তরীণ উন্নত প্ল্যাটফর্ম যেমন একটি স্থান হিসাবে কাজ করে। পুরানো তথ্য দিয়ে কাউকে বিভ্রান্ত করা রোধ করতে বিভিন্ন স্থানে ডকুমেন্টেশনের খণ্ডন এড়ানো অপরিহার্য।

ঠিক করুন:

• প্রযুক্তিগত ডকুমেন্টেশন কোথাও প্রকাশ করার আগে, নিশ্চিত করুন যে এটি অন্য কোথাও বিদ্যমান নেই, যদি এটি আসে যে কোম্পানি জ্ঞান ভাগ করার জন্য বিভিন্ন স্থান ব্যবহার করে।
• আর্কাইভ বা মুছে দিন (যদি আপনার মালিকানা থাকে) পুরানো প্রযুক্তিগত ডকুমেন্টেশন। আপনি যদি অকাল মুছে ফেলার বিষয়ে উদ্বিগ্ন হন (উদাহরণস্বরূপ, পৃষ্ঠাটির বাহ্যিক লিঙ্কের কারণে), একটি কলআউট যোগ করুন যে পৃষ্ঠাটি পুরানো হয়েছে, এবং বৈধ নথির বর্তমান ডকুমেন্টেশন অবস্থান, যেখানে আরও আপডেট করা উচিত।
• আপনি যদি মূল্যবান তথ্য বা অন্তর্দৃষ্টি জুড়ে আসেন, সেগুলি ডকুমেন্টেশনে যোগ করুন। স্ল্যাক বা অন্য কোথাও, বিশেষ করে ব্যক্তিগত চ্যাটে এটি ছেড়ে দেবেন না। শেয়ার করার মত জ্ঞান!

আনা গনচারোভা পোস্ট করেছেন