Contribuire alla documentazione di Minecraft Bedrock

Ti diamo il benvenuto nel repository pubblico per la documentazione di Minecraft Bedrock! Tutti gli articoli che crei o modifichi in questo repository saranno visibili al pubblico.

I documenti di Minecraft Bedrock si trovano nella piattaforma docs.microsoft.com, che utilizza GitHub-flavored Markdown con le funzionalità di Markdig. Il contenuto che modifichi in questo repository verrà formattato in pagine stilizzate di Microsoft Docs, visualizzate in Documenti Minecraft Bedrock. Il contenuto creato da te e da altri membri della community Bedrock verrà pubblicato come parte dei nostri contenuti e degli aggiornamenti di Minecraft: Bedrock Edition.

Questa pagina descrive i passaggi e le linee guida da seguire per apportare il proprio contributo, oltre ai link per apprendere i fondamenti di Markdown. Grazie per il tuo contributo!

Repository disponibili

Nome del repository	URL
Documenti Minecraft Bedrock	https://github.com/MicrosoftDocs/minecraft-creator

Prima di iniziare

Se non ne hai già uno, dovrai creare un account GitHub.

Durante la configurazione del tuo account GitHub, ti consigliamo inoltre di adottare le seguenti precauzioni:

Crea una password sicura per il tuo account Github.
Abilita l’autenticazione a due fattori.
Salva i tuoi codici di recupero in un luogo sicuro.
Aggiorna le impostazioni del tuo profilo pubblico.
- Imposta il tuo nome e considera l'eventualità di non mostrare la tua e-mail pubblica, selezionando Non mostrare il mio indirizzo e-mail dalle impostazioni.
- Poiché nelle pagine a cui contribuisci verrà mostrata una miniatura della tua immagine profilo, ti consigliamo di caricarne una.
Se prevedi di utilizzare la riga di comando, considera l'eventualità di configurare Git Credential Manager per Windows. In questo modo, non dovrai inserire la tua password ogni volta che apporti un contributo.

Il sistema di pubblicazione è collegato a GitHub, quindi è importante seguire questi passaggi. Sarai menzionato come autore o collaboratore di ogni articolo con il tuo alias GitHub.

Modificare un articolo esistente

Segui i passaggi qui riportati per aggiornare un articolo esistente in un browser web con GitHub:

Seleziona l’articolo che desideri modificare in Documenti del Creatore Minecraft.
Fai clic sul pulsante Modifica (icona a forma di matita) in alto a destra, che biforcherà automaticamente uno dei rami disponibili presenti nel ramo “main”.

Pulsante Modifica portale di apprendimento

Modifica il contenuto dell’articolo e il formato in base ai fondamenti di Markdown.
Aggiorna i metadati nella parte superiore di ogni articolo:
- titolo: Titolo della pagina che appare nella scheda del browser durante la visualizzazione dell’articolo. I titoli delle pagine vengono utilizzati per l'ottimizzazione in ottica SEO e l’indicizzazione. Per questo motivo è importante non modificare il titolo se non strettamente necessario (sebbene sia meno grave farlo prima di pubblicare la documentazione).
- descrizione: Descrivi brevemente il contenuto dell’articolo, per migliorare l'ottimizzazione SEO e permettere agli utenti di scoprirti.
- autore: Se sei il proprietario principale della pagina, aggiungi qui il tuo alias GitHub.
- ms.author: Se sei il proprietario principale della pagina, aggiungi qui il tuo alias Microsoft (non serve inserire @microsoft.com, è sufficiente l’alias).
- ms.data: Aggiorna la data solo se stai aggiungendo contenuti importanti alla pagina, non in caso di correzioni, come chiarimenti, formattazione, grammatica o ortografia.
- parole chiave: Le parole chiave contribuiscono alla SEO (ottimizzazione per i motori di ricerca). Aggiungi parole chiave specifiche per il tuo articolo, separandole tra loro con una virgola e uno spazio, senza inserire segni di punteggiatura dopo l’ultima parola chiave dell’elenco. Non è necessario aggiungere parole chiave globali adatte a tutti gli articoli, poiché quelle vengono gestite altrove.
Una volta apportate tutte le modifiche necessarie all’articolo, scorri verso il basso e seleziona Proponi modifica file.
Nella pagina successiva, seleziona Crea richiesta di pull per unire il ramo creato automaticamente al “main”.
Ripeti i passaggi precedenti per modificare qualunque altro articolo.

Rinominare o eliminare un articolo esistente

Se la tua modifica consiste nel rinominare o eliminare un articolo esistente, assicurati di aggiungere un reindirizzamento. In questo modo, chiunque possegga un link all’articolo esistente raggiungerà comunque la pagina giusta. I reindirizzamenti sono gestiti dal file .openpublishing.redirection.json, che si trova nella radice del repository.

Per aggiungere un reindirizzamento a .openpublishing.redirection.json, aggiungi una voce alla matrice redirections:

{
    "redirections": [
        {
            "source_path": "minecraft-creator/creator/old-article.md",
            "redirect_url": "new-article#section-about-old-topic",
            "redirect_document_id": false
        },

Il source_path è il percorso del repository relativo al vecchio articolo che stai rimuovendo. Assicurati che il percorso inizi con minecraft-creator/creator e finisca con .md.
Il redirect_url è l’URL pubblico che reindirizza dal vecchio articolo al nuovo articolo. Assicurati che questo URL non contenga minecraft-creator/creator o .md, poiché fa riferimento all’URL pubblico e non al percorso del repository. È consentito inserire il collegamento a una sezione all’interno del nuovo articolo utilizzando il comando #section. Se necessario, in questa sede è inoltre possibile utilizzare un percorso assoluto verso un altro sito.
redirect_document_id indica se desideri mantenere l’ID del documento del file precedente. L’impostazione predefinita è false. Utilizza true se desideri preservare il valore dell’attributo ms.documentid dell’articolo reindirizzato. Se conservi l’ID del documento, i dati, come il numero di visualizzazioni e il ranking della pagina, verranno trasferiti all’articolo di destinazione. Esegui questa operazione se lo scopo del reindirizzamento è principalmente quello di rinominare un articolo, non di trasferire l'utente sulla pagina di un articolo diverso e solo in parte correlato al primo.

Se aggiungi un reindirizzamento, assicurati inoltre di avere eliminato il vecchio file.

Creare un nuovo articolo

Segui i passaggi qui riportati per creare nuovi articoli nel repository della documentazione con GitHub utilizzando un browser web:

Crea una biforcazione del ramo “main” MicrosoftDocs/minecraft-creator (usando il pulsante Fork in alto a destra).

Pulsante Fork di GitHub

Nella cartella “creatore/Documenti”, seleziona Aggiungi file > Crea nuovo file in alto a destra.
Dai un nome alla pagina dell’articolo (usa i trattini al posto degli spazi e non usare punteggiatura o apostrofi) e aggiungi “.md”

Importante

Assicurati di creare il nuovo articolo all'interno della cartella “creatore/Documenti”. Per controllare di averlo fatto, verifica la presenza di “/creatore/Documenti” nel nome del nuovo file.

Nella parte superiore della nuova pagina, aggiungi il seguente blocco di metadati:

---
title:
description:
author:
ms.author:
ms.date:
ms.topic: article
keywords:
---

Compila i campi dei metadati pertinenti seguendo le istruzioni riportate nella sezione precedente.
Scrivi il contenuto dell’articolo utilizzando i fondamenti di Markdown.
Aggiungi una sezione ## See also in fondo all’articolo con link ad altri articoli pertinenti.
Una volta che avrai finito di scrivere il tuo articolo, seleziona Conferma nuovo file.
Seleziona Nuova richiesta di pull e unisci il ramo “main” della tua biforcazione al “main” di MicrosoftDocs/minecraft-creator (assicurati che la freccia indichi la direzione corretta).

Richiesta di pull su GitHub

La tua richiesta di pull verrà esaminata dal nostro Content team. Se approvata, le modifiche saranno pubblicate al rilascio della nuova versione aggiornata. Se la richiesta di pull non viene approvata, un membro del team dei contenuti lascerà un commento nella stessa comunicandoti il motivo della decisione.

Fondamenti di Markdown

Con le seguenti risorse potrai imparare a modificare la documentazione utilizzando il linguaggio Markdown:

Aggiungere tabelle

Lo stile delle tabelle di docs.microsoft.com non prevede bordi o stili personalizzati, neanche se provi CSS in linea. Lo stile sembrerà funzionare per un breve periodo di tempo, ma alla fine la piattaforma lo eliminerà dalla tabella. Fai tesoro di questa informazione e crea tabelle semplici. Ecco un sito che semplifica la creazione di tabelle Markdown.

L’estensione Docs Markdown per Visual Studio Code semplifica persino la creazione di tabelle, se per modificare la documentazione si utilizza Visual Studio Code (vedi sotto).

|Title 1 |Title 2| Title 3|
|--------|-------|--------|
|This will |Show a three |column table|

Aggiungere immagini

Dovrai caricare le tue immagini nella cartella “minecraft-creator/creator/images” nel repository, facendovi poi riferimento in modo appropriato nell’articolo. Le immagini verranno visualizzate automaticamente in full-size, di conseguenza l'intera l'articolo si riempirà di immagini molto grandi. Ti consigliamo di ridimensionare le immagini prima di caricarle. La larghezza consigliata è compresa tra 600 e 700 pixel, anche se ti consigliamo di aumentare o diminuire le dimensioni se si tratta, rispettivamente, di uno screenshot scuro o di una frazione di screenshot.

Importante

È possibile caricare immagini nel repository biforcato solo prima dell’unione. Quindi, se hai intenzione di aggiungere immagini a un articolo, dovrai usare Visual Studio Code per aggiungere prima le immagini alla cartella “immagini” della biforcazione oppure assicurarti di avere seguito questi passaggi in un browser web:

Avere eseguito la biforcazione del repository MicrosoftDocs/minecraft-creator.
Avere modificato l’articolo nella tua biforcazione.
Avere caricato nella cartella “minecraft-creator/creator/images” della tua biforcazione le immagini a cui fai riferimento nell'articolo.
Avere creato una richiesta di pull per unire la tua biforcazione al ramo “main” MicrosoftDocs/minecraft-creator.

Per sapere come impostare il tuo repository biforcato, segui le istruzioni per la creazione di un nuovo articolo.

Visualizzare l'anteprima del tuo lavoro

Durante la modifica in GitHub con un browser web, puoi selezionare la scheda Anteprima nella parte superiore della pagina per visualizzare il tuo lavoro prima di effettuare il commit.

Nota

L’anteprima delle modifiche su review.docs.microsoft.com è disponibile solo per i dipendenti Microsoft

Dipendenti Microsoft: una volta che i vostri contributi sono stati uniti al ramo “main”, è possibile esaminare il contenuto prima che diventi pubblico su https://github.com/MicrosoftDocs/minecraft-creator/tree/main/creator. Puoi trovare il tuo articolo utilizzando l’indice nella colonna di sinistra.

Differenze tra la modifica in un browser web e la modifica con un client desktop

Il browser è lo strumento più semplice e rapido per apportare modifiche, tuttavia, presenta alcuni svantaggi:

Non hai a disposizione il controllo ortografico.
Non hai a disposizione alcun collegamento intelligente ad altri articoli (devi digitare manualmente il nome del file dell’articolo).
Può essere faticoso caricare le immagini e creare dei riferimenti.

Se vuoi evitare questi problemi durante la pubblicazione di un contributo, usa un client desktop come Visual Studio Code con alcune estensioni utili.

Usare Visual Studio Code

Per i motivi sopra elencati, per modificare la documentazione potresti preferire l’utilizzo di un client desktop a quello di un browser web. Noi consigliamo di utilizzare Visual Studio Code.

Configurazione

Segui questi passaggi per configurare Visual Studio Code in modo da renderlo compatibile con questo repository:

In un browser web:

a. Installa Git per il tuo PC.

b. Installa Visual Studio Code.

c. Se non lo hai già fatto, esegui la biforcazione di MicrosoftDocs/minecraft-creator.

d. Nella tua biforcazione, seleziona Clona oppure scarica e copia l’URL.
Crea un clone locale della tua biforcazione in Visual Studio Code:

a. Dal menu Visualizza, seleziona Riquadro comandi.

b. Digita “Git: Clona”.

c. Incolla l’URL che hai copiato.

d. Scegli dove salvare il clone sul tuo PC.

e. Seleziona Apri repository nel pop-up.

Modificare la documentazione

Segui i passaggi qui riportati per apportare modifiche alla documentazione con Visual Studio Code: