Save the date! Google I/O returns May 18-20 Register now
Halaman ini diterjemahkan oleh Cloud Translation API.
Switch to English

Panduan gaya dokumentasi TensorFlow

Praktik terbaik

  • Fokus pada niat pengguna dan audiens.
  • Gunakan kata-kata sehari-hari dan buat kalimat pendek.
  • Gunakan konstruksi kalimat, kata-kata, dan kapitalisasi yang konsisten.
  • Gunakan tajuk dan daftar untuk membuat dokumen Anda lebih mudah dipindai.
  • Panduan Gaya Dokumen Pengembang Google 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

Sebutan kode sebaris

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

  • Nama argumen: `input` , `x` , `tensor`
  • Nama tensor yang ditampilkan: `output` , `idx` , `out`
  • Jenis data: `int32` , `float` , `uint8`
  • Referensi nama op lain 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 backticks 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 repositori. Ini berfungsi di tensorflow.org dan GitHub :
[Custom layers](../tutorials/eager/custom_layers.ipynb) menghasilkan lapisan Kustom di situs.

Tautan API diubah ketika situs dipublikasikan. Untuk menautkan ke halaman referensi API simbol, apit jalur simbol lengkap di backticks:

Untuk C ++ API, gunakan jalur namespace:

Untuk tautan eksternal, termasuk file di https://www.tensorflow.org yang tidak ada di repositori tensorflow/docs , gunakan tautan Penurunan Harga standar dengan URI lengkap.

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.

Skema penamaan URI ini memastikan bahwa https://www.tensorflow.org dapat meneruskan tautan ke cabang kode yang sesuai dengan versi dokumentasi yang Anda lihat.

Jangan sertakan parameter kueri URI di tautan.

Jalur file menggunakan garis bawah untuk spasi, misalnya, custom_layers.ipynb .

Sertakan ekstensi file dalam tautan untuk digunakan di situs dan GitHub, misalnya,
[Custom layers](../tutorials/eager/custom_layers.ipynb) .

Matematika dalam penurunan harga

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

  • MathJax merender dengan benar di tensorflow.org .
  • MathJax tidak dirender dengan baik di GitHub.
  • Notasi ini dapat mengganggu pengembang yang tidak dikenal.
  • Untuk konsistensi tensorflow.org mengikuti aturan yang sama seperti Jupyter / Colab.

Gunakan $$ 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 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 gaya yang baik

  • Periksa ejaan dan tata bahasa dalam kontribusi Anda. Kebanyakan editor menyertakan pemeriksa ejaan atau memiliki plugin pemeriksa ejaan yang tersedia. Anda juga dapat menempelkan teks Anda ke dalam Google Doc atau perangkat lunak dokumen lain 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 dengan orang lain secara pribadi. Gunakan nada suportif dalam artikel.
  • Hindari penafian, opini, dan penilaian nilai. Kata-kata seperti "mudah", "hanya", dan "sederhana" sarat dengan asumsi. Sesuatu mungkin tampak mudah bagi Anda, tetapi sulit bagi orang lain. Cobalah untuk menghindari ini jika memungkinkan.
  • Gunakan kalimat sederhana dan langsung tanpa jargon yang rumit. Kalimat gabungan, rantai klausa, dan idiom khusus lokasi dapat membuat teks sulit untuk dipahami dan diterjemahkan. Jika sebuah kalimat dapat dibagi menjadi dua, mungkin itu seharusnya. Hindari titik koma. Gunakan daftar poin jika perlu.
  • Berikan konteks. Jangan gunakan singkatan tanpa menjelaskannya. Jangan sebutkan project non-TensorFlow tanpa menautkannya. Jelaskan mengapa kode ditulis seperti itu.

Panduan penggunaan

Ops

Dalam file penurunan harga, gunakan # ⇒ alih-alih satu tanda sama dengan ketika Anda ingin menunjukkan apa yang dikembalikan op.

# '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 akan ditampilkan secara otomatis.)

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

Tensor

Saat Anda berbicara tentang tensor secara umum, jangan gunakan huruf besar untuk kata tensor . Saat Anda berbicara tentang objek tertentu yang disediakan atau dikembalikan dari sebuah operasi, Anda harus menggunakan huruf besar dari kata Tensor dan menambahkan backtick di sekitarnya karena Anda sedang membicarakan objek Tensor .

Jangan gunakan Tensors kata (plural) untuk menggambarkan beberapa Tensor objek kecuali jika Anda benar-benar berbicara tentang Tensors objek. Sebagai gantinya, ucapkan "daftar (atau kumpulan) objek Tensor ".

Gunakan bentuk kata untuk merinci sumbu tensor, dan perlihatkan bentuk dalam tanda kurung siku dengan backticks. Sebagai contoh:


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, pilih "sumbu" atau "indeks" daripada "dimensi" saat berbicara tentang elemen bentuk Tensor . Jika tidak, mudah untuk mengacaukan "dimensi" dengan dimensi ruang vektor. Sebuah "vektor tiga dimensi" memiliki satu sumbu dengan panjang 3.