Bazel এর ডকুমেন্টেশন অবদানের জন্য আপনাকে ধন্যবাদ. এটি আপনাকে শুরু করার জন্য একটি দ্রুত ডকুমেন্টেশন শৈলী নির্দেশিকা হিসাবে কাজ করে। এই নির্দেশিকা দ্বারা উত্তর না দেওয়া কোনও শৈলী প্রশ্নের জন্য, Google বিকাশকারী ডকুমেন্টেশন শৈলী নির্দেশিকা অনুসরণ করুন।
সংজ্ঞায়িত নীতি
Bazel ডক্সের এই নীতিগুলি বজায় রাখা উচিত:
- সংক্ষিপ্ত. যতটা সম্ভব কম শব্দ ব্যবহার করুন।
- স্পষ্ট. সরল ভাষা ব্যবহার করুন। পঞ্চম-শ্রেণির পড়ার স্তরের জন্য শব্দার্থ ছাড়াই লিখুন।
- সামঞ্জস্যপূর্ণ। ডক্স জুড়ে পুনরাবৃত্তি ধারণার জন্য একই শব্দ বা বাক্যাংশ ব্যবহার করুন।
- সঠিক। সময়-ভিত্তিক তথ্য এবং ভবিষ্যতের প্রতিশ্রুতি এড়িয়ে যতক্ষণ সম্ভব বিষয়বস্তু যথাসম্ভব সঠিক থাকে এমনভাবে লিখুন।
লেখা
এই বিভাগে মৌলিক লেখার টিপস রয়েছে।
শিরোনাম
- পৃষ্ঠা-স্তরের শিরোনাম H2 থেকে শুরু হয়। (H1 শিরোনামগুলি পৃষ্ঠা শিরোনাম হিসাবে ব্যবহৃত হয়।)
শিরোনামগুলিকে সংক্ষিপ্ত করুন যতটা বুদ্ধিমান। এইভাবে, তারা মোড়ানো ছাড়াই TOC এ ফিট করে।
- হ্যাঁ : অনুমতি
- না : অনুমতির উপর একটি সংক্ষিপ্ত নোট
শিরোনাম জন্য বাক্য ক্ষেত্রে ব্যবহার করুন
- হ্যাঁ : আপনার কর্মক্ষেত্র সেট আপ করুন
- না : আপনার ওয়ার্কস্পেস সেট আপ করুন
শিরোনাম টাস্ক-ভিত্তিক বা কর্মযোগ্য করার চেষ্টা করুন। শিরোনামগুলি ধারণাগত হলে, এটি বোঝার উপর ভিত্তি করে হতে পারে, তবে ব্যবহারকারী যা করেন তা লিখুন।
- হ্যাঁ : গ্রাফ অর্ডার সংরক্ষণ করা
- না : গ্রাফ অর্ডার সংরক্ষণের উপর
নাম
বাজেল এবং স্টারলার্কের মতো সঠিক বিশেষ্যগুলিকে বড় করা।
- হ্যাঁ : বিল্ডের শেষে, Bazel অনুরোধ করা লক্ষ্যগুলি প্রিন্ট করে।
- না : বিল্ডের শেষে, বেজেল অনুরোধ করা লক্ষ্যগুলি প্রিন্ট করে।
এটি ধারাবাহিক রাখুন। বিদ্যমান ধারণার জন্য নতুন নাম প্রবর্তন করবেন না। যেখানে প্রযোজ্য, শব্দকোষে সংজ্ঞায়িত শব্দটি ব্যবহার করুন।
- উদাহরণস্বরূপ, যদি আপনি একটি টার্মিনালে কমান্ড ইস্যু করার বিষয়ে লিখছেন, তাহলে পৃষ্ঠায় টার্মিনাল এবং কমান্ড লাইন উভয়ই ব্যবহার করবেন না।
পৃষ্ঠার সুযোগ
প্রতিটি পৃষ্ঠার একটি উদ্দেশ্য থাকা উচিত এবং এটি শুরুতে সংজ্ঞায়িত করা উচিত। এটি পাঠকদের তাদের যা প্রয়োজন তা দ্রুত খুঁজে পেতে সহায়তা করে৷
- হ্যাঁ : এই পৃষ্ঠাটি উইন্ডোজে ব্যাজেল ইনস্টল করার পদ্ধতি কভার করে।
- না : (কোন সূচনা বাক্য নয়।)
পৃষ্ঠার শেষে, পাঠককে পরবর্তীতে কী করতে হবে তা বলুন। পৃষ্ঠাগুলির জন্য যেখানে কোনও স্পষ্ট পদক্ষেপ নেই, আপনি অনুরূপ ধারণা, উদাহরণ বা অন্বেষণের জন্য অন্যান্য উপায়গুলির লিঙ্ক অন্তর্ভুক্ত করতে পারেন।
বিষয়
Bazel ডকুমেন্টেশনে, শ্রোতাদের প্রাথমিকভাবে ব্যবহারকারী হওয়া উচিত - লোকেরা তাদের সফ্টওয়্যার তৈরি করতে Bazel ব্যবহার করে৷
আপনার পাঠককে "আপনি" বলে সম্বোধন করুন। (যদি কোনো কারণে আপনি "আপনি" ব্যবহার করতে না পারেন, লিঙ্গ-নিরপেক্ষ ভাষা ব্যবহার করুন, যেমন তারা।)
- হ্যাঁ : Bazel ব্যবহার করে জাভা কোড তৈরি করতে, আপনাকে অবশ্যই একটি JDK ইনস্টল করতে হবে।
- হতে পারে : ব্যাজেল দিয়ে জাভা কোড তৈরি করার জন্য ব্যবহারকারীদের অবশ্যই একটি JDK ইনস্টল করতে হবে।
- না : ব্যাজেল দিয়ে জাভা কোড তৈরি করতে একজন ব্যবহারকারীর জন্য, তাকে অবশ্যই একটি JDK ইনস্টল করতে হবে।
আপনার শ্রোতা সাধারণ ব্যাজেল ব্যবহারকারী না হলে, পৃষ্ঠার শুরুতে বা বিভাগে দর্শকদের সংজ্ঞায়িত করুন। অন্যান্য শ্রোতাদের মধ্যে রক্ষণাবেক্ষণকারী, অবদানকারী, অভিবাসী বা অন্যান্য ভূমিকা অন্তর্ভুক্ত থাকতে পারে।
"আমরা" এড়িয়ে চলুন। ব্যবহারকারী ডক্সে, কোন লেখক নেই; শুধু লোকেদের বলুন কি সম্ভব।
- হ্যাঁ : ব্যাজেল বিকশিত হওয়ার সাথে সাথে সামঞ্জস্য বজায় রাখতে আপনার কোড বেস আপডেট করা উচিত।
- না : Bazel বিকশিত হচ্ছে, এবং আমরা Bazel-এ এমন কিছু পরিবর্তন করব যা কখনও কখনও বেমানান হবে এবং Bazel ব্যবহারকারীদের কাছ থেকে কিছু পরিবর্তন প্রয়োজন৷
অস্থায়ী
যেখানে সম্ভব, নির্দিষ্ট তারিখগুলি উল্লেখ করা (Q2 2022) বা "এখন", "বর্তমানে" বা "শীঘ্রই" বলার মতো শর্তাবলী এড়িয়ে চলুন এগুলি দ্রুত বাসি হয়ে যায় এবং এটি ভবিষ্যতের অভিক্ষেপ হলে ভুল হতে পারে। পরিবর্তে, পরিবর্তে একটি সংস্করণ স্তর নির্দিষ্ট করুন, যেমন "Bazel Xx এবং উচ্চতর সমর্থন <feature> বা একটি GitHub সমস্যা লিঙ্ক।
- হ্যাঁ : Bazel 0.10.0 বা তার পরে রিমোট ক্যাশিং সমর্থন করে।
- না : Bazel শীঘ্রই রিমোট ক্যাশিং সমর্থন করবে, সম্ভবত অক্টোবর 2017 এ।
ক্রিয়ার কাল
বর্তমান কাল ব্যবহার করুন। স্পষ্টতার জন্য একেবারে প্রয়োজনীয় না হলে অতীত বা ভবিষ্যতের কাল এড়িয়ে চলুন।
- হ্যাঁ : Bazel একটি ত্রুটি ইস্যু করে যখন এটি এই নিয়মের সাথে সঙ্গতিপূর্ণ নয় এমন নির্ভরতা খুঁজে পায়।
- না : যদি Bazel এমন একটি নির্ভরতা খুঁজে পায় যা এই নিয়মের সাথে সঙ্গতিপূর্ণ নয়, Bazel একটি ত্রুটি জারি করবে৷
যেখানে সম্ভব, সক্রিয় ভয়েস ব্যবহার করুন (যেখানে একটি বিষয় একটি বস্তুর উপর কাজ করে) প্যাসিভ ভয়েস নয় (যেখানে একটি বিষয় একটি বিষয় দ্বারা কাজ করে)। সাধারণত, সক্রিয় ভয়েস বাক্যকে স্পষ্ট করে তোলে কারণ এটি দেখায় কে দায়ী। সক্রিয় ভয়েস ব্যবহার করলে স্বচ্ছতা বিঘ্নিত হয়, প্যাসিভ ভয়েস ব্যবহার করুন।
- হ্যাঁ : ব্যাজেল X শুরু করে এবং Y তৈরি করতে আউটপুট ব্যবহার করে।
- না : X ব্যাজেল দ্বারা শুরু করা হয়েছে এবং তারপরে Y আউটপুট দিয়ে তৈরি করা হবে।
স্বর
একটি ব্যবসা বন্ধুত্বপূর্ণ স্বন সঙ্গে লিখুন.
কথ্য ভাষা এড়িয়ে চলুন। ইংরেজিতে নির্দিষ্ট বাক্যাংশ অনুবাদ করা কঠিন।
- হ্যাঁ : ভাল নিয়ম
- না : তাহলে একটি ভাল নিয়ম কি?
অত্যধিক আনুষ্ঠানিক ভাষা এড়িয়ে চলুন. এমনভাবে লিখুন যেন আপনি এমন কাউকে ধারণাটি ব্যাখ্যা করছেন যিনি প্রযুক্তি সম্পর্কে কৌতূহলী, কিন্তু বিস্তারিত জানেন না।
ফরম্যাটিং
ফাইলের ধরন
পঠনযোগ্যতার জন্য, 80 অক্ষরে লাইন মোড়ানো। দীর্ঘ লিঙ্ক বা কোড স্নিপেট দীর্ঘ হতে পারে, কিন্তু একটি নতুন লাইন শুরু করা উচিত. উদাহরণ স্বরূপ:
লিঙ্ক
"এখানে" বা "নীচে" এর পরিবর্তে বর্ণনামূলক লিঙ্ক পাঠ্য ব্যবহার করুন। এই অনুশীলনটি একটি ডক স্ক্যান করা সহজ করে তোলে এবং স্ক্রিন পাঠকদের জন্য আরও ভাল।
- হ্যাঁ : আরো বিস্তারিত জানার জন্য, [বেজেল ইনস্টল করা] দেখুন।
- না : আরো বিস্তারিত জানার জন্য, [এখানে] দেখুন।
সম্ভব হলে লিঙ্ক দিয়ে বাক্যটি শেষ করুন।
- হ্যাঁ : আরো বিস্তারিত জানার জন্য, [লিংক] দেখুন।
- না : আরও তথ্যের জন্য [লিংক] দেখুন।
তালিকা
- ধাপ সহ একটি টাস্ক কিভাবে সম্পন্ন করতে হয় তা বর্ণনা করতে একটি অর্ডার করা তালিকা ব্যবহার করুন
- কাজ ভিত্তিক নয় এমন জিনিসগুলি তালিকাভুক্ত করতে একটি ক্রমহীন তালিকা ব্যবহার করুন। (এখনও একটি ক্রম থাকা উচিত, যেমন বর্ণানুক্রমিক, গুরুত্ব, ইত্যাদি)
- সমান্তরাল গঠন সহ লিখুন। উদাহরণ স্বরূপ:
- সমস্ত তালিকা আইটেম বাক্য তৈরি করুন.
- একই কালের ক্রিয়াপদ দিয়ে শুরু করুন।
- যদি অনুসরণ করার পদক্ষেপ থাকে তবে একটি আদেশকৃত তালিকা ব্যবহার করুন।
স্থানধারক
ব্যবহারকারীদের পরিবর্তন করা উচিত এমন একটি ভেরিয়েবল বোঝাতে কোণ বন্ধনী ব্যবহার করুন। মার্কডাউনে, ব্যাক স্ল্যাশ দিয়ে কোণ বন্ধনীগুলি এড়িয়ে যান:
\<example\>।- হ্যাঁ :
bazel help <command>: প্রিন্ট করে সাহায্য এবং<command>-এর বিকল্প - না : বেজেল হেল্প কমান্ড : "কমান্ড" এর জন্য সাহায্য এবং বিকল্পগুলি প্রিন্ট করে
- হ্যাঁ :
বিশেষ করে জটিল কোড নমুনার জন্য, স্থানধারক ব্যবহার করুন যা প্রেক্ষাপটে অর্থপূর্ণ।
সুচিপত্র
সাইট দ্বারা সমর্থিত স্বয়ংক্রিয়ভাবে তৈরি TOC ব্যবহার করুন। একটি ম্যানুয়াল TOC যোগ করবেন না।
কোড
কোড নমুনা হল ডেভেলপারদের সেরা বন্ধু। আপনি সম্ভবত জানেন কিভাবে এই লিখতে হয়, কিন্তু এখানে কয়েকটি টিপস আছে.
আপনি যদি কোডের একটি ছোট স্নিপেট উল্লেখ করছেন, আপনি এটি একটি বাক্যে এম্বেড করতে পারেন। আপনি যদি চান যে পাঠক কোড ব্যবহার করুক, যেমন একটি কমান্ড অনুলিপি করা, একটি কোড ব্লক ব্যবহার করুন।
কোড ব্লক
- সংক্ষিপ্ত রাখুন। একটি কোড নমুনা থেকে সমস্ত অপ্রয়োজনীয় বা অপ্রয়োজনীয় পাঠ্য বাদ দিন।
- মার্কডাউনে, নমুনার ভাষা যোগ করে কোড ব্লকের ধরন নির্দিষ্ট করুন।
```shell
...
- বিভিন্ন কোড ব্লকে আলাদা কমান্ড এবং আউটপুট।
ইনলাইন কোড বিন্যাস
- ফাইলের নাম, ডিরেক্টরি, পাথ এবং কোডের ছোট বিটগুলির জন্য কোড শৈলী ব্যবহার করুন।
- তির্যক , "উদ্ধৃতি" বা বোল্ডিংয়ের পরিবর্তে ইনলাইন কোড স্টাইলিং ব্যবহার করুন৷
- হ্যাঁ :
bazel help <command>: প্রিন্ট করে সাহায্য এবং<command>-এর বিকল্প - না : বেজেল হেল্প কমান্ড : "কমান্ড" এর জন্য সাহায্য এবং বিকল্পগুলি প্রিন্ট করে
- হ্যাঁ :