ডকুমেন্টেশন হ্রাস - কিভাবে এটি মোকাবেলা?

Question

গুরুত্বপূর্ণ : উত্স কোড ডকুমেন্টেশন সহ আমাদের কাছে কোনও সমস্যা নেই । এটি নিয়মিত কোড অডিট এর অন্তর্গত এবং এটি টু ডেট রাখে। আমাদের সমস্যাটি বিকাশকারীদের ডকুমেন্টেশন (বা "যদি আপনি পছন্দ করেন" বাহ্যিক) সাথে থাকে তবে প্রোগ্রামার থেকে প্রোগ্রামারদের কাছে ব্লগের মতো ছোট টিপস যা একবার লেখার প্রবণতা থাকে, প্রায়শই পিছনে ফেলে যায়।

---

প্রোগ্রামার ডকুমেন্টেশন তৈরি করতে আমরা উইকির মতো সিস্টেম ব্যবহার করি - প্রোগ্রামারদের জন্য প্রোগ্রামারদের দ্বারা লেখা নিবন্ধগুলি আরও নির্দিষ্টভাবে কোডের কীভাবে কাজ করে সে সম্পর্কে আরও বিশদে বর্ণনা করে। সেই উইকি-পৃষ্ঠাগুলিতে সাধারণত অন্তর্ভুক্ত থাকে:

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

সাধারণভাবে, প্রাথমিকভাবে রাইটিং কোড সম্পর্কিত এমন জিনিস যা এর আকার এবং ব্লগ পোস্ট / নিবন্ধের মতো প্রকৃতির কারণে নিয়মিত কোড-ডকুমেন্টেশন ফিট করে না।

সমস্যাটি

যতদূর এই সিস্টেমটি প্রবর্তন করা কয়েক মাস আগে একটি ভাল ধারণা বলে মনে হয়েছিল, আজকাল আমার মনে হচ্ছে এটি সমাধান হওয়ার চেয়ে আরও সমস্যার সৃষ্টি করছে। উদাহরণ স্বরূপ:

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

স্বাভাবিক অবক্ষয়। কোড পরিবর্তন হয়েছে, উইকি একই থাকে। পরের বার যখন কেউ তথ্য অনুসন্ধান করবে, সে সাধারণত যা খুঁজে পায় তা হ'ল পুরানো, নিম্নমানের স্টাফগুলির গোছা - এবং ভাবছে যে কী ঘটছে, তার যে জিনিসগুলি পাওয়া গেছে সেগুলি সঠিক কিনা বা (আরও খারাপ) এর কোন অংশগুলি। এবং যা সাহায্য করার কথা ছিল, তার বিপরীত কাজ শেষ করে।

এই মুহুর্তে মনে হচ্ছে লোকেদের সমস্যা সম্পর্কে সচেতন, প্রকল্পের সীসা অন্তর্ভুক্ত রয়েছে, তবে স্পষ্টতই কেউ এর সাথে কিছু করার (বা আরও মজাদার জিনিস আছে) বিরক্ত করেন বলে মনে হয় না।

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

Comments

আমরা আমাদের বিয়ার মিটিংয়ের পরে প্রতিটি "উত্পাদনশীলতা" শুক্রবার আমাদের বাহ্যিক ডকুমেন্টেশন আপডেট করি (বিকেল 3 টার দিকে ছোঁড়া পর্যন্ত) এটি বেশ ভাল কাজ করে।

— লুকারবেলো

এই তথ্যটি কি কেবল আপনার সংস্থার ইন্ট্রানেটের কর্মচারীদের জন্য, বা তৃতীয় পক্ষের দেবগণ যারা আপনার এপিআইগুলিও ব্যবহার করেন তাদের জন্য উপলব্ধ?

— জেমস

@ জেমস: খালি বাড়ি বিকাশকারীদের জন্য। এগুলি সবই হারমেটিক, আসলে এই বিষয়টিতে যে অন্য দলগুলির কেউই এই তথ্য ব্যবহার করতে পারে না। কঠোরভাবে প্রকল্প / দলবদ্ধ-

— কিমি

Answer 1

দেখে মনে হচ্ছে আপনি উইকিতে খুব বেশি ট্রিভিয়ার ডকুমেন্ট করছেন।

কোডে কোড এবং পদ্ধতিগুলির ডকুমেন্ট ব্লক । আপনার কোডটি স্ব-ডকুমেন্টিং করার চেষ্টা করুন যাতে আপনাকে প্রচুর মন্তব্য করতে হবে না। লেখার ইউনিট পরীক্ষাগুলিও সহায়তা করতে পারে।

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

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

স্ক্রিপ্ট বা ইনস্টলেশন ফাইলে তাদের স্বয়ংক্রিয় করে ডকুমেন্ট পদ্ধতি । অন্যথায় এগুলি উইকে রাখুন, তবে প্রতিবার কেউ যখন উইকির কাছ থেকে কোনও পদ্ধতি ব্যবহার করেন, তাদের নিবন্ধটি উন্নত করতে বা প্রক্রিয়াটির অংশগুলি স্বয়ংক্রিয় করার চেষ্টা করতে বলুন।

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

Answer 2

ডকুমেন্টেশনটিকে একটি বিতরণযোগ্য হিসাবে গণ্য করা উচিত এবং এটি ট্রেসেবিলিটি এবং গ্রহণযোগ্যতার বিধিগুলির সাথে সাথে বিকাশের উপযুক্ত সময় দেওয়া উচিত।

লোকেরা যখন "প্রত্যাশী" সফ্টওয়্যার ডকুমেন্টেশন প্রদেয় হিসাবে দেখেন তখন তা অস্বাভাবিক নয় when

Answer 3

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

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

Comments

প্রাথমিক লেখালেখি কোনও সমস্যা নয়। যখন সেই দস্তাবেজটি ইতিমধ্যে উপস্থিত রয়েছে, এবং অন্য কেউ মূল মডিউল কোড পরিবর্তন করেন তিনি প্রায়শই বাহ্যিক ডক্স / উইকির আপডেট "ভুলে যান" (বা কখনও কখনও এমনকি সচেতন থাকেন না যে এই জিনিসটি বিদ্যমান রয়েছে)।

— কিমি

তারপরে তার সমাধানটি রোল-ব্যাক করে দেখানো হয়েছে যে

— টিকিটটি

এখানে অন্তর্নিহিত পয়েন্টটি গুরুত্বপূর্ণ - আপনার একটি ডকুমেন্টেশন চ্যাম্পিয়ন দরকার যারা দলকে একরকম মানক হিসাবে ধরে রাখছেন।

— মাইকেল

এটা ঠিক, এবং একটি বিষয় নিশ্চিত - দলের মধ্যে তার জীবন সহজ হবে না

— আন্দ্রেজ বোবাক

Answer 4

যদি কোনও কিছু দ্রুত পরিবর্তিত হয় তবে তা কোডের বাইরে রক্ষণাবেক্ষণ করা উচিত নয়।

API এর অংশগুলির জন্য নকশার সিদ্ধান্তের পিছনে অনুপ্রেরণা

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

স্বাভাবিক অবক্ষয়। কোড পরিবর্তন হয়েছে, উইকি একই থাকে।

এখানেই "এক্সিকিউটেবল ডকুমেন্টেশন" - ইউনিট পরীক্ষা - খুব দরকারী হয়ে ওঠে। যদি কোডটি পরিবর্তন হয় এবং পরীক্ষাগুলি এর সাথে পরিবর্তন না হয় তবে বিল্ডটি বিরতি। অবশ্যই ডকুমেন্টেশন হিসাবে পরীক্ষা লেখার ক্ষেত্রে কিছুটা দক্ষতা লাগে। তবে তাই বাহ্যিক ডকুমেন্টেশন লেখার (ভাল)।

Comments

+1, আমি মনে করি যে ডকুমেন্টেশনগুলি, যা দ্রুত পরিবর্তিত হয়, উত্স কোড থেকে বের করা উচিত। এটি বিকাশকারীর পক্ষে কম বেদনাদায়ক।

— লুকারবেলো

+1: শালীন সামগ্রিকভাবে পরামর্শ দেয় তবে দুর্ভাগ্যক্রমে আপনি ইউনিট পরীক্ষাগুলির সাথে আপনার সমস্ত "কোড সম্পর্কিত সমস্যাগুলি" কভার করতে পারবেন না (ইউআই দেব প্রধান উদাহরণ হিসাবে)। ইশ যদিও তাই হত!

— কিমি

@ জিমি: আপনি জিইউআই লেআউটের জন্য দরকারী ইউনিট পরীক্ষা লিখতে না পারলে আপনি অবশ্যই ব্যাক-এন্ড লজিকের ক্রিয়া এবং অনুরোধ পরীক্ষা করতে পারবেন

— ২১:০৮ এ পার্সিফল

যদি আমি কোড / মন্তব্যে "API এর অংশগুলির জন্য ডিজাইনের সিদ্ধান্তের পিছনে অনুপ্রেরণা" রাখি তবে আমার উত্স ফাইলগুলি বিস্ফোরিত হবে। পরিবর্তে, আমি অনেক বিস্তারিত এই ট্র্যাক ইস্যু যে ব্যক্তি অনুসরণ করে এবং শুধুমাত্র কোড মন্তব্য নিজ নিজ টিকেট পড়ুন

— মশা

Answer 5

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

এটিকে প্রক্রিয়ার অংশ হিসাবে যুক্ত করার আরেকটি উপায় - যেহেতু আপনি একটি চৌর্য মডেল ব্যবহার করছেন, পুনরাবৃত্তির জন্য পরিকল্পনার প্রক্রিয়ার অংশ, এটি উইকিতে পরিকল্পিত পরিবর্তনগুলি আপডেট করা হতে পারে। উইকিসিটি 'রিসোর্সগুলিতে এভাবে কাজ করা উচিত' হিসাবে কাজ করে।

Answer 6

আপনি যদি নেট ভাষা ব্যবহার করে থাকেন তবে ( স্যান্ডক্যাসল ) দেখুন যা XML ডকুমেন্টেশন নেয় (/// # সি #) এবং এটিকে এমএসডিএন সহায়তা ফর্ম্যাটে রূপান্তর করে।

বিন্যাসে বর্ণনা, মন্তব্য এবং কোডের নমুনাগুলি পাশাপাশি কিছু অন্যান্য বৈশিষ্ট্য অন্তর্ভুক্ত করার ক্ষমতা রয়েছে। আপনি .CHM, .HsX, .MSCH এবং HTML / ASP.NET ফর্ম্যাটে আউটপুট করতে পারেন। আসল প্রকল্পটি আপনার সমাধানটিতে যুক্ত হয় এবং বিল্ড সার্ভারে নির্মিত হয়। আমরা এটি করেছি এবং প্রতি রিলিজ একটি ওয়েব সাইটে স্থাপন করেছি এবং গ্রাহকরা এটি পছন্দ করেন কারণ ডকুমেন্টেশন প্রকাশের সাথে সম্পর্কিত, এবং ক্রমাগত আপডেট হয় updated

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

এটিই আমরা একমাত্র ডকুমেন্টেশন হিসাবে পরিণত হয়েছি, কারণ API ব্যবহারের প্রেরণাগুলি এবং তাত্পর্যগুলি ডকুমেন্টেশনের মন্তব্য বিভাগে অন্তর্ভুক্ত করা যেতে পারে। আমি যেখানে কাজ করি সেখানে প্রক্রিয়াটি ভালভাবে কাজ করে।

Answer 7

আমি দুটি ক্ষেত্রের উপর ফোকাস করব, 1) কোড। 2) নন-কোড নোট এবং ডকুমেন্ট।

1) কোড।

এটিকে স্ব-ডকুমেন্টেশন করার চেষ্টা করুন। অতীতে আমি দেখতে পেয়েছিলাম যে প্রায়শই পরামর্শ দেওয়া হয়েছিল তবে খুব কমই ভাল ব্যাখ্যা করা হয়েছিল, তাই ...

এই ধরণের সিউডো কোডের পরিবর্তে:

# Routine by mdd on 7/25/2012
# processes cars for sale
a=0
col = Car.all
Collection.loop |a|
 if a.stat = 'fs' then 
   a+= a.value    
   call easo 
  endif
end

এই জাতীয় দেখতে আরও কোড দেখাচ্ছে:

accumulating_potential_sale_revenue = 0
cars_to_check = Car.all
cars_to_check.loop |one_car|
  if one_car.sell_status == 'for_sale'
    accumulating_potential_sale_revenue+= one_car.sale_price
    call email_about_special_offer(car)
  endif
end

তথ্য 'কখন কী করেছিল' ট্র্যাক করতে উত্স নিয়ন্ত্রণ ব্যবহার করুন।

2) নন-কোড

এই তথ্য বজায় রাখতে একটি উইকি এবং মার্কডাউন ফর্ম্যাট ব্যবহার করুন। এটিকে কাজের অংশ করুন। এটি প্রচার করুন, এটি পোস্ট করুন এবং এটি ব্লগ করুন। পুরানো এবং নতুন স্টাফ পর্যালোচনা করতে একটি আদর্শ সাপ্তাহিক বা মাসিক সভা সেট আপ করুন। এটিকে একটি মন্ত্র তৈরি করুন যে যখন কেউ কিছু জিজ্ঞাসা করে উত্তর দেওয়া হয় ... সেই চিন্তার পাশাপাশি "পরের বার কেউ জিজ্ঞাসা করলে এটি কি উইকে থাকা উচিত?"