Contribuire al manuale di TinyCAD
Questo manuale è pubblicato con GitHub Pages. Se trovi un errore, un passaggio mancante, uno screenshot poco chiaro o informazioni non aggiornate, puoi proporre una correzione con una Pull Request (PR).
Questa guida illustra due modalità di lavoro:
- Modifiche rapide nel browser (ideali per piccole correzioni testuali)
- Modifica e anteprima in locale (ideali per modifiche più ampie)
Prima di iniziare
Ti serviranno:
- Un account GitHub
- Per le modifiche in locale: Git, Node.js, Ruby e Bundler
Dettagli del repository:
- Repository sorgente:
https://github.com/matt123p/TinyCAD-docs - Sito pubblicato: output GitHub Pages di questo repository
- Cartella sorgente della documentazione:
docs/ - Pagine v4:
docs/v4/
Opzione A: modifica rapida su GitHub (senza configurazione locale)
Usa questo metodo per correggere refusi, aggiungere brevi chiarimenti o aggiornare link.
1) Aprire il sorgente della pagina su GitHub
- Vai al repository della documentazione di TinyCAD:
https://github.com/matt123p/TinyCAD-docs - Cerca la pagina che vuoi modificare in
docs/v4/. - Apri il file Markdown (ad esempio
Rulers.md).
2) Iniziare a modificare
- Fai clic sull’icona della matita (Modifica questo file (Edit this file)).
- Se richiesto, GitHub ti aiuterà a creare automaticamente un fork.
- Apporta le modifiche in Markdown.
3) Eseguire il commit della modifica
- Scorri fino a Esegui il commit delle modifiche (Commit changes).
- Usa un messaggio di commit chiaro, ad esempio:
docs(v4): clarify ruler units in Rulers - Scegli Crea un nuovo branch per questo commit (Create a new branch for this commit).
- Fai clic su Proponi modifiche (Propose changes).
4) Aprire una Pull Request
- Fai clic su Confronta e crea una pull request (Compare & pull request).
- Imposta il repository di base su
matt123p/TinyCAD-docse il branch di base sumain. - Compila il titolo e la descrizione della PR (modello qui sotto).
- Invia la PR.
Opzione B: modifica e anteprima in locale (consigliata per le modifiche più ampie)
Usa questo metodo quando devi modificare più file, controllare i link o visualizzare un’anteprima della formattazione.
1) Creare un fork e clonarlo
- Crea un fork di
matt123p/TinyCAD-docssu GitHub. - Clona il tuo fork:
git clone https://github.com/<your-username>/TinyCAD-docs.git
cd TinyCAD-docs
- Aggiungi il remote upstream:
git remote add upstream https://github.com/matt123p/TinyCAD-docs.git
2) Installare le dipendenze
Questo repository fornisce script npm che eseguono Bundler + Jekyll per te:
npm install
npm run bundle:install
3) Creare un branch per la modifica
git checkout -b docs/v4-fix-rulers
Idee per i nomi dei branch:
docs/fix-typo-...docs/v4-update-...docs/add-...
4) Apportare le modifiche
La maggior parte delle pagine rivolte agli utenti si trova in:
docs/v4/*.md(pagine del manuale v4)docs/v3/*.md(pagine del manuale v3)docs/_data/navigation.yml(navigazione a sinistra)
Se aggiungi una nuova pagina, aggiorna anche la navigazione, così gli utenti potranno trovarla.
5) Visualizzare l’anteprima del sito in locale
npm run serve
Poi apri l’URL locale mostrato nel terminale (in genere http://127.0.0.1:4000).
Controlla che:
- La struttura dei titoli sia leggibile
- I link interni funzionino
- La navigazione includa la pagina nuova o rinominata
- Le immagini vengano caricate correttamente
6) Eseguire il commit e il push
git add .
git commit -m "docs(v4): improve Rulers instructions"
git push -u origin docs/v4-fix-rulers
7) Creare la PR
- Apri il tuo fork su GitHub.
- Fai clic su Confronta e crea una pull request (Compare & pull request) per il tuo branch.
- Scegli come destinazione
matt123p/TinyCAD-docs:main. - Completa il titolo e la descrizione della PR e inviala.
Checklist per la qualità della scrittura
Prima di aprire una PR, verifica rapidamente che:
- L’ambito sia circoscritto (un argomento/problema per PR)
- Le istruzioni siano corrette rispetto al comportamento attuale di TinyCAD
- Il linguaggio sia chiaro e conciso
- I link di destinazione funzionino
- Quando necessario, la pagina sia collegata dalla navigazione
- Siano mantenuti lo stile e la terminologia esistenti
Set di schede riutilizzabili per browser/app desktop
Quando una pagina richiede istruzioni diverse per TinyCAD nel browser e nell’app per desktop, usa il componente condiviso per i set di schede invece di creare markup specifico per la pagina.
<div class="manual-tabset" data-tabset="product-mode" data-tabset-label="Choose your TinyCAD product" data-default-tab="Browser" markdown="1">
### Browser
Browser-specific content.
### Desktop App
Desktop-specific content.
</div>
Note:
data-tabsetè la chiave di sincronizzazione/archiviazione. Riutilizza lo stesso valore per mantenere sincronizzati più set di schede nella stessa pagina.data-default-tabimposta la scheda selezionata alla prima visita.- Mantieni tutti i titoli delle schede allo stesso livello (
###nell’esempio qui sopra).
Modello di PR suggerito
Copia e incolla questo testo nella descrizione della PR:
## Summary
-
## What changed
-
## Why
-
## Validation
- [ ] Previewed locally with `npm run serve`
- [ ] Checked navigation and links
- [ ] Confirmed formatting on rendered page
## Screenshots (if relevant)
-
Mantenere aggiornato il fork
Se la tua PR rimane aperta a lungo, sincronizza il branch con l’ultima versione di main:
git fetch upstream
git checkout main
git merge upstream/main
git push origin main
git checkout docs/v4-fix-rulers
git merge main
git push
Problemi comuni e soluzioni
- La PR mostra modifiche a file non correlate
- Crea un nuovo branch a partire da
mainaggiornato e applica con cherry-pick solo i tuoi commit.
- Crea un nuovo branch a partire da
- Elemento di navigazione mancante
- Aggiorna
docs/_data/navigation.ymle verifica che l’URL corrisponda al percorso del permalink della pagina.
- Aggiorna
- La pagina viene visualizzata in modo anomalo
- Controlla i livelli dei titoli, il rientro degli elenchi e i delimitatori dei blocchi di codice.
- Il link funziona in locale ma non su Pages
- Preferisci i link relativi usati altrove in questo repository e mantieni coerenti i nomi delle pagine.
Dopo l’invio
I responsabili della manutenzione potrebbero chiederti di apportare aggiornamenti. Aggiungi i commit successivi allo stesso branch/PR; la PR si aggiornerà automaticamente. Una volta approvate e unite, le modifiche appariranno nel manuale pubblicato dopo la ricostruzione di GitHub Pages.
Grazie per aver migliorato la documentazione di TinyCAD.
- Torna all’indice v4