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, susunan kata, dan penggunaan huruf besar yang konsisten.
  • Gunakan judul dan daftar untuk membuat dokumen Anda lebih mudah dipindai.
  • Panduan Gaya Dokumen Pengembang Google sangat membantu.

Penurunan harga

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

Tulis tentang kode

Penyebutan kode sebaris

Letakkan `backticks` di sekitar simbol berikut saat digunakan dalam teks:

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

Blok kode

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


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

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

Misalnya, file yang Anda baca ini berasal dari repositori https://github.com/tensorflow/docs . Oleh karena itu, ia 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 ketika mereka mengklik sebuah link.

Untuk link ke file yang tidak ada dalam repositori saat ini, gunakan link Markdown standar dengan URI lengkap. Lebih suka menautkan ke URI tensorflow.org jika tersedia.

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

Saat menautkan tensorflow.org , sertakan `` pada tautan Penurunan harga sehingga simbol "tautan eksternal" ditampilkan.

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

Jangan sertakan parameter kueri URI di tautan:

  • Gunakan: <a href="https://www.tensorflow.org/guide/data">https://www.tensorflow.org/guide/data</a>
  • Tidak: <a href="https://www.tensorflow.org/guide/data?hl=en">https://www.tensorflow.org/guide/data?hl=en</a>

Gambar

Saran di bagian sebelumnya adalah untuk link ke halaman. Gambar ditangani secara berbeda.

Umumnya, Anda tidak boleh memeriksa gambar, melainkan menambahkan tim TensorFlow-Docs ke PR Anda, dan meminta mereka untuk menghosting gambar di tensorflow.org . Ini membantu memperkecil ukuran repositori Anda.

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

Tautan API dikonversi saat situs dipublikasikan. Untuk menautkan ke halaman referensi API simbol, sertakan jalur simbol di backticks:

Jalur penuh sedikit lebih disukai kecuali jalur panjang. Jalur dapat disingkat dengan menghilangkan komponen jalur utama. Jalur parsial akan dikonversi menjadi tautan jika:

  • Setidaknya ada satu . di jalan, dan
  • Jalur parsial bersifat unik dalam proyek ini.

Jalur API ditautkan untuk setiap proyek dengan API Python yang dipublikasikan di tensorflow.org . Anda dapat dengan mudah menautkan ke beberapa subproyek dari satu file dengan menggabungkan nama API dengan backticks. Misalnya:

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

Matematika dalam Penurunan Harga

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

  • MathJax ditampilkan dengan benar di tensorflow.org .
  • MathJax tidak ditampilkan dengan benar di GitHub.
  • Notasi ini mungkin tidak menyenangkan bagi pengembang yang tidak terbiasa.
  • Untuk 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 sebaris: \( 2 \times 2 = 4 \)

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

Gaya prosa

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

Prinsip gaya yang baik

  • Periksa ejaan dan tata bahasa dalam kontribusi Anda. Kebanyakan editor menyertakan pemeriksa ejaan atau menyediakan plugin pemeriksa ejaan. Anda juga dapat menempelkan teks Anda ke Google Dokumen atau perangkat lunak dokumen lainnya untuk pemeriksaan ejaan dan tata bahasa yang lebih baik.
  • Gunakan suara yang santai dan ramah. Tulis dokumentasi TensorFlow seperti percakapan—seolah-olah Anda sedang berbicara empat mata dengan orang lain. Gunakan nada yang mendukung dalam artikel.
  • Hindari penafian, opini, dan penilaian nilai. Kata-kata seperti “mudah”, “adil”, dan “sederhana” sarat dengan asumsi. Sesuatu mungkin tampak mudah bagi Anda, namun sulit bagi orang lain. Cobalah untuk menghindari ini bila memungkinkan.
  • Gunakan kalimat yang sederhana dan to the point tanpa jargon yang rumit. Kalimat majemuk, rangkaian klausa, dan idiom spesifik lokasi dapat membuat teks sulit dipahami dan diterjemahkan. Jika sebuah kalimat dapat dipecah menjadi dua, mungkin memang demikian. Hindari titik koma. Gunakan daftar poin bila diperlukan.
  • Berikan konteks. Jangan gunakan singkatan tanpa menjelaskannya. Jangan menyebut proyek non-TensorFlow tanpa menautkannya. Jelaskan mengapa kode tersebut ditulis seperti itu.

Panduan penggunaan

Operasi

Dalam file penurunan harga, gunakan # ⇒ alih-alih satu tanda sama dengan ketika Anda ingin menunjukkan hasil 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, maka ekspresi tersebut akan ditampilkan secara otomatis.)

Dalam dokumen referensi API, lebih suka menggunakan doctest untuk menampilkan hasil.

Tensor

Saat Anda berbicara tentang tensor secara umum, jangan menggunakan huruf besar pada kata tensor . Saat Anda berbicara tentang objek spesifik yang disediakan atau dikembalikan dari operasi, Anda harus menggunakan huruf kapital pada kata Tensor dan menambahkan tanda tik terbalik di sekitarnya karena Anda sedang berbicara tentang objek Tensor .

Jangan gunakan kata Tensor (jamak) untuk mendeskripsikan beberapa objek Tensor kecuali Anda benar-benar membicarakan tentang objek Tensors . Sebagai gantinya, ucapkan "daftar (atau kumpulan) objek Tensor ".

Gunakan kata bentuk untuk merinci sumbu tensor, dan perlihatkan bentuk dalam tanda kurung siku dengan tanda tik terbalik. 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 di atas, pilihlah "sumbu" atau "indeks" daripada "dimensi" ketika berbicara tentang elemen bentuk Tensor . Kalau tidak, mudah untuk mengacaukan "dimensi" dengan dimensi ruang vektor. Sebuah "vektor tiga dimensi" memiliki sumbu tunggal dengan panjang 3.