Guida di stile della documentazione TensorFlow

Best practice

  • Focalizzarsi sull'obiettivo degli utilizzatori e l'audience.
  • Usare il linguaggio di tutti i giorni e periodi brevi.
  • Usare costruzione e formulazione del periodo consistenti tra loro e con l'impiego delle maiuscole.
  • Usare titoli e punti elenco in modo da rendere il vostro testo facile da scorrere.
  • La Guida di Stile dello Sviluppatore Google può essere d'aiuto.

Markdown

A meno di poche eccezioni,TensorFlow usa una sintassi di Markdown simile alla GitHub Flavored Markdown (GFM). Questo capitolo spiega le differenze tra la sintassi del Markdown GFM ed il Markdown usato per la documentazione TensorFlow.

Scrivere del codice

Menzione di codice inline

Racchiudere tra `apici inversi` i simboli seguenti nel testo:

  • Nomi di argomenti: `input`, `x`, `tensor`
  • Nomi di tensori restituiti: `output`, `idx`, `out`
  • Tipi di dato: `int32`, `float`, `uint8`
  • Richiami ad operazioni nel testo: `list_diff()`, `shuffle()`
  • Nomi di classi: `tf.Tensor`, `Strategy`
  • Nomi di file: `image_ops.py`, `/path_to_dir/file_name`
  • Espressioni matematiche o condizioni: `-1-input.dims() <= dim <= input.dims()`

Blocchi di codice

Usare tre apici inversi per aprire e chiudere un blocco di codice. Eventualmente, specificare il linguaggio di programmazione dopo il primo gruppo di apici, per esempio:


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

Collegamenti in Markdown

Collegamenti tra file in questo repository

Usare collegamenti relativi tra i file in un repository. Così funzioneranno in tensorflow.org e GitHub:
[Custom layers](../tutorials/eager/custom_layers.ipynb) produce Custom layers sul sito.

Collegamenti alla documentazione sulle API

Quando il sito viene pubblicato, i collegamenti alle API vengono convertiti. Per collegarsi ad un simbolo in una pagina di riferimento di un'API, racchiudere il percorso completo tra apici inversi:

Per API C++, usare il percorso del namespace:

Collegamenti esterni

Per i collegamenti esterni, inclusi i file su https://www.tensorflow.org che non si trovano nel repository tensorflow/docs, usare i collegamenti Markdown standard con l'URI completo.

Per collegamenti al codice sorgente, usare un collegamenti che inizi con https://www.github.com/tensorflow/tensorflow/blob/master/, seguito dal nome del file iniziando dalla radice di GitHub.

Questo schema di nomenclatura degli URI assicura che https://www.tensorflow.org possa indirizzare il collegamento al ramo di codice corrispondente alla versione della documentazione che state guardando.

Non includere i parametri delle query di un URI in un collegamento.

Nei percorsi dei file usare il trattino basso (underscore n.d.t.) al posto degli spazi, per esempio, custom_layers.ipynb.

Includere le estensioni dei file nei collegamenti da usare sul sito e in GitHub, per esempio,
[Custom layers](../tutorials/eager/custom_layers.ipynb).

Matematica nei Markdown

In TensorFlow potete usare MathJax, quando dovete redigere file Markdown, ma fate attenzione a quanto segue:

  • MathJax viene visualizzato bene su tensorflow.org.
  • MathJax non viene visualizzato bene su GitHub.
  • La notazione può scoraggiare sviluppatori che non hanno familiarità con essa.
  • Per consistenza tensorflow.org segue le stesse regole di Jupyter/Colab.

Racchiudere un blocco MathJax tra $$:

$$
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 $$

Racchiudere le espressioni MathJax inline con $ ... $:


Questo è un esempio di espressione MathJax inline: $ 2 \times 2 = 4 $

Questo è un esempio di espressione MathJax inline: $ 2 \times 2 = 4 $

I delimitatori \\( ... \\) funzionano anche per espressioni matematiche inline, anche se la forma $ talvolta è più leggibile.

Nota: Se avete bisogno di un segno dollaro in un testo o in un'espressione MathJax, fatelo precedere da uno slash: \$. I segni dollaro dentro i blocchi di codice (come i nomi delle variabili Bash) possono essere lasciati invariati.

Stile della prosa

Se devi scrivere o modificare una porzione consistente della documentazione narrativa, leggi la Guida di Stile della Documentazione per lo Sviluppatore Google.

Principi di buon stile

  • Controlla l'ortografia e la grammatica tuoi vostri contributi. Molti editor contengono un correttore ortografico o dispongono di un plugin per il controllo. Puoi anche copiare il tuo testo in un Google Doc o in un altro software per documenti per un controllo ortografico e grammaticale più robusto.
  • Usa una voce informale ed amichevole. Scrivi la documentazione come una conversazione uno-ad-uno che tu stia tenendo con un'altra persona. Usa un tono di supporto.

Nota: Essere meno formali non significa essere meno tecnici. Semplifica la tua prosa, non il contenuto tecnico.

  • Evita disconoscimenti, opinioni, e giudizi di valore. Parole come "facilmente", "solo", e "semplice" presuppongono assunzioni. Qualcosa può sembrare semplice a te, ma essere difficile per un'altra persona. Quando possibile, cerca di evitarle.
  • Usa frasi semplici che vanno dirette al punto, senza gerghi complicati. Frasi composte, catene di clausole, e idiomi locali possono rendere il testo difficile da capire e tradurre. Se una frase può essere divisa in due, va probabilmente fatto. Evita i punti e virgola. Usa i punti elenco quando appropriato.
  • Fornisci il contesto. Non usare abbreviazioni senza spiegarle. Non citare progetti che non appartengano a TensorFlow senza collegamenti ad essi. Spiega perché il codice è scritto nel modo in cui lo è.

Guida all'uso

Operazioni

Usa # ⇒ invece di un segno singolo di uguale quando vuoi far vedere ciò che ritorna un'operazione.

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

Tensori

Quando stai parlando di un tensore in genere, non usare la lettera maiuscola per la parola tensore. Quando stai parlando dell'oggetto specifico passato o ritornato da un'operazione, la parola Tensor dovrebbe avere la lettera maiuscola ed essere tra apici inversi, perché stai parlando di un oggetto Tensor.

Non usare la parola Tensors (plurale) per descrivere più oggetti Tensor a meno che tu non stia realmente parlando di un oggetto Tensors object. Scrivi, invece "una lista (o una collezione) di oggetti Tensor".

Usa la parola shape per dettagliare le dimensioni di un tensore, e mostra lo shape tra parentesi quadre con apici inversi. Per esempio:


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