Writing Tone & Style Guide - giobidev
Guida allo stile di scrittura per i blog post tecnici di giobidev.
Principi Base
1. Narrativa > Spec Tecnica
❌ EVITA (stile spec tecnica):
## Features
### Auto-backup
- Clona tutte le repo
- Pull automatico se esistono
- Storage tracking
✅ USA (stile narrativo):
## Clone Automatico: Zero Configurazione
Non volevo nemmeno pensare a dover aggiornare manualmente una lista di repo.
L'idea è che questo programma viva per i fatti suoi su un Raspberry, faccia il
suo lavoro e basta. Quindi interroga le API di GitHub e si prende tutto da solo.
Regola: Spiega il perché e il come ci sei arrivato, non solo cosa fa.
2. Contesto Personale & Aneddoti
Ogni post deve partire con il contesto:
- Quale problema reale hai affrontato?
- Cosa ti ha fatto incazzare/sbattere abbastanza da creare questa soluzione?
- Su quale progetto concreto l’hai usato?
Esempio (da Diary post):
Tutto è partito da due progetti completamente diversi che mi hanno fatto la stessa richiesta: “Vogliamo sapere cosa fanno gli utenti nella piattaforma”.
Il primo era una piattaforma didattica. Volevano tracciare il progresso degli studenti…
Il secondo era un sistema documentale per una PA. Qui la richiesta era più seria: tracciare le responsabilità…
Non iniziare mai con “Questa libreria fa X” o “In questo post vedremo Y”.
3. Tono: Leggero ma Tecnico
Caratteristiche:
- ✅ Sarcasmo leggero e autoironico
- ✅ Linguaggio colloquiale (“roba”, “fatto”, “cazzo” solo quando naturale)
- ✅ Competenza tecnica trasparente
- ❌ Zero volgarità gratuita
- ❌ Zero marketing-speak (“revolutionary”, “game-changer”, etc.)
- ❌ Zero pedanteria
Esempi di sarcasmo accettabile:
“Ovviamente le label vanno in config perché siamo delle persone decenti, non certo dei grezzi frontend developer che hardcodano stringhe a caso.”
“Impossibile fare query complesse, grep va bene al volo ma poi tanti auguri.”
“Pensavo ‘vabbè, vedremo’. Dopo qualche mese la tabella stava crescendo abbastanza velocemente.”
4. Struttura Narrativa
Schema consigliato:
- Intro personale (2-3 paragrafi)
- Contesto del problema
- Progetti reali dove l’hai affrontato
- Perché le soluzioni esistenti non andavano bene
- Il problema spiegato (bullet + narrativa)
- NON solo bullet points
- Aggiungi 1-2 paragrafi di contesto
- La soluzione (alternare code + spiegazioni narrative)
- Code block
- Paragrafo che spiega PERCHÉ quella scelta
- Aneddoto o caso d’uso reale
- Use cases concreti
- Progetti reali dove l’hai usato
- Risultati specifici (performance, tempo risparmiato, etc.)
- Conclusioni personali
- “L’ho usato in N progetti”
- “Ogni volta mi risparmia X tempo”
- Cosa cambieresti, cosa rifrai uguale
5. Code Blocks: Spiegazioni Integrate
❌ EVITA (solo code senza contesto):
Diary::deleteOlderThan(month: 6);
✅ USA (code + narrativa):
Quando ho fatto il primo deploy, non avevo messo retention policy.
Pensavo "vabbè, vedremo". Dopo qualche mese la tabella `diaries` stava
crescendo abbastanza velocemente. Non era ancora un problema, ma l'ho
aggiunto lo stesso per principio.
```php
// Elimina log più vecchi di 6 mesi
Diary::deleteOlderThan(month: 6);
Oltre a tenere sotto controllo la dimensione del database, ti aiuta anche con il GDPR.
---
### 6. Decisioni di Design: Spiega Le Alternative
**Quando introduci una scelta tecnica**, spiega:
- Perché questa e non alternative?
- Cosa hai provato prima?
- Trade-offs accettati?
**Esempio** (polymorphic relations):
> Ovviamente è una [polymorphic relation](link): così posso attaccarla
> a un qualsiasi model e non. La cosa bella è che funziona anche su cose
> che non sono model. Puoi loggare da un Command, da un Job, da dove ti pare.
**Esempio** (dual logging):
> Una cosa che mi piace di questo pattern è che non devi scegliere tra
> database e log file. Puoi avere entrambi. Database per le query e
> l'audit trail. Log file per quando stai debuggando in real-time.
---
### 7. Numeri e Risultati Concreti
**Preferisci dati reali** a claim generici:
❌ "Molto veloce"
✅ "Risposta in 10ms, con tutti i dettagli"
❌ "Risparmia tempo"
✅ "Da zero a audit trail completo in meno di un giorno"
❌ "Scalabile"
✅ "Pattern testato in production con milioni di record"
---
### 8. Link Esterni: Solo Quando Utili
**Inserisci link** per:
- Documentazione Laravel/framework ufficiale
- Concetti non ovvi (es: polymorphic relations)
- Tool/librerie menzionate
**NON linkare**:
- Concetti base (non serve linkare "cos'è Git")
- Wikipedia per termini comuni
- Tutorial generici
---
### 9. Checklist Pre-Pubblicazione
Prima di pubblicare, verifica:
- [ ] Il post inizia con un aneddoto/contesto personale?
- [ ] Ogni sezione tecnica ha almeno 1-2 frasi narrative?
- [ ] Hai spiegato il **perché** delle scelte, non solo il **cosa**?
- [ ] Ci sono numeri/risultati concreti da progetti reali?
- [ ] Il tono è leggero ma competente?
- [ ] Zero marketing-speak o claim esagerati?
- [ ] I code block hanno contesto prima/dopo?
---
## Anti-Pattern da Evitare
### ❌ Landing Page SaaS Style
Features
1. Auto-sync
Fast and reliable synchronization
2. Cloud backup
Your data, safe in the cloud
3. Real-time updates
Never miss a change
Questo suona da brochure commerciale. NO.
---
### ❌ README di Libreria
Installation
npm install foo
Usage
import { foo } from 'foo';
foo.bar();
API Reference
foo.bar()
…
Va bene per una README, NON per un blog post.
---
### ❌ Tutorial Passo-Passo Impersonale
In this tutorial, we will learn how to implement activity logging.
First, create a model: …
Then, add the trait: …
Finally, configure the settings: … ```
Troppo formale, zero personalità. NO.
Esempi di Riferimento
✅ Buoni esempi dal blog:
Diary logging post (2025-11-15):
- Intro con due progetti concreti (didattica + documentale)
- Aneddoti su retention policy
- Sarcasmo su frontend dev e label config
- Use cases specifici con risultati reali
GitBackup post (2025-11-16):
- Contesto: “sbattimenti che altri miei amici hanno”
- Tono colloquiale: “Pensavo ‘vabbè, vedremo’”
- Spiegazioni tecniche ma leggere
Note Finali
Obiettivo: Scrivere post che siano:
- Utili tecnicamente (qualcuno può applicare il pattern)
- Piacevoli da leggere (narrativa, non spec)
- Autentici (esperienze reali, non marketing)
Target reader: Developer con esperienza che vuole:
- Soluzioni concrete a problemi reali
- Contesto e ragionamento, non solo codice
- Stile rilassato ma competente
Voce: Giobi che racconta cosa ha fatto e perché, non “un esperto che spiega best practices”.
Versione: 1.0 (2025-11-12) Ultima modifica: Post Diary + GitBackup review session