Processo per le Guide
Scopri qui il processo per contribuire ai nostri ZAP-Docs. Il processo è scritto in ordine cronologico, quindi ti consigliamo di partire da questa pagina.
Passo 1: Suggerire Contenuti
La prima fase consiste nel creare un issue di suggerimento tramite il nostro repository GitHub. Devi fornirci dettagli sulle modifiche e miglioramenti che intendi proporre.
Assicurati che la tua idea non sia un duplicato di guide o suggerimenti esistenti e che credi davvero possa essere utile sia ai principianti che agli utenti più esperti. Puoi vedere i suggerimenti già presenti andando alla Pagina Issues.
Ti consigliamo di leggere le nostre Linee Guida per capire lo stile di contenuto e documentazione che seguiamo.
Che argomenti cerchiamo?
Cerchiamo guide pratiche e di alta qualità che coprano prodotti, servizi e software open-source disponibili tramite ZAP-Hosting o correlati ai nostri servizi. Se ti serve ispirazione, dai un’occhiata alle nostre pagine su ZAP-Docs per capire lo stile e il tipo di contenuti che pubblichiamo.
Come detto nell’introduzione, tutto il contenuto deve essere originale per rispettare le leggi sul copyright. È vietato l’uso non autorizzato di AI/generative tools o altre proprietà intellettuali. Le nostre guide vogliono fornire info top passo dopo passo, così il lettore capisce cosa fa e come farlo, con l’obiettivo di educare e risolvere.
Lista Guide Richieste
Qui sotto trovi una lista utile di suggerimenti per nuove guide che potresti voler scrivere. Alcuni argomenti potrebbero anche avere un bonus extra come ricompensa. Puoi accedere alla lista manualmente qui.
Ricorda, sono solo idee utili, non devi per forza scrivere su questi argomenti, i tuoi suggerimenti possono essere creativi come detto prima.
Come inviare un suggerimento
Sei sicuro che il tuo suggerimento è adatto alla nostra documentazione? Allora vai al nostro repository ZAP Docs su GitHub e apri un issue usando il template Contribution Suggestion. Segui il template e compila tutti i dettagli necessari. Ti verrà chiesto anche di confermare l’accettazione dei nostri Termini & Condizioni per il Programma di Contributo, che trovi qui: Contribution Terms.
Assicurati di inserire correttamente il tuo ZAP ID per ricevere la ricompensa sull’account giusto!
Dopo aver inviato il suggerimento, puntiamo a risponderti entro 3-5 giorni direttamente nel tuo issue su GitHub.
Problemi? Unisciti al nostro Discord ZAP-Hosting, noi e la community saremo felici di aiutarti. Oppure apri un ticket sul sito e scrivi "Contribution Program - Guides" per essere indirizzato al team contributi.
Nella risposta ti daremo feedback o dettagli da modificare. Se ci sono problemi, ti contatteremo direttamente nel tuo issue.
Passo 2: Scrivere la Guida
Quando aggiungi o modifichi contenuti, segui sempre le nostre Linee Guida per mantenere coerenza e qualità. Qui approfondiamo best practice e workflow ottimale per creare o modificare contenuti. Se sei nuovo su GitHub, usa i tutorial qui sotto per capire come editare o creare contenuti per ZAP-Docs.
Assicurati di aver creato un suggerimento sul nostro GitHub Repository e che sia stato approvato da un membro del Team Contributi ZAP prima di lavorare su una guida o modifica. Senza approvazione non possiamo garantire la ricompensa.
Prerequisiti:
Il primo passo è creare un fork del repository ZAP-Docs su GitHub. Vai al repository ZAP Docs e clicca su Fork in alto.
Dai un nome al repository basato sul suggerimento accettato e spunta Copy the master branch only. Poi clicca crea e aspetta qualche secondo.
Con il tuo fork pronto, puoi procedere. Ci sono due modi principali per creare contenuti: direttamente via sito GitHub o clonando il repo localmente. Il primo è più user-friendly, il secondo ti permette di testare Docusaurus in locale e vedere le modifiche live.
Per chi è alle prime armi o poco esperto con Git, consigliamo Metodo 1: scrivere direttamente via GitHub, è più semplice, veloce e tutto fatto dal browser.
Modi per Creare Guide
- Metodo 1: Direttamente via GitHub
- Metodo 2: Localmente via IDE (git clone)
Il modo più semplice e consigliato è usare il sito GitHub. Qui ti spieghiamo come creare una guida nuova o modificare una esistente.
Vai al tuo fork creato prima. Dentro troverai tutte le guide nella cartella docs.
I file seguono una convenzione semplice: la prima parola indica il tipo di guida (di solito gioco, prodotto o sezione), le parole successive la sezione specifica. Ti consigliamo di guardare il nostro sito live ZAP-Docs per capire dove inserire la guida. Per esempio, dedicated-windows.md è per server dedicati Windows.
Ora devi aprire un file esistente o crearne uno nuovo, a seconda se aggiorni o crei una guida. Usa la tab giusta qui sotto per le istruzioni, perché creare una guida nuova richiede qualche passaggio in più.
- Crea un file guida nuovo
- Modifica un file guida esistente
Esempio: vogliamo creare una guida nuova per il gioco Rust, sui comandi disponibili. Controllando il sito o repo, vediamo che esiste già una sezione Rust sotto game servers. Seguendo la convenzione, il file si chiamerà rust-commands.md.
Per creare il file, vai al repository GitHub, apri la cartella docs e a destra clicca Add File > Create new file.
In alto imposta il nome del file, es. rust-commands.md.
Ricordati di aggiungere l’estensione .md perché tutte le guide sono in Markdown.
Ora devi aggiungere i metadati all’inizio del file. Il modo più semplice è aprire un file simile come rust-plugins.md, copiare i metadati in cima e modificarli per la tua guida. L’elemento più importante è id che deve corrispondere al nome del file senza .md.
Esempio:
---
id: rust-commands
title: "Rust: Comandi Admin"
description: "Info sui comandi Admin per Rust da ZAP-Hosting"
sidebar_label: Comandi Admin
services:
- gameserver
---
Controlliamo i metadati durante la revisione, quindi se hai problemi non preoccuparti e procedi.
In questo caso apri il file che vuoi modificare. Per esempio dedicated-linux-satisfactory.md nella cartella /docs. Vedrai un’anteprima grezza in Markdown.
In alto a destra clicca l’icona della matita per modificare direttamente.
Continua: Scrivere il contenuto
Ora che hai il file aperto, scrivi il contenuto concordato nel suggerimento. Ti consigliamo di salvare o fare commit spesso per non perdere il lavoro.
Mentre scrivi, fai commit o copia spesso perché l’editor GitHub non ha autosave: se chiudi la scheda o succede qualcosa, perdi tutto.
Consigliamo di usare lo strumento Markdown StackEdit per scrivere offline, salvare localmente e sincronizzare. Quando finisci, copia e incolla su GitHub e fai commit.
Puoi usare il pulsante Preview in alto per vedere l’anteprima e tornare a editare con Edit.
Alcuni elementi specifici Docusaurus come admonizioni (:::note, :::tip ecc.) o tabs potrebbero non vedersi bene su GitHub perché non sono Markdown tradizionale, ma si vedranno correttamente in locale e in produzione.
Consulta le Linee Guida per tutto su Markdown, struttura, terminologia e altro.
Quando hai finito, clicca Commit changes... e inserisci un messaggio utile che spiega cosa hai fatto, con descrizione estesa se serve. Poi conferma il commit. Questo aggiorna il tuo fork. Ora puoi andare alla sezione Invio Contenuti per creare una Pull Request e inviare il contenuto al repository principale ZAP-Docs.
Se preferisci lavorare localmente con un IDE o editor come Visual Studio Code, qui ti spieghiamo come creare o modificare guide localmente.
Prerequisiti:
- IDE a scelta, qui useremo Visual Studio Code
- GitHub Desktop o altro con funzionalità Git
Prima cosa: clona il tuo fork. Il modo più semplice è usare GitHub Desktop: clicca Add > Clone repository e scegli il tuo fork. Puoi anche farlo direttamente dall’IDE se supporta Git.
Apri la cartella del repo in Visual Studio Code. Nella tab Explorer a sinistra vedrai tutte le cartelle.
I file seguono la stessa convenzione vista prima. Controlla il sito live ZAP-Docs per capire dove mettere la guida. Per esempio dedicated-windows.md è per server dedicati Windows.
Ora apri un file esistente o creane uno nuovo, a seconda se aggiorni o crei una guida. Usa la tab giusta qui sotto per le istruzioni, perché creare una guida nuova richiede qualche passaggio in più.
- Crea un file guida nuovo
- Modifica un file guida esistente
Esempio: vogliamo creare una guida nuova per Rust sui comandi. La sezione Rust esiste già sotto game servers. Il file si chiamerà rust-commands.md.
Apri la cartella /docs nel tuo IDE e crea un nuovo file con il nome giusto.
Ricordati di aggiungere l’estensione .md.
Ora aggiungi i metadati in cima al file. Copia da un file simile come rust-plugins.md e modifica i valori. L’id deve corrispondere al nome del file senza .md.
Esempio:
---
id: rust-commands
title: "Rust: Comandi Admin"
description: "Info sui comandi Admin per Rust da ZAP-Hosting"
sidebar_label: Comandi Admin
services:
- gameserver
---
Controlliamo i metadati durante la revisione, quindi se hai problemi non preoccuparti e procedi.
Ultimo passo: per far comparire la pagina nel sidebar di Docusaurus, aggiungila nel file sidebar.js nella sezione giusta. Cerca la sezione Rust con CTRL+F e aggiungi una nuova riga con il nome del file, es. rust-commands. Se la sezione non esiste, crea una nuova seguendo il formato degli altri.
Ricordati di mettere una virgola (,) sulla riga prima della tua nuova riga per mantenere la sintassi corretta.
Modificare un file esistente è semplice, non devi impostare tutta la struttura.
Apri il file guida che vuoi modificare nella cartella /docs e procedi con le modifiche concordate e approvate.
Continua: Scrivere il contenuto
Ora che il file è pronto, scrivi il contenuto concordato. Salva o fai commit spesso per non perdere il lavoro.
Puoi usare CTRL+SHIFT+V o l’icona preview in alto a destra per vedere l’anteprima live in split view.
Alcuni elementi Docusaurus come admonizioni (:::note, :::tip ecc.) o tabs potrebbero non vedersi bene su GitHub perché non sono Markdown tradizionale, ma si vedranno correttamente in locale e in produzione.
Consulta le Linee Guida per tutto su Markdown, struttura, terminologia e altro.
Quando hai finito, fai un commit e push sul tuo fork usando GitHub Desktop o altro client Git, con titolo e descrizione appropriati.
Ora puoi andare alla sezione Invio Contenuti per creare una Pull Request e inviare il contenuto al repository principale ZAP-Docs.
Ti consigliamo anche di leggere la sezione opzionale Test locale, così puoi abbinare test e sviluppo locale per un workflow ottimale. Non è obbligatorio però.
Opzionale: Test locale della build
Prima di creare la Pull Request finale, è buona pratica testare localmente per assicurarti che tutto funzioni con le modifiche fatte. Consigliamo di testare localmente per velocizzare l’approvazione, ma non è obbligatorio.
Non è obbligatorio, perché facciamo una build automatica quando invii la Pull Request. Però può aiutarti a fare debug e test live.
Se hai seguito il tutorial per lavorare localmente, puoi saltare il primo passo di clonare il repo perché lo hai già.
Prerequisiti:
Prima clona il tuo fork. Il modo più semplice è GitHub Desktop: clicca Add > Clone repository e scegli il tuo fork.
Puoi anche usare Git da terminale. Crea una cartella, es. Docs Test, apri Git Bash lì e prendi l’URL del tuo fork da GitHub. Poi esegui:
git clone [your_url]
Ora hai il repo clonato localmente. Passa alla cartella, apri un terminale (cmd o git bash) e scarica i moduli con:
npm install
Ci vorrà un po’, ma alla fine avrai la cartella node_modules. Se ricevi errori, probabilmente non hai installato Node.js.
Ultimo passo: avvia il sito docs localmente con:
npm start
Si aprirà automaticamente una versione locale del sito nel browser sulla porta 3000. È identica alla versione di produzione e puoi testare tutto!
Quando sei soddisfatto, vai alla sezione successiva per creare la Pull Request e inviare il contenuto.
Passo 3: Inviare il Contenuto
Quando hai finito e pensi che il contenuto rispetti le linee guida e sia top, crea una Pull Request. Vai al tuo fork del repository ZAP Docs, clicca su Contribute sotto i pulsanti principali e apri una pull request.
Si aprirà una pagina dove vedi le modifiche fatte. Di default c’è una checklist per assicurarti di aver fatto tutto bene, puoi cancellarla se vuoi.
Metti un titolo chiaro che spiega cosa hai fatto. Nella descrizione, menziona o linka il tuo suggerimento usando #000 con l’ID del suggerimento. Se non lo trovi nel menu, vai al repo principale ZAP Docs GitHub, cerca negli issues il tuo suggerimento e prendi l’ID.
Quando titolo, descrizione e modifiche sono a posto, crea la pull request per inviarla al nostro repository.
Il sistema controllerà che le modifiche passino vari test di sintassi e qualità. Se tutto va bene, il team ZAP-Docs la revisionerà entro pochi giorni.
Durante la revisione potremmo chiederti modifiche o fare noi stessi aggiustamenti. Quando tutto è ok, approveremo la PR e sarà pronta per la pubblicazione.
Passo 4: Pubblicazione e Pagamento Ricompensa
Quando accettiamo la tua Pull Request dopo eventuali modifiche richieste, ti risponderemo direttamente sulla PR con info importanti. Ti diremo quando la guida sarà pubblicata e come riceverai la ricompensa per il tuo contributo.
La ricompensa dipende da vari fattori, soprattutto qualità e quantità del contenuto scritto, e altri criteri valutati dal Team Contributi ZAP. Leggi di più nei nostri Rewards.
Complimenti per aver contribuito alle guide ZAP-Hosting! Apprezziamo tantissimo il tuo supporto! 💚