সর্বোত্তম অনুশীলন
- ব্যবহারকারীর উদ্দেশ্য এবং দর্শকের উপর মনোযোগ দিন।
- দৈনন্দিন শব্দ ব্যবহার করুন এবং বাক্য সংক্ষিপ্ত রাখুন।
- বাক্য গঠন, শব্দচয়ন এবং বড় হাতের অক্ষর ব্যবহারে সামঞ্জস্য বজায় রাখুন।
- আপনার নথিগুলো সহজে দেখার জন্য শিরোনাম এবং তালিকা ব্যবহার করুন।
- গুগল ডেভেলপার ডক্স স্টাইল গাইডটি সহায়ক।
মার্কডাউন
কিছু ব্যতিক্রম ছাড়া, TensorFlow গিটহাব ফ্লেভার্ড মার্কডাউন (GFM)-এর অনুরূপ একটি মার্কডাউন সিনট্যাক্স ব্যবহার করে। এই অংশে GFM মার্কডাউন সিনট্যাক্স এবং TensorFlow ডকুমেন্টেশনে ব্যবহৃত মার্কডাউনের মধ্যে পার্থক্য ব্যাখ্যা করা হয়েছে।
কোড সম্পর্কে লিখুন
কোডের ইনলাইন উল্লেখ
টেক্সটে ব্যবহার করার সময় নিম্নলিখিত চিহ্নগুলির চারপাশে `backticks` দিন:
- আর্গুমেন্টের নামগুলো:
`input`,`x`,`tensor` - ফেরত আসা টেনসরের নামগুলো:
`output`,`idx`,`out` - ডেটা টাইপ:
`int32`,`float`,`uint8` - টেক্সটে উল্লেখিত অন্যান্য অপারেশনের নাম:
`list_diff()`,`shuffle()` - ক্লাসের নাম:
`tf.Tensor`,`Strategy` - ফাইলের নাম:
`image_ops.py`,`/path_to_dir/file_name` - গাণিতিক রাশি বা শর্ত:
`-1-input.dims() <= dim <= input.dims()`
কোড ব্লক
একটি কোড ব্লক শুরু ও শেষ করতে তিনটি ব্যাকটিক ব্যবহার করুন। ঐচ্ছিকভাবে, প্রথম ব্যাকটিক গ্রুপের পরে প্রোগ্রামিং ভাষা উল্লেখ করুন, উদাহরণস্বরূপ:
```python
# some python code here
```
মার্কডাউন এবং নোটবুকে লিঙ্ক
একটি রিপোজিটরিতে ফাইলগুলির মধ্যে লিঙ্ক
একটিমাত্র গিটহাব রিপোজিটরির মধ্যে ফাইলগুলোর মধ্যে রিলেটিভ লিঙ্ক ব্যবহার করুন। ফাইল এক্সটেনশনটি অন্তর্ভুক্ত করুন।
উদাহরণস্বরূপ, আপনি যে ফাইলটি পড়ছেন তা https://github.com/tensorflow/docs রিপোজিটরি থেকে নেওয়া। তাই, এটি একই রিপোজিটরির অন্যান্য ফাইলের সাথে লিঙ্ক করার জন্য রিলেটিভ পাথ ব্যবহার করতে পারে, যেমনটা এখানে দেখানো হয়েছে:
-
[Basics](../../guide/basics.ipynb)Basics তৈরি হয়।
এটিই সবচেয়ে ভালো পদ্ধতি, কারণ এর মাধ্যমে tensorflow.org , GitHub এবং Colab- এর সব লিঙ্কই কাজ করে। এছাড়াও, পাঠক কোনো লিঙ্কে ক্লিক করলেও একই সাইটে থাকেন।
বাহ্যিক লিঙ্ক
যে ফাইলগুলো বর্তমান রিপোজিটরিতে নেই, সেগুলোর লিংকের জন্য সম্পূর্ণ URI সহ স্ট্যান্ডার্ড মার্কডাউন লিংক ব্যবহার করুন। যদি tensorflow.org URI উপলব্ধ থাকে, তবে সেটি ব্যবহার করা শ্রেয়।
সোর্স কোডের সাথে লিঙ্ক করতে, https://www.github.com/tensorflow/tensorflow/blob/master/ দিয়ে শুরু হওয়া একটি লিঙ্ক ব্যবহার করুন, এবং এর পরে গিটহাব রুট থেকে শুরু করে ফাইলের নামটি দিন।
tensorflow.org থেকে লিঙ্ক করার সময়, মার্কডাউন লিঙ্কে একটি `` যোগ করুন, যাতে "বহিরাগত লিঙ্ক" প্রতীকটি প্রদর্শিত হয়।
-
[GitHub](https://github.com/tensorflow/docs)GitHub তৈরি করে
লিঙ্কে URI কোয়েরি প্যারামিটার অন্তর্ভুক্ত করবেন না:
- ব্যবহার করুন:
https://www.tensorflow.org/guide/data - না:
https://www.tensorflow.org/guide/data?hl=en
ছবি
পূর্ববর্তী অনুচ্ছেদের পরামর্শটি পৃষ্ঠার লিঙ্কের জন্য। ছবি ভিন্নভাবে পরিচালনা করা হয়।
সাধারণত, আপনার ইমেজ চেক-ইন করা উচিত নয়, বরং আপনার PR-এ TensorFlow-Docs টিমকে যুক্ত করুন এবং তাদেরকে tensorflow.org- এ ইমেজগুলো হোস্ট করতে বলুন। এটি আপনার রিপোজিটরির সাইজ কম রাখতে সাহায্য করে।
আপনি যদি আপনার রিপোজিটরিতে ছবি জমা দেন, তবে মনে রাখবেন যে কিছু সিস্টেম ছবির রিলেটিভ পাথ সাপোর্ট করে না। এক্ষেত্রে tensorflow.org- এ ছবিটির চূড়ান্ত অবস্থান নির্দেশকারী একটি সম্পূর্ণ URL ব্যবহার করা শ্রেয়।
এপিআই ডকুমেন্টেশনের লিঙ্ক
সাইটটি প্রকাশিত হলে এপিআই লিঙ্কগুলি রূপান্তরিত হয়। কোনো সিম্বলের এপিআই রেফারেন্স পৃষ্ঠায় লিঙ্ক করতে, সিম্বল পাথটিকে ব্যাকটিকের মধ্যে রাখুন:
-
`tf.data.Dataset`ফলেtf.data.Datasetতৈরি হয়।
দীর্ঘ পাথ ছাড়া পূর্ণ পাথ কিছুটা বেশি পছন্দনীয়। পাথের শুরুর অংশ বাদ দিয়ে পাথ সংক্ষিপ্ত করা যায়। নিম্নলিখিত ক্ষেত্রে আংশিক পাথ লিঙ্কে রূপান্তরিত হবে:
- পথে অন্তত একটি
.আছে, এবং - আংশিক পথটি প্রকল্পের মধ্যে অনন্য।
tensorflow.org- এ প্রকাশিত পাইথন এপিআই সহ প্রতিটি প্রকল্পের জন্য এপিআই পাথগুলি লিঙ্ক করা আছে। আপনি এপিআই নামগুলিকে ব্যাকটিক দিয়ে মুড়ে দিয়ে একটি ফাইল থেকেই একাধিক সাবপ্রজেক্টে সহজেই লিঙ্ক করতে পারেন। উদাহরণস্বরূপ:
-
`tf.metrics`,`tf_agents.metrics`,`text.metrics`ফলে তৈরি হয়:tf.metrics,tf_agents.metrics,text.metrics।
যেসব সিম্বলের একাধিক পাথ অ্যালিয়াস আছে, সেগুলোর ক্ষেত্রে tensorflow.org- এর এপিআই-পেজের সাথে মেলে এমন পাথটিকে সামান্য অগ্রাধিকার দেওয়া হয়। সব অ্যালিয়াসই সঠিক পেজে রিডাইরেক্ট হবে।
মার্কডাউনে গণিত
মার্কডাউন ফাইল সম্পাদনা করার সময় আপনি টেনসরফ্লো-এর মধ্যে ম্যাথজ্যাক্স ব্যবহার করতে পারেন, কিন্তু নিম্নলিখিত বিষয়গুলো মনে রাখবেন:
- tensorflow.org- এ MathJax সঠিকভাবে রেন্ডার হয়।
- গিটহাবে MathJax সঠিকভাবে প্রদর্শিত হয় না।
- এই সাংকেতিক চিহ্নটি অনভিজ্ঞ ডেভেলপারদের কাছে অপ্রীতিকর মনে হতে পারে।
- সামঞ্জস্য রক্ষার জন্য tensorflow.org , Jupyter/Colab-এর নিয়মকানুনই অনুসরণ করে।
MathJax-এর কোনো ব্লকের চারপাশে $$ ব্যবহার করুন:
$$
E=\frac{1}{2n}\sum_x\lVert (y(x)-y'(x)) \rVert^2
$$\[ E=\frac{1}{2n}\sum_x\lVert (y(x)-y'(x)) \rVert^2 \]
ইনলাইন MathJax এক্সপ্রেশনগুলোকে $ ... $ দিয়ে মুড়ে দিন:
This is an example of an inline MathJax expression: $ 2 \times 2 = 4 $
এটি একটি ইনলাইন ম্যাথজ্যাক্স এক্সপ্রেশনের উদাহরণ: \( 2 \times 2 = 4 \)
\\( ... \\) ডিলিমিটারগুলো ইনলাইন ম্যাথের ক্ষেত্রেও কাজ করে, কিন্তু $ ফর্মটি কখনও কখনও বেশি পাঠযোগ্য হয়।
গদ্য শৈলী
আপনি যদি বর্ণনামূলক ডকুমেন্টেশনের উল্লেখযোগ্য অংশ লিখতে বা সম্পাদনা করতে যান, তাহলে অনুগ্রহ করে গুগল ডেভেলপার ডকুমেন্টেশন স্টাইল গাইডটি পড়ুন।
ভালো শৈলীর নীতিমালা
- আপনার লেখায় বানান ও ব্যাকরণ পরীক্ষা করে নিন। বেশিরভাগ এডিটরেই স্পেল চেকার থাকে অথবা স্পেল-চেকিং প্লাগইন পাওয়া যায়। আরও ভালোভাবে বানান ও ব্যাকরণ পরীক্ষা করার জন্য আপনি আপনার লেখাটি গুগল ডক বা অন্য কোনো ডকুমেন্ট সফটওয়্যারে পেস্ট করতে পারেন।
- সহজ ও বন্ধুত্বপূর্ণ ভাষা ব্যবহার করুন। TensorFlow ডকুমেন্টেশন এমনভাবে লিখুন যেন তা একটি কথোপকথন—যেন আপনি অন্য কোনো ব্যক্তির সাথে একান্তে কথা বলছেন। লেখাটিতে একটি সহায়ক সুর বজায় রাখুন।
- অস্বীকৃতি, মতামত এবং মূল্যবোধের বিচার পরিহার করুন। 'সহজে', 'শুধু', এবং 'সরল'-এর মতো শব্দগুলো অনুমানে পরিপূর্ণ। কোনো কিছু আপনার কাছে সহজ মনে হতে পারে, কিন্তু তা অন্য কারো জন্য কঠিন হতে পারে। যথাসম্ভব এগুলো এড়িয়ে চলার চেষ্টা করুন।
- জটিল পরিভাষা পরিহার করে সহজ ও সংক্ষিপ্ত বাক্য ব্যবহার করুন। যৌগিক বাক্য, একাধিক খণ্ডবাক্যের শৃঙ্খল এবং স্থান-নির্দিষ্ট বাগধারা কোনো লেখাকে বোঝা ও অনুবাদ করা কঠিন করে তুলতে পারে। যদি কোনো বাক্যকে দুটি ভাগে ভাগ করা যায়, তবে সম্ভবত তা করাই উচিত। সেমিকোলন পরিহার করুন। প্রয়োজন অনুযায়ী বুলেট তালিকা ব্যবহার করুন।
- প্রাসঙ্গিক তথ্য দিন। ব্যাখ্যা ছাড়া সংক্ষিপ্ত রূপ ব্যবহার করবেন না। লিঙ্ক না দিয়ে TensorFlow-বহির্ভূত প্রকল্পের উল্লেখ করবেন না। কোডটি যেভাবে লেখা হয়েছে, তার কারণ ব্যাখ্যা করুন।
ব্যবহার নির্দেশিকা
অপারেশন
মার্কডাউন ফাইলে, কোনো অপারেশন কী রিটার্ন করে তা দেখাতে চাইলে একটিমাত্র সমান চিহ্নের পরিবর্তে # ⇒ ব্যবহার করুন।
# 'input' is a tensor of shape [2, 3, 5]
tf.expand_dims(input, 0) # ⇒ [1, 2, 3, 5]
নোটবুকে মন্তব্য যোগ করার পরিবর্তে ফলাফলটি প্রদর্শন করুন (যদি নোটবুক সেলের শেষ এক্সপ্রেশনটি কোনো ভেরিয়েবলে অ্যাসাইন করা না থাকে, তবে এটি স্বয়ংক্রিয়ভাবে প্রদর্শিত হয়।)
এপিআই রেফারেন্স ডক্স-এ ফলাফল দেখানোর জন্য ডকটেস্ট ব্যবহার করা শ্রেয়।
টেনসর
সাধারণভাবে টেনসর নিয়ে কথা বলার সময় 'tensor' শব্দটি বড় হাতের অক্ষরে লিখবেন না। কিন্তু যখন কোনো অপ (op)-এ দেওয়া বা সেখান থেকে ফেরত আসা নির্দিষ্ট অবজেক্টটির কথা বলবেন, তখন 'Tensor' শব্দটি বড় হাতের অক্ষরে লিখবেন এবং এর চারপাশে ব্যাকটিক চিহ্ন দেবেন, কারণ আপনি একটি Tensor অবজেক্টের কথা বলছেন।
একাধিক Tensor অবজেক্ট বোঝাতে ‘Tensors’ (বহুবচন) শব্দটি ব্যবহার করবেন না, যদি না আপনি সত্যিই একটি Tensors অবজেক্টের কথা বলছেন। এর পরিবর্তে বলুন, “ Tensor অবজেক্টের একটি তালিকা (বা সংগ্রহ)”।
একটি টেনসরের অক্ষগুলো বিশদভাবে বর্ণনা করতে ‘shape’ শব্দটি ব্যবহার করুন এবং বর্গাকার বন্ধনীর মধ্যে ব্যাকটিক দিয়ে আকৃতিটি দেখান। উদাহরণস্বরূপ:
If `input` is a three-axis `Tensor` with shape `[3, 4, 3]`, this operation
returns a three-axis `Tensor` with shape `[6, 8, 6]`.
উপরে যেমন বলা হয়েছে, একটি Tensor আকৃতির উপাদানগুলো নিয়ে কথা বলার সময় 'ডাইমেনশন'-এর পরিবর্তে 'অ্যাক্সিস' বা 'ইনডেক্স' ব্যবহার করা শ্রেয়। অন্যথায়, 'ডাইমেনশন'-কে একটি ভেক্টর স্পেসের ডাইমেনশনের সাথে গুলিয়ে ফেলার সম্ভাবনা থাকে। একটি 'ত্রিমাত্রিক ভেক্টর'-এর একটিমাত্র অ্যাক্সিস থাকে, যার দৈর্ঘ্য ৩।