ইতিমধ্যে উন্নত একটি প্রকল্প নথি কিভাবে?

Question

ইতিমধ্যে বিকাশযুক্ত কোনও প্রকল্পের নথিপত্রের জন্য কী কী বিকল্প রয়েছে তা আমি জানতে চাই, যে বিকাশকারীরা কাজ করেছেন তারা ডকুমেন্টেশনের একটি পৃষ্ঠাও লিখেনি।

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

প্রকল্পটি পিএইচপি এবং মাইএসকিউএল দ্বারা বিকাশিত হয়েছিল। ফাংশনগুলি খারাপভাবে মন্তব্য করা হয় তাই আমি ডক্সিজেন দিয়ে চালানোর সময় আমি ভাল ফলাফল পেতে পারি না।

Comments

আমি কর্মপ্রবাহ ডকুমেন্টিং থেকে শুরু করব। বড় ছবি পরিষ্কার হওয়ার পরে, আপনি আরও বিশদ যুক্ত করতে পারেন।

— সুপারম

সম্পর্কিত (যদিও অনুলিপি করার প্রয়োজন নেই): প্রোগ্রামার্স.স্ট্যাকেক্সেঞ্জার.কম

— সেকশনস / 95 95

আইএমএইচও শুরুতে সত্যিই সহায়ক জিনিসটি একটি ক্রস-রেফারেন্স - "কোথায় কী?" কমপক্ষে, যখন স্ক্রিপ্টগুলির নামগুলি থেকে এটি স্পষ্ট না হয় (এবং আমি অনুমান করি এটি তা নয়)।

— ডক ব্রাউন

The functions are poorly commented so I can't get good results when I run it with doxygen। এটি একটি ডিবাগার দিয়ে চালানোর চেষ্টা করুন। এটি উত্স কোডটি মুছে ফেলার সাথে মন্তব্যগুলির অনুলিপি থাকার চেয়ে এটি আরও অনেক ভাল কি করে তা ব্যাখ্যা করবে।

— আয়তাকার

আমি খুঁজে পেয়েছি যে ডকুমেন্টেশনগুলি প্রায়শই বলে যে উত্স কোডটি অনুমান করা হয়েছিল, এটি আসলে কী করে না।

— আয়তাকার

Answer 1

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

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

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

1. ব্যবহারের ক্ষেত্রে পণ্যের পূরণ করে। এটি পণ্যের বয়স বিবেচনা করা কঠিন হতে পারে তবে পণ্যটি কী বোঝায় তা ক্যাপচার অ প্রযুক্তিগত পাঠক এবং পরীক্ষকদের জন্য গুরুত্বপূর্ণ প্রসঙ্গ দেয়। বাজারে প্রতিযোগী কারা (যদি থাকে)? পণ্যের সুযোগ থেকে বাদে কিছু আছে কি?
2. কোনও স্পষ্ট অ অ-কার্যকরী প্রয়োজনীয়তা । উদাহরণস্বরূপ, পণ্যটি একটি নির্দিষ্ট ভলিউম পরিচালনা করতে লেখা হয়েছিল? ডেটা কত পুরানো হতে পারে? ক্যাচিং কোথায় ব্যবহৃত হয়? ব্যবহারকারীরা কীভাবে প্রমাণিত হয়? অ্যাক্সেস নিয়ন্ত্রণ কীভাবে কাজ করে?
3. অন্যান্য সিস্টেমে যেমন ডাটাবেস, প্রমাণীকরণের উত্স, ব্যাকআপ, মনিটরিং এবং এর সাথে কথোপকথন দেখানো একটি প্রসঙ্গ চিত্র চিত্র ।
4. (যদি জানা থাকে) ঝুঁকিগুলি এবং কীভাবে সিদ্ধান্ত নিবন্ধকের সাথে তাদের প্রশমিত করা হয়েছিল । এটি সম্ভবত পূর্ববর্তী ক্ষেত্রেই কঠিন তবে প্রায়শই সমালোচনামূলক সিদ্ধান্ত রয়েছে যা কোনও নকশাকে প্রভাবিত করে। আপনি জানেন যে কোনও ক্যাপচার।
5. সাধারণ নকশার নিদর্শন বা নকশার নির্দেশিকা । উদাহরণস্বরূপ, ডাটাবেস অ্যাক্সেস করার একটি মানক উপায় আছে? কোডিং বা নামকরণের মান আছে কি?
6. সমালোচনামূলক কোড পাথগুলি , সাধারণত ফ্লো চার্ট বা ইউএমএল ক্রিয়াকলাপ বা সিকোয়েন্স ডায়াগ্রাম ব্যবহার করে। প্রকল্পে কোনও নাও থাকতে পারে তবে এগুলি সাধারণত ব্যবসায়িক ব্যবহারকারীরা বলে থাকেন।

এমনকি যদি এই সমস্ত তথ্য না পাওয়া যায় তবে এখনই শুরু করুন । আপনার পরে আসা বিকাশকারীরা আপনাকে ধন্যবাদ জানাবে।

স্বতঃ স্বয়ংক্রিয় ইউনিট পরীক্ষা বা পরীক্ষার কেসগুলিও কার্যকর ডকুমেন্টেশন হতে পারে, যদিও কম প্রযুক্তিগত লোকের পক্ষে অ্যাক্সেস করা শক্ত।

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

Answer 2

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

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

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

Answer 3

প্রথম জিনিসগুলি, আপনার টার্গেট শ্রোতা কে? ভবিষ্যতের বিকাশকারী বা অন্যান্য ব্যবসায়ী মানুষ? এই প্রশ্নের উত্তর মাথায় রেখে:

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

যে কোনও জটিল প্রক্রিয়াজাতকরণ বা যুক্তি আমি একটি স্টেট ডায়াগ্রাম, ডেটা ফ্লো ডায়াগ্রাম বা সিকোয়েন্স ডায়াগ্রাম ব্যবহার করতাম। অবশ্যই কোনও সত্তার চিত্রটি করুন, তারপরে একটি ডিবি স্কিমা ডিজাইন (দুটি ভিন্ন জিনিস!) করুন। হতে পারে একটি মৌলিক শ্রেণীর ডায়াগ্রাম তবে এটি সহজ রাখুন, কেবল আগ্রহের মূল বিষয়গুলি নোট করুন, ডিভস কোডটি দেখে সেই জিনিসটি বের করতে পারে।

আপনার যদি শুরু করতে সমস্যা হয়, কেবলমাত্র আপনার পাশের ঘরেই অন্য একজন বিকাশকারী রয়েছে তা ভান করুন, যিনি সিস্টেম সম্পর্কে প্রথম জিনিস জানেন না, আমি তুলনামূলকভাবে অধৈর্য এবং তার মূল কথাটি জানা দরকার। তারপরে ব্যাখ্যা শুরু করুন, এবং আপনি যা বলবেন তা লিখুন :)

Answer 4

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

Answer 5

প্রশ্নটি হ'ল আপনি কি এখন এটি যেমনটি চান ঠিক তেমন নথিবদ্ধ করতে চান বা যেমনটি হওয়া উচিত?

আপনার প্রশ্ন থেকে আমি যা পড়েছি তা হ'ল আপনি এপিআই ডকুমেন্টেশন সম্পর্কে ভাবছেন এবং এতগুলি ব্যবহারকারীর নথিপত্র নয় এবং কোডটি সম্ভবত এতটা রক্ষণাবেক্ষণ এবং ক্রিপ্টিক নয়।

আমি আশঙ্কা করছি আপনি যদি এখনই ডকুমেন্ট করেন তবে কোডটি রিফ্যাক্ট হয়ে গেলে আপনি আপনার বেশিরভাগ কাজ ফেলে দেবেন।

আমি নিম্নলিখিত পদ্ধতি গ্রহণ করব:

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

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