Panduan gaya dokumentasi TensorFlow

Praktik terbaik

  • Fokus pada niat pengguna dan audiens.
  • Gunakan kata-kata sehari-hari dan buat kalimat tetap pendek.
  • Gunakan konstruksi kalimat, pemilihan kata, dan penggunaan huruf kapital yang konsisten.
  • Gunakan judul dan daftar untuk membuat dokumen Anda lebih mudah dipindai.
  • Panduan Gaya Google Developer Docs sangat membantu.

Penurunan harga

Dengan beberapa pengecualian, TensorFlow menggunakan sintaks Markdown yang mirip dengan GitHub Flavored Markdown (GFM). Bagian ini menjelaskan perbedaan antara sintaks Markdown GFM dan Markdown yang digunakan untuk dokumentasi TensorFlow.

Tulis tentang kode.

Penyebutan kode secara langsung

Gunakan tanda `backticks` di sekitar simbol-simbol berikut saat digunakan dalam teks:

  • Nama argumen: `input` , `x` , `tensor`
  • Nama tensor yang dikembalikan: `output` , `idx` , `out`
  • Tipe data: `int32` , `float` , `uint8`
  • Nama operasi lain yang dirujuk dalam teks: `list_diff()` , `shuffle()`
  • Nama kelas: `tf.Tensor` , `Strategy`
  • Nama file: `image_ops.py` , `/path_to_dir/file_name`
  • Ekspresi atau kondisi matematika: `-1-input.dims() <= dim <= input.dims()`

Blok kode

Gunakan tiga tanda backtick untuk membuka dan menutup blok kode. Secara opsional, tentukan bahasa pemrograman setelah kelompok backtick pertama, misalnya:


```python
# some python code here
```

Gunakan tautan relatif antar file dalam satu repositori GitHub. Sertakan ekstensi file.

Sebagai contoh, file yang Anda baca ini berasal dari repositori https://github.com/tensorflow/docs . Oleh karena itu, file ini dapat menggunakan jalur relatif untuk menautkan ke file lain di repositori yang sama seperti ini:

  • [Basics](../../guide/basics.ipynb) menghasilkan Basics .

Ini adalah pendekatan yang lebih disukai karena dengan cara ini tautan di tensorflow.org , GitHub , dan Colab semuanya berfungsi. Selain itu, pembaca tetap berada di situs yang sama saat mereka mengklik tautan.

Untuk tautan ke file yang tidak ada di repositori saat ini, gunakan tautan Markdown standar dengan URI lengkap. Lebih baik menautkan ke URI tensorflow.org jika tersedia.

Untuk menautkan ke kode sumber, gunakan tautan yang diawali dengan https://www.github.com/tensorflow/tensorflow/blob/master/ , diikuti dengan nama file yang diawali dari direktori root GitHub.

Saat membuat tautan dari tensorflow.org , sertakan `` pada tautan Markdown agar simbol "tautan eksternal" ditampilkan.

  • [GitHub](https://github.com/tensorflow/docs) menghasilkan GitHub

Jangan sertakan parameter kueri URI dalam tautan:

  • Gunakan: https://www.tensorflow.org/guide/data
  • Bukan: https://www.tensorflow.org/guide/data?hl=en

Gambar

Saran pada bagian sebelumnya berlaku untuk tautan ke halaman. Gambar ditangani secara berbeda.

Secara umum, Anda sebaiknya tidak menyertakan gambar dalam kode, tetapi tambahkan tim TensorFlow-Docs ke PR Anda, dan minta mereka untuk mengunggah gambar ke tensorflow.org . Ini membantu menjaga ukuran repositori Anda tetap kecil.

Jika Anda mengirimkan gambar ke repositori Anda, perhatikan bahwa beberapa sistem tidak menangani jalur relatif ke gambar. Lebih baik gunakan URL lengkap yang mengarah ke lokasi akhir gambar di tensorflow.org .

Tautan API dikonversi saat situs dipublikasikan. Untuk menautkan ke halaman referensi API suatu simbol, sertakan jalur simbol dalam tanda kutip terbalik (` `):

Jalur lengkap sedikit lebih disukai kecuali untuk jalur yang panjang. Jalur dapat disingkat dengan menghilangkan komponen jalur di bagian depan. Jalur parsial akan diubah menjadi tautan jika:

  • Setidaknya ada satu titik ( . di jalur tersebut, dan
  • Jalur parsial ini unik di dalam proyek tersebut.

Jalur API dihubungkan untuk setiap proyek dengan API Python yang dipublikasikan di tensorflow.org . Anda dapat dengan mudah menautkan ke beberapa subproyek dari satu file dengan membungkus nama API dengan tanda backtick. Misalnya:

Untuk simbol dengan beberapa alias jalur, ada sedikit preferensi untuk jalur yang sesuai dengan halaman API di tensorflow.org . Semua alias akan mengarahkan ke halaman yang benar.

Matematika dalam Markdown

Anda dapat menggunakan MathJax di dalam TensorFlow saat mengedit file Markdown, tetapi perhatikan hal berikut:

  • MathJax ditampilkan dengan benar di tensorflow.org .
  • MathJax tidak ditampilkan dengan benar di GitHub.
  • Notasi ini bisa membingungkan bagi pengembang yang belum terbiasa.
  • Demi konsistensi, tensorflow.org mengikuti aturan yang sama seperti Jupyter/Colab.

Gunakan $$ di sekitar blok 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 \]

Bungkus ekspresi MathJax sebaris dengan $ ... $ :


This is an example of an inline MathJax expression: $ 2 \times 2 = 4 $

Ini adalah contoh ekspresi MathJax inline: \( 2 \times 2 = 4 \)

Pembatas \\( ... \\) juga berfungsi untuk matematika sebaris, tetapi bentuk $ terkadang lebih mudah dibaca.

Gaya prosa

Jika Anda akan menulis atau mengedit sebagian besar dokumentasi naratif, harap baca Panduan Gaya Dokumentasi Pengembang Google .

Prinsip-prinsip gaya yang baik

  • Periksa ejaan dan tata bahasa dalam kontribusi Anda. Sebagian besar editor menyertakan pemeriksa ejaan atau memiliki plugin pemeriksa ejaan yang tersedia. Anda juga dapat menempelkan teks Anda ke Google Docs atau perangkat lunak dokumen lainnya untuk pemeriksaan ejaan dan tata bahasa yang lebih menyeluruh.
  • Gunakan gaya bahasa yang santai dan ramah. Tulis dokumentasi TensorFlow seperti percakapan—seolah-olah Anda sedang berbicara dengan orang lain secara langsung. Gunakan nada yang mendukung dalam artikel tersebut.
  • Hindari pernyataan penafian, opini, dan penilaian nilai. Kata-kata seperti "mudah", "hanya", dan "sederhana" sarat dengan asumsi. Sesuatu mungkin tampak mudah bagi Anda, tetapi bisa sulit bagi orang lain. Cobalah untuk menghindari hal-hal ini sebisa mungkin.
  • Gunakan kalimat sederhana dan langsung ke intinya tanpa jargon yang rumit. Kalimat majemuk, rangkaian klausa, dan idiom spesifik lokasi dapat membuat teks sulit dipahami dan diterjemahkan. Jika sebuah kalimat dapat dibagi menjadi dua, sebaiknya dibagi. Hindari penggunaan titik koma. Gunakan daftar poin jika sesuai.
  • Berikan konteks. Jangan menggunakan singkatan tanpa menjelaskannya. Jangan menyebutkan proyek non-TensorFlow tanpa memberikan tautan ke proyek tersebut. Jelaskan mengapa kode ditulis seperti itu.

Panduan penggunaan

Operasi

Dalam file markdown, gunakan # ⇒ sebagai pengganti tanda sama dengan tunggal jika Anda ingin menunjukkan nilai kembalian dari suatu operasi.

# 'input' is a tensor of shape [2, 3, 5]
tf.expand_dims(input, 0)  # ⇒ [1, 2, 3, 5]

Di buku catatan, tampilkan hasilnya alih-alih menambahkan komentar (Jika ekspresi terakhir dalam sel buku catatan tidak ditetapkan ke variabel, ekspresi tersebut akan ditampilkan secara otomatis.)

Dalam dokumentasi referensi API, lebih baik menggunakan doctest untuk menampilkan hasilnya.

Tensor

Saat membicarakan tensor secara umum, jangan menggunakan huruf kapital pada kata "tensor" . Namun, saat membicarakan objek spesifik yang diberikan atau dikembalikan dari suatu operasi, Anda harus menggunakan huruf kapital pada kata "Tensor" dan menambahkan tanda kutip terbalik di sekitarnya karena Anda sedang membicarakan objek Tensor .

Jangan gunakan kata Tensor (jamak) untuk mendeskripsikan beberapa objek Tensor kecuali Anda benar-benar sedang membicarakan satu objek Tensors . Sebaliknya, katakan "daftar (atau koleksi) objek Tensor ".

Gunakan kata " bentuk" untuk menjelaskan sumbu-sumbu tensor, dan tunjukkan bentuknya dalam tanda kurung siku dengan tanda backtick. Misalnya:


If `input` is a three-axis `Tensor` with shape `[3, 4, 3]`, this operation
returns a three-axis `Tensor` with shape `[6, 8, 6]`.

Seperti yang telah disebutkan di atas, lebih baik gunakan "sumbu" atau "indeks" daripada "dimensi" ketika berbicara tentang elemen-elemen bentuk Tensor . Jika tidak, mudah untuk mengacaukan "dimensi" dengan dimensi ruang vektor. "Vektor tiga dimensi" memiliki satu sumbu dengan panjang 3.