Per chi

Documentazione con il codice intatto

Clean Clipper legge il linguaggio dalla pagina stessa – la classe del blocco, l’elemento che lo contiene, il markup lasciato dall’evidenziatore del sito – e lo scrive sulla recinzione del blocco. Su un corpus tecnico di nove pagine la marcatura è sopravvissuta in 73 blocchi su 156, contro 20 e 0 dei due motori confrontati. Il resto della pagina arriva in Markdown normale, senza la barra laterale.

Che cosa si rompe nel copia-incolla

Una documentazione è prima di tutto codice, ed è proprio la parte che quasi tutti i clipper guastano. Il blocco arriva nudo, senza marcatura: in Obsidian resta un rettangolo grigio uniforme, in un repository attraversa la revisione senza evidenziazione. Così riapri ogni nota per riscrivere a mano js, python o bash sopra ogni recinzione. Su una documentazione di trenta pagine è una serata passata a rimettere in piedi qualcosa che sulla pagina di partenza c’era già.

Il resto del salvataggio non se la cava meglio. Il selettore di versione, la barra laterale e l’indice «in questa pagina» finiscono in mezzo al testo, e una tabella di parametri si schiaccia su una riga sola perché una cella conteneva un esempio di codice. Tre mesi dopo cerchi un’opzione dell’API nei tuoi appunti e la prima cosa che trovi sono tre copie del menu. La nota esiste, ma non si rilegge.

Il terzo problema è la scheda tenuta aperta al posto della nota. Una documentazione è versionata, il suo indirizzo quasi mai: la pagina che leggevi per la 4.x diventa in silenzio la 6.x, con un’opzione rinominata e una tolta, e il segnalibro continua a funzionare – verso un testo diverso. Nei tuoi appunti non c’è scritto da nessuna parte contro quale versione avevi costruito. Un file con l’indirizzo e la data dichiarata dalla pagina risponde a quella domanda un anno dopo; un segnalibro non ci ha mai provato.

Che cosa cambia nella nota

• Il blocco esce come ```js e non nudo: l’evidenziazione funziona in Obsidian, VS Code e su GitHub appena incolli
• Il linguaggio è letto dalla pagina – classe del blocco, elemento contenitore, markup dell’evidenziatore – mai indovinato dal codice
• Una tabella di parametri con del codice in una cella tiene le sue righe invece di schiacciarsi
• I rimandi diventano note [^1], con le definizioni raccolte in fondo al file
• Barra laterale, selettore di versione e indice «in questa pagina» vengono tagliati, non convertiti
• Il codice in linea resta codice in linea, anche dentro i titoli e dentro le celle
• L’estrazione gira sul DOM già disegnato: una documentazione costruita in JavaScript viene presa come la vedi, con la sezione davvero aperta
• Il campo extraction dichiara la via seguita – dom, oppure jsonld-articlebody quando la pagina teneva il testo nei dati strutturati senza finire di disegnarlo

## Affettare una lista

Le liste si possono affettare e concatenare:

```python
>>> quadrati = [1, 4, 9, 16, 25]
>>> quadrati[-3:]
[9, 16, 25]
```

| Operazione | Che cosa restituisce |
| --- | --- |
| `len(quadrati)` | il numero di elementi |
| `quadrati[:]` | una copia superficiale |

Prepararlo per la documentazione

Cinque minuti una volta sola, poi lavora la scorciatoia. Le impostazioni predefinite sono pensate per leggere articoli; una documentazione vuole un altro nome file, nessun campo autore e nessuna immagine.

1. Installa l’estensione e fissa la sua icona nella barra degli strumenti. Clic destro sull’icona, poi Opzioni: le impostazioni si aprono in una scheda, non in un riquadro che sparisce al primo clic fuori.
2. Alla voce cosa fa il clic sull’icona scegli «scrivi nella cartella». È il passaggio che trasforma un salvataggio in un solo tasto: la finestra di anteprima serve finché stai imparando lo strumento, dopo è una finestra che chiudi ogni volta.
3. Indica la cartella. Punta a una directory che tieni già sotto controllo di versione, per esempio docs/ritagli dentro il repository su cui stai lavorando. Il browser chiede conferma una volta e ricorda il consenso per quel profilo.
4. Metti il modello del nome file su {domain}-{title}. Quattro framework hanno tutti una pagina «Per iniziare»: senza il dominio nel nome, la quarta diventa in silenzio per-iniziare-4.
5. Nella sezione del frontmatter tieni source ed extraction e spegni author. Una documentazione raramente è firmata, e un campo vuoto ripetuto in ogni file è rumore che finirai per togliere a mano.
6. Imposta le immagini su «salta». La schermata dell’IDE di qualcun altro non si cerca con grep, e il link punta a una CDN che prima o poi cambierà indirizzo.
7. Apri chrome://extensions/shortcuts e verifica che Alt+Shift+M sia assegnato. Se un’altra estensione se l’è preso, è lì che te lo riprendi.

Impostazioni per chi programma

Sono i valori che vale la pena spostare dai predefiniti, e il motivo per cui contano su una documentazione tecnica invece che sulla lettura in generale.

Prima di avviare il servizio, applica le migrazioni:

```
./bin/migrate --env produzione
```

```sql
SELECT id, creato_il FROM sessioni WHERE scade_il < now();
```

Il secondo blocco portava `class="language-sql"`. Il primo non portava
niente, e resta nudo invece di ricevere una marcatura indovinata.

Tre sessioni vere

Fissare la versione contro cui hai davvero costruito

Sei sul ramo 4.x della documentazione di un framework, sulla pagina di un’opzione di configurazione che nella 5.0 cambierà nome. Premi Alt+Shift+M. Il file arriva come esempio-dev-riferimento-configurazione.md dentro docs/ritagli, con source che punta all’indirizzo /v4/ e la data dichiarata dalla pagina in cima.

Otto mesi dopo l’opzione si comporta diversamente in produzione e nessuno ricorda perché era stata messa così. Il salvataggio è nel repository, nello stesso intervallo di commit della modifica, e dice contro quale versione della documentazione era stata presa la decisione. L’indirizzo dal vivo intanto serve la 6.x e quell’opzione non la nomina più.

La discussione che ha risolto davvero il problema

La documentazione ufficiale descrive il percorso felice; la soluzione al tuo caso sta in una discussione su Reddit, quattro commenti sotto, con la risposta accettata a 140 punti sotto una risposta sbagliata a 30. Salvi la discussione. La regola per sito la manda in discussioni, e la struttura dei commenti arriva come citazioni annidate con il punteggio attaccato a ciascuna.

Il punteggio è la parte che conta quando rileggi. Un copia-incolla piatto di quella pagina perde l’ordine e ti lascia con cinque opinioni fra cui non sai più quale avesse convinto gli altri.

Una tabella di variabili, dritta nella pull request

La guida al deploy ha una tabella di diciotto variabili d’ambiente, tre delle quali contengono un esempio di codice dentro la cella. Selezioni la tabella sulla pagina, salvi la selezione e incolli il Markdown nella descrizione della pull request. GitHub la disegna come tabella, perché è una tabella GFM e non una schermata.

Sul corpus tecnico di quindici tabelle questo serializzatore ne ha tenute dodici, mentre ciascuno dei motori confrontati ne ha tenute sette. Le celle che fanno deragliare i convertitori generici sono esattamente queste: quelle con dentro del codice o un elenco.

Rispetto ai modi soliti

Ognuno di questi modi funziona, e in questo momento qualcuno nella tua squadra sta usando proprio quello. La terza colonna dice il prezzo vero, compreso il nostro.

Quando non esce bene

Perché la recinzione è nuda?

Perché la pagina non ha detto di che linguaggio si trattava. Clean Clipper legge il linguaggio dalla classe che l’evidenziatore del sito ha lasciato; non guarda il codice per indovinare. Un esempio colorato a mano, senza classe, produce una recinzione nuda – ed è il risultato onesto, perché un python indovinato sopra un frammento di shell è peggio di niente: l’evidenziazione colora con sicurezza le cose sbagliate.

Perché metà della guida non c’è?

Quasi sempre sono schede o fisarmoniche. L’estensione converte quello che il browser ha davvero disegnato, e il contenuto di una scheda che viene inserito solo quando clicchi non è nel DOM finché non clicchi. Apri la scheda, espandi la sezione e poi salva – oppure salva una volta per variante. Dove il sito disegna tutte le schede e le nasconde con il CSS, arrivano tutte, una dopo l’altra.

Perché dice «nessun articolo»?

Una console di prova dell’API, una pagina di risultati o un indice di pacchetti sono quasi solo etichette di link, e l’estensione li rifiuta apposta: se più o meno un quarto dei caratteri estratti sta dentro dei link, dichiara «nessun articolo» invece di consegnarti trecento voci. Quel rifiuto è anche il motivo per cui la sua quota di «testo utile» risulta più bassa di quella dei motori che restituiscono sempre qualcosa.

Che cosa vuol dire extraction: "jsonld-articlebody" nel mio file?

Che la pagina portava il testo dell’articolo nei propri dati strutturati ma non ha mai finito di disegnarlo nel DOM, quindi il corpo è stato letto da lì. Viene registrato invece che nascosto perché le due vie possono differire: a volte la copia nei dati strutturati è una stesura precedente, a volte è l’unica completa. Quando vedi quel valore, vale un’occhiata all’originale prima di appoggiarci una decisione.

Che cosa non fa

Non indovina il linguaggio di un blocco che la pagina non marca: dove il sito rende il codice senza classe la recinzione resta nuda, ed è una scelta voluta, perché una marcatura inventata costa più di una marcatura assente. Non percorre un sito di documentazione intero: una pagina alla volta, quella che hai davanti, senza crawler e senza elaborazione in blocco. Non scarica schemi né schermate: le immagini restano link al sito di partenza. E sulle pagine protette dal browser, come chrome:// e lo store delle estensioni, non gira affatto.

Domande