Prerequisiti

Se vuoi contribuire al manuale, avrai bisogno del permesso per modificarlo.

TODO: configura https://www.netlifycms.org/

In ogni caso, dovrai contattarmi con l’indirizzo email associato a github, google, facebook, o twitter per poter modificare, perché Jon deve inserire tale indirizzo email in un file di configurazione affinché tu possa ottenere i poteri di modifica.

Se sei un utente di Plucky, prima di diventare un editor dovresti prima capire che gli editor possono incorporare video o immagini da qualsiasi sito in questo sito. Se questo ti potrebbe creare problemi, potresti voler bloccare video e immagini usando i seguenti comandi.

Tieni anche presente che alcuni utenti di Plucky non sono fluenti in inglese.

Regole

  1. In generale, usa parole minuscole separate da trattini per il nome della pagina in modo che l’URL contenga sempre caratteri minuscoli e non richieda escaping speciale. Non creare pagine con spazi nei nomi. Ad esempio, questa pagina è “editing-the-manual” non “editing the manual”, e il titolo è impostato esplicitamente al nome con spazi nel frontmatter.

  2. Sii coerente. Guarda i documenti esistenti e cerca di formattare il testo in modo simile.

  3. Usa il case della frase per titoli e intestazioni.

  4. Non duplicare blocchi sostanziali di informazioni su più pagine. Il manuale ha una funzione di ricerca ed è un ipertesto. Usa i link per puntare alla fonte autorevole invece di duplicare le informazioni. Ad esempio, invece di descrivere come installare Plucky su faq e su come installare, descrivilo solo nell’ultima e collega ad essa dalla prima. Le eccezioni a questa linea guida sono appropriate per alcune pagine, ad esempio nozioni di base sulla riga di comando, dove avere diversi esempi semplici e introduttivi in una pagina può essere utile per i nuovi utenti.

  5. Evita modifiche solo di spazi bianchi, inclusa la combinazione o la suddivisione di righe nel sorgente. Ogni modifica di pagina viene in realtà trasformata in un commit Git sul server, e le modifiche solo di spazi bianchi rendono l’output di strumenti come Git blame meno utile.

  6. Usa una voce coerente. O la seconda persona (“tu”) o la voce passiva. Nota che attualmente c’è un mix di voci.

  7. Usa fino a 600 caratteri per riga. In emacs, (set-variable 'fill-column 600).

  8. Per gli screencast, usa 1024 x 768 per la risoluzione video – questo mantiene i video leggermente più piccoli e più facili da vedere per coloro che hanno schermi piccoli. Per il formato, preferisci webm, poi mp4. Queste regole possono essere infrante a volte: Jon ha usato 1152x720 e m4v in un video di macOS perché aveva fretta e non sapeva come fare uno screencast se non usando Quicktime. Ma se avesse avuto tempo, avrebbe cambiato questo.

Suggerimenti per gli editor frequenti

Se modifichi molto frequentemente, potresti voler chiedere a Jon dell’accesso ai documenti non tramite browser. È così che Jon aggiorna molte pagine perché è un modo più veloce e potente per modificare molte pagine contemporaneamente.

Dai anche un’occhiata ai link utili qui sotto.

Sezioni specifiche per OS

TODO: FIXME: questo è obsoleto.

Alcune pagine (ad esempio, come installare) hanno sezioni relative a specifici sistemi operativi. Poiché di solito solo una di queste sezioni è rilevante per il lettore, è stato aggiunto JavaScript che può nascondere automaticamente le sezioni non rilevanti in tali pagine, e dare al lettore un pulsante per alternare la visibilità di queste sezioni. I possibili OS sono:

  • Android
  • Chrome OS
  • iOS
  • Linux
  • Mac OS X
  • Windows
  • Windows Phone
  • Sconosciuto
Ultimo aggiornamento: 2026-04-21