ব্যবহারকারীর ডকুমেন্টেশন: কী এটি খারাপ করে এবং কীভাবে এটি ঠিক করা যায়

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

আমাদের পুরানো ডকুমেন্টেশনে অনেক ত্রুটি ছিল। আমরা এখন প্রায় এক বছর ধরে এটি পুনরায় কাজ করছি যাতে উপরে বর্ণিত দৃশ্যটি আমাদের ক্লায়েন্টদের প্রভাবিত না করে। দেখ, যেমন ছিল и এটা কিভাবে ঘটেছে.

সমস্যা 1: অস্পষ্ট, খারাপভাবে লেখা নিবন্ধ

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

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

উপরের টিপসগুলি বিবেচনা করুন, এবং নিবন্ধগুলি আরও স্পষ্ট হয়ে উঠবে - গ্যারান্টিযুক্ত। এটি আরও ভাল করতে, আমাদের ব্যবহার করুন প্রযুক্তিগত ডকুমেন্টেশনে কাজ করার সময় 50টি প্রশ্ন.

সমস্যা 2. নিবন্ধগুলি সমস্ত প্রশ্নের উত্তর দেয় না

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

ডকুমেন্টেশন উন্নয়ন সঙ্গে রাখা না

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

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

ডকুমেন্টেশন ব্যবহারকারীর অনুরোধ প্রতিফলিত করে না

আমরা এই মত কাজ করতে অভ্যস্ত: একটি বৈশিষ্ট্য বেরিয়ে এসেছে, আমরা এটি সম্পর্কে কথা বলেছি। আমরা বর্ণনা করেছি কিভাবে এটি চালু করা যায়, এটি বন্ধ করা যায় এবং সূক্ষ্ম সমন্বয় করা যায়। কিন্তু যদি কোন ক্লায়েন্ট আমাদের সফটওয়্যার এমনভাবে ব্যবহার করে যা আমরা আশা করিনি? নাকি এতে এমন ত্রুটি আছে যা আমরা ভাবিনি?

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

ডকুমেন্টেশন উন্নত করা হচ্ছে না

এখনই এটি পুরোপুরি করা কঠিন; এখনও ভুল থাকবে। আপনি গ্রাহকদের কাছ থেকে প্রতিক্রিয়া আশা করতে পারেন, কিন্তু এটা অসম্ভাব্য যে তারা প্রতিটি টাইপো, ভুল, বোধগম্য বা অপ্রস্তুত নিবন্ধ রিপোর্ট করবে। ক্লায়েন্ট ছাড়াও, কর্মীরা ডকুমেন্টেশন পড়ে, যার মানে তারা একই ত্রুটি দেখতে পায়। এই ব্যবহার করা যেতে পারে! আপনাকে কেবল এমন পরিস্থিতি তৈরি করতে হবে যেখানে সমস্যাটি রিপোর্ট করা সহজ হবে।

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

সমস্যা 3. সঠিক নিবন্ধটি খুঁজে পেতে অনেক সময় লাগে।

একটি নিবন্ধ যা খুঁজে পাওয়া যায় না এমন একটি নিবন্ধের চেয়ে ভাল নয় যা পাওয়া যায় না। ভাল ডকুমেন্টেশনের মূলমন্ত্র হওয়া উচিত "অনুসন্ধান করা সহজ, খুঁজে পাওয়া সহজ।" এই অর্জন কিভাবে?

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

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

আপনি যে পদ্ধতিই বেছে নিন না কেন, নিশ্চিত করুন যে বিষয়টি ব্যবহারকারীরা যা খুঁজছেন তার সাথে প্রাসঙ্গিক এবং এমনভাবে কভার করা হয়েছে যা ব্যবহারকারীর প্রশ্নটিকে বিশেষভাবে সম্বোধন করে।

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

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

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

পপ-আপ উইন্ডোতে ডানদিকে ISPmanager-এর ডোমেন ম্যানেজমেন্ট বিভাগে DNSSEC সেট আপ করার বিষয়ে একটি নিবন্ধের একটি লিঙ্ক রয়েছে

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

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

সমস্যা 4. পুরানো লেআউট উপলব্ধিতে হস্তক্ষেপ করে

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

এই নিবন্ধটিতে অনেকগুলি স্ক্রিনশট এবং হাইলাইট রয়েছে যা তারা সাহায্য করে না, তবে কেবল উপলব্ধিতে হস্তক্ষেপ করে (ছবিটি ক্লিকযোগ্য)

একগুচ্ছ প্রভাব সহ ডকুমেন্টেশন থেকে আপনার লংরিড করা উচিত নয়, তবে আপনাকে প্রাথমিক নিয়মগুলি বিবেচনা করতে হবে।

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

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

স্ক্রিনশট. কোন ক্ষেত্রে স্ক্রিনশট প্রয়োজন দলের সাথে একমত। প্রতিটি ধাপে চিত্রিত করার প্রয়োজন নেই। প্রচুর সংখ্যক স্ক্রিনশট, সহ। পৃথক বোতাম, উপলব্ধিতে হস্তক্ষেপ, বিন্যাস লুণ্ঠন. আকার, সেইসাথে স্ক্রিনশটগুলিতে হাইলাইট এবং স্বাক্ষরগুলির বিন্যাস নির্ধারণ করুন এবং সেগুলিকে প্রবিধানে রেকর্ড করুন৷ মনে রাখবেন যে চিত্রগুলি সর্বদা যা লেখা হয়েছে তার সাথে সঙ্গতিপূর্ণ এবং প্রাসঙ্গিক হওয়া উচিত। আবার পণ্য নিয়মিত হালনাগাদ করা হলে সবার খোঁজখবর রাখা কঠিন হবে।

পাঠ্যের দৈর্ঘ্য. অত্যধিক দীর্ঘ নিবন্ধ এড়িয়ে চলুন. এগুলিকে ভাগে ভাগ করুন এবং যদি এটি সম্ভব না হয় তবে নিবন্ধের শুরুতে অ্যাঙ্কর লিঙ্ক সহ সামগ্রী যোগ করুন। একটি নিবন্ধকে দৃশ্যত ছোট করার একটি সহজ উপায় হল পাঠকদের একটি সংকীর্ণ বৃত্তের জন্য প্রয়োজনীয় প্রযুক্তিগত বিবরণ লুকিয়ে রাখা।

ফরম্যাটের. আপনার নিবন্ধে বিভিন্ন বিন্যাস একত্রিত করুন: পাঠ্য, ভিডিও এবং চিত্র। এটি উপলব্ধি উন্নত করবে।

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

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

কোথায় উন্নতি শুরু করবেন এবং কীভাবে বেঁচে থাকবেন

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

এখনই বলি - এটা সহজ হবে না। এবং এটি দ্রুত কাজ করার সম্ভাবনাও কম। যদি না আপনি শুধু শুরু করছেন এবং এখনই সঠিক কাজটি করছেন। একটি জিনিস আমরা নিশ্চিতভাবে জানি যে এটি সময়ের সাথে আরও ভাল হবে। কিন্তু প্রক্রিয়া শেষ হবে না :-)।

উত্স: www.habr.com