'ডকুমেন্টেশন' এর ঠিক কী রয়েছে?

Question

আমরা যখন কোনও সফ্টওয়্যার পণ্যটির জন্য 'ডকুমেন্টেশন' বলি, এতে কী অন্তর্ভুক্ত থাকে এবং এতে কী অন্তর্ভুক্ত করা উচিত নয়?

উদাহরণস্বরূপ, একটি সাম্প্রতিক প্রশ্ন জিজ্ঞাসা করা হয়েছে যদি মন্তব্যগুলি ডকুমেন্টেশন হিসাবে বিবেচিত হয়?

তবে অন্যান্য অনেকগুলি ক্ষেত্র রয়েছে যা এটির জন্যও একটি বৈধ প্রশ্ন, অন্যদের তুলনায় এটি আরও সুস্পষ্ট:

• ম্যানুয়ালগুলি (স্পষ্টতই)
• অব্যাহতি পত্র?
• টিউটোরিয়াল
• মন্তব্য
• অন্য কেউ?

কোথায় রেখা টানা হয়। উদাহরণস্বরূপ, যদি 'টিউটোরিয়াল' ডকুমেন্টেশন হয়, তবে কি 'ভিডিও টিউটোরিয়াল' ডকুমেন্টেশন, বা এটি অন্য কিছু?

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

---

_{প্রশ্নটি আমাদের সম্মেলনে সাম্প্রতিক গ্রাহকদের প্রতিক্রিয়া থেকে অনুপ্রাণিত করে যে আমাদের ডকটির আরও বেশি 'নমুনা' দরকার ছিল, যা আমাদের আগে যেমন করা উচিত ছিল তেমন বিবেচনা করা তেমন ভাল ছিল না।}

_{শ্রোতা: সফ্টওয়্যার বিকাশকারীরা আমাদের ডাটাবেস (গুলি), প্রোগ্রামিং ল্যাঙ্গুয়েজ এবং সম্পর্কিত সরঞ্জামাদি (যেমন অ্যাডমিন ক্লায়েন্টকে ডিবি বলে) ব্যবহার করে}

Comments

ডাউনোটে মন্তব্য সর্বদা প্রশংসা করা হয়। দুর্ভাগ্যক্রমে সংখ্যাগুলি কোথায় বোঝা গেছে বুঝতে বুঝতে অনেক গঠনমূলক সমালোচনা জোগায় না :)

— ড্যান ম্যাকগ্রা

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

— ইন্নিস

সম্পর্কিত: মন্তব্যগুলি কি ডকুমেন্টেশনের একটি ফর্ম

— ডায়নামিক

এই প্রশ্নটি কারও জন্য ভেন চিত্রটি আঁকতে চিৎকার করছে।

— ম্যাথট্যাক

Answer 1

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

লক্ষ্যটিকে সামনে রেখে (সফ্টওয়্যারটি ব্যাখ্যা করে), গ্রাহক ব্যাখ্যায় সন্তুষ্ট হলে ডকুমেন্টেশন শেষ হয় : ঠিক যেমনভাবে গ্রাহক সফ্টওয়্যার দ্বারা সন্তুষ্ট হয়ে সফ্টওয়্যারটি সমাপ্ত হয়। মনে রাখবেন যে ডকুমেন্টেশনের জন্য গ্রাহক সফ্টওয়্যারটির জন্য প্রদেয় গ্রাহক হিসাবে সর্বদা এক রকম নন: সফটওয়্যারটি কীভাবে কাজ করে এবং কীভাবে এটি কাজ করে সে সম্পর্কে সহায়তা কর্মী, পরীক্ষকগণ, বিক্রয়কর্মী এবং অন্য সকলের কিছুটা বোঝার প্রয়োজন হবে।

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

Comments

আমি কেবল কোর্সের সামগ্রীগুলি নথিভুক্ত হিসাবে বিবেচনা করব যদি সেগুলি একই দল (বিস্তৃত অর্থে) সফ্টওয়্যার দ্বারা উত্পাদিত হিসাবে উত্পাদিত / বিতরণ করা হয়। সম্পূর্ণ তৃতীয় পক্ষের পাঠ্যক্রমগুলি ডক্স নয়।

— ডোনাল ফেলো

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

Answer 2

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

আপনি যে সমস্যার সমাধান করেছেন তা হ'ল আপনি যে গ্রাহকের প্রয়োজনীয়তা অনুমান করেছিলেন এবং তারা আপনাকে কী সরবরাহ করার প্রত্যাশা করেছিল তার মধ্যে আপনার সংযোগ বিচ্ছিন্ন হয়ে পড়েছিল শেষে আপনি "আরে যেখানে সমস্ত নমুনা আছেন" অবাক করে দিয়েছিলেন।

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

কিছু বিষয় যা খেলতে আসবে:

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

Comments

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

— ড্যান ম্যাকগ্রা

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

— ডিএক্সএম

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

— ড্যান ম্যাকগ্রা

Answer 3

ডকুমেন্টেশন এটিকে কোনও পরিবর্তন না করেই পঠন করার উদ্দেশ্যে তৈরি করা জিনিস।

আমি মনে করি আপনি উদ্দেশ্য ভিত্তিক সংজ্ঞা দিয়ে ভুল করতে পারবেন না ... তবে আপনি যদি উদ্দেশ্যটিকে সঠিকভাবে সংজ্ঞা দেন তবেই।

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

আপনি যে 'নমুনাগুলি' সরবরাহ করতে যাচ্ছেন তার জন্য, না-পঠন-পরিবর্তিত পার্থক্যটি বেশ গুরুত্বপূর্ণ হয়ে উঠতে পারে।

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

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

Answer 4

"আমি কীভাবে করব ..." প্রশ্নের উত্তর দেয় এমন কিছু হ'ল ডকুমেন্টেশন।

বিকাশকারীদের জন্য, এর অর্থ প্রয়োজনীয়তা বিশদকরণ ("কীভাবে লিখতে হয় তা আমি কীভাবে জানি"), নকশা নথি ("আমি কীভাবে আমার প্রয়োজনীয়তাগুলিকে সম্বোধন করব"), ট্রেসিবিলিটি ম্যাট্রিকেস ("আমি কীভাবে জানি যে আমার নকশা করা আমার সমস্ত প্রয়োজনীয়তার ঠিকানা দেয় "), পরীক্ষা পরিকল্পনা ( "কিভাবে আমি আমার কোড কাজ জানলে"), ইউনিট পরীক্ষা ( "কিভাবে আমি জানি আমি করেছি safisfied প্রয়োজন এক্স"), ইনলাইন মন্তব্য ( "কিভাবে আমি নিশ্চিত আগামী দরিদ্র schlub বুঝতে পারে কেন আমি এটা লিখেছে করতে পারি এই উপায় "), স্থাপনার নির্দেশাবলী (" কীভাবে আমি এই পণ্যটি ইনস্টলেশনের জন্য প্যাকেজ করব "), ইত্যাদি

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