Articoli di Documentazione: Riferimento Versione per Utenti Esistenti

Un articolo di documentazione è un riferimento mantenuto per qualcuno che già utilizza un prodotto, API, servizio, dispositivo o processo operativo. Risponde a una precisa domanda di consultazione — cosa fa un’impostazione, quali valori accetta un campo, quale accesso è richiesto, quale versione si comporta in un certo modo, o dove si applica un limite — senza costringere il lettore a passare attraverso un argomento di marketing.

Il suo contratto è ambito → prerequisiti → comportamento corrente → riferimento esatto → eccezioni → attività correlata. La pagina ha successo quando un utente recupera il dato giusto per la versione e il ruolo giusti. Trasformare ogni etichetta dell’interfaccia in un URL pubblico non aiuta.

Domande a cui risponde

La domanda principale è: “Cosa significa questo comportamento del prodotto nella mia versione e nel mio contesto?” Le domande di supporto includono:

• Questa pagina si applica al mio prodotto, piano, ruolo, regione, piattaforma e versione?
• Cosa deve già essere vero prima che io possa usare questa funzionalità o consultare questo campo?
• Quali sono i valori accettati, i valori predefiniti, i limiti, i formati e gli effetti collaterali?
• Quale comportamento è corrente e cosa è cambiato rispetto a una versione precedente?
• Quale esempio dimostra la regola senza nascondere condizioni importanti?
• Cosa dovrei leggere dopo se ho bisogno di una procedura, diagnosi o cronologia delle modifiche?
• Questa informazione è sicura e utile nella ricerca pubblica, o richiede un contesto autenticato?

Quando usare questo tipo di post

Usa la documentazione quando una pagina stabile deve supportare consultazioni ripetute. L’argomento necessita di un proprietario autorevole, un comportamento testabile e un segnale di manutenzione come un rilascio, API, piano o modifica dell’interfaccia.

Una pagina chiamata “Come configurare i campi di esportazione” può comunque essere documentazione quando il suo valore duraturo è un catalogo di campi e gli utenti saltano direttamente ai singoli parametri. Al contrario, “Esporta il tuo primo report” è una guida pratica quando il lettore deve seguire una sequenza e verificare un file scaricato. La grammatica del titolo non decide il formato; lo fanno il compito del lettore e la forma della risposta.

Ideale per questi tipi di business

1. SaaS. La migliore corrispondenza perché ruoli, piani, impostazioni, integrazioni, API, modelli di dati e cadenza di rilascio generano esigenze di riferimento precise. La documentazione dovrebbe distinguere il comportamento dell’interfaccia dal comportamento dell’API e le autorizzazioni utente dai diritti di abbonamento.
2. Ecommerce. Ottimo per amministrazione del merchant, feed di prodotto, regole di pagamento, resi, integrazioni e uso post-acquisto. Separa l’assistenza clienti dalla documentazione del merchant in modo che un acquirente non finisca su un riferimento di implementazione.
3. Marketplace. Ottimo dove acquirente, venditore, fornitore e amministratore vedono stati diversi. Ogni articolo deve identificare l’attore perché la stessa etichetta può mostrare diversi controlli o obblighi.
4. Agenzie. Utile per portali clienti, standard di consegna, flussi di lavoro ricorrenti e strumenti condivisi. Pubblica riferimenti cliente riutilizzabili pubblicamente solo quando non espongono controlli interni, credenziali o dettagli operativi proprietari.
5. Servizi B2B. Utile per sistemi di onboarding, passaggi di dati, specifiche di file, stati di approvazione e portali di servizio. Evita di presentare un impegno contrattuale come un dato generico del centro assistenza quando i termini variano per account.
6. Aziende manifatturiere e industriali. Prezioso per controlli, software, compatibilità, configurazione, registri di manutenzione e parametri tecnici. Il materiale critico per la sicurezza richiede una revisione controllata, un’esplicita applicabilità del modello e un percorso verso il manuale autorevole.

Intento di ricerca

L’ intento di ricerca è il risultato che una persona si aspetta da una query. L’intento della documentazione è solitamente navigazionale più informativo: chi cerca conosce il prodotto o l’oggetto e vuole un dato esatto, come “conservazione esportazione Northstar”, “valori stato Northstar” o “dimensione pagina API Northstar”. Marchio, funzionalità, linguaggio dell’attività senza errori, versione e piattaforma appaiono spesso insieme.

Il risultato ideale si apre vicino alla risposta. Usa titoli descrittivi, anchor stabili, valori accettati e qualificatori di versione. Un’affermazione estratta deve preservare la sua condizione: “Nei piani Team ed Enterprise, le esportazioni completate rimangono disponibili per 30 giorni.”

La documentazione pubblica dovrebbe posizionarsi quando risponde a una domanda duratura senza rivelare dati dell’account: formati supportati, campi API pubblici, compatibilità, limiti, significato della configurazione e comportamento documentato.

La documentazione non dovrebbe posizionarsi quando rispecchia una singola etichetta UI, duplica una pagina corrente, copre una versione obsoleta senza necessità continuativa, espone dettagli sensibili o richiede contesto di account privato. Usa invece assistenza autenticata, guida in-app, noindex, consolidamento o un chiaro stato di archiviazione. La domanda di ricerca non giustifica mai la pubblicazione di segreti o percorsi di exploit.

Struttura della pagina

Le fasce di parole sono controlli di produzione, non quote minime. Un riferimento di campo ristretto può essere più corto; un riferimento di funzionalità con versioni potrebbe necessitare più spazio perché l’applicabilità e le eccezioni prevengono errori costosi.

La maggior parte degli articoli di documentazione sostanziali si colloca tra 1.500 e 2.800 parole. Aggiungi dettagli solo dove prevengono ambiguità: ambito, prerequisito, valore, valore predefinito, effetto collaterale, eccezione o cambiamento di versione.

Elementi obbligatori

I lettori di riferimenti scansionano. Posiziona le informazioni di applicabilità prima del riferimento in modo che un valore tecnicamente corretto non venga applicato al piano o rilascio sbagliato.

Frontmatter

Segui la specifica del frontmatter. In questa specifica di tipo di post, entity = "post-type-documentation-article". In una pagina di documentazione prodotta, usa un valore stabile dell’oggetto prodotto come northstar-scheduled-export-settings, non una frase promozionale come effortless-reporting e non un numero di versione che forzerebbe una nuova identità dopo ogni rilascio.

Usa schemaType = "Article". Lo schema markup deve descrivere la pagina visibile; non selezionare HowTo solo perché un esempio contiene tre azioni. Aggiungi dati strutturati FAQ solo quando le domande e risposte visibili corrispondono esattamente. I riferimenti API o la semantica specifica del software possono essere rappresentati altrove nel modello dati del sito, ma un tipo di schema più specifico non dovrebbe essere inventato nel frontmatter senza supporto del template.

Memorizza i campi che il sistema di manutenzione può applicare: area prodotto, piani, ruolo, piattaforma, intervallo di versioni, data verificata, proprietario e URL di sostituzione. lastmod significa che il comportamento è stato rivisto, non che un refuso è stato corretto. Preserva l’URL canonico tra rilasci compatibili.

Esempio completo

Questo esempio fittizio di analisi dimostra una pagina di riferimento, non una procedura di esportazione completa.

# Impostazioni esportazione pianificata

Le esportazioni pianificate creano un file CSV o JSON da un report salvato a un'ora UTC fissa e lo consegnano a una destinazione approvata. Sono disponibili per Editor e Amministratori nei piani Team ed Enterprise. Questo riferimento si applica a Northstar Analytics web app 6.4 ed è stato verificato il 27 agosto 2026.

## Prima di usare questo riferimento

È necessario un report salvato esistente, una destinazione abilitata e l'accesso come Editor o Amministratore. Un Visualizzatore può scaricare un'esportazione esistente ma non può creare o modificare una pianificazione. Gli amministratori della destinazione possono imporre limiti aggiuntivi di conservazione o dimensione file.

## Riferimento impostazioni

| Impostazione | Valore accettato | Predefinito | Effetto e vincoli |
|---|---|---|---|
| Nome | 1–80 caratteri | Nome report | Identifica la pianificazione; modificarlo non rinomina i file precedenti. |
| Formato | `csv` o `json` | `csv` | CSV usa l'ordine delle colonne visibile del report. JSON usa chiavi di campo stabili. |
| Ora di esecuzione | `HH:MM` in UTC | `08:00` | I cambi di ora legale non spostano l'ora di esecuzione UTC. |
| Includi righe vuote | On o Off | Off | Disponibile solo per report tabellari; ignorato per report riassuntivi. |
| Conservazione | 1–30 giorni | 7 giorni | I file esistenti scadono indipendentemente dalla pianificazione che li ha creati. |

## Comportamento e confini

Una pianificazione legge la configurazione del report salvato quando inizia l'esecuzione. Modificare il report quindi cambia i file futuri ma non quelli già generati. Mettere in pausa una pianificazione impedisce nuove esecuzioni; non elimina i file conservati. Eliminare la destinazione disabilita la consegna e porta la pianificazione in stato `Needs attention`.

## Esempio

Per un CSV giornaliero necessario alle 09:00 a Bratislava durante l'ora solare, imposta l'ora di esecuzione UTC su `08:00`. Controlla l'ora quando cambiano le regole dell'ora legale perché le pianificazioni rimangono fisse all'UTC.

Esempio non valido: inserire `Europe/Bratislava` nel campo dell'ora di esecuzione. Il campo accetta un'ora UTC, non un identificatore di fuso orario.

## Differenze tra versioni

- Versione 6.4: Le esportazioni JSON usano chiavi di campo stabili; l'etichetta di colonna visualizzata non diventa più la chiave.
- Versioni 6.1–6.3: Le chiavi JSON seguono le etichette delle colonne visualizzate. Le integrazioni esistenti dovrebbero essere verificate prima dell'aggiornamento.
- Prima della 6.1: l'esportazione JSON pianificata non è disponibile. Usa CSV o passa a una versione supportata.

## Se un'esportazione non arriva

Non aggiungere correzioni speculative qui. Apri la guida alla risoluzione dei problemi "L'esportazione pianificata non è arrivata", che verifica lo stato della pianificazione, l'autorizzazione della destinazione, i limiti di file e gli incidenti di servizio in ordine diagnostico.

## Attività correlate

- Crea la tua prima esportazione pianificata — configurazione ordinata e verifica del successo
- Risolvi un'esportazione pianificata mancante — diagnosi guidata dal sintomo
- Note di rilascio Northstar Analytics 6.4 — modifiche del comportamento e nota di migrazione

## Registro di verifica

Verificato con web app 6.4 dal proprietario del prodotto Reporting il 27 agosto 2026. Da rivedere quando cambiano autorizzazioni, formati, conservazione, pianificazione o comportamento della destinazione.

Galleria di design

Usa impostazioni, limiti, ruoli e dati di versione identici tra le varianti in modo che la revisione del design misuri la velocità di recupero piuttosto che le differenze di copia.

Checklist di qualità

Un articolo di documentazione è pronto solo quando ogni affermazione applicabile è vera:

• L’apertura nomina l’oggetto esatto e fornisce il comportamento corrente prima del contesto o dei benefici.
• L’applicabilità di prodotto, piano, ruolo, regione, piattaforma e versione è esplicita dove cambia la risposta.
• I prerequisiti appaiono prima delle impostazioni o degli esempi che dipendono da essi.
• Ogni termine tecnico è definito al primo utilizzo, espresso attraverso un’etichetta di interfaccia familiare o collegato alla sua definizione canonica.
• Campi, valori, valori predefiniti, unità, formati, limiti ed effetti collaterali provengono da una fonte autorevole o da un test di prodotto verificato.
• Le tabelle di riferimento usano dimensioni consistenti; le celle vuote non nascondono valori predefiniti o eccezioni sconosciuti.
• Gli esempi indicano le condizioni che li rendono validi e includono un esempio non valido o di confine quando è probabile confusione.
• Gli avvisi appaiono prima di comportamenti distruttivi, irreversibili, sensibili alla sicurezza, costosi o che modificano le autorizzazioni.
• Gli screenshot includono una versione di acquisizione e un equivalente testuale; l’immagine non è l’unica fonte di un valore o istruzione.
• Titoli e anchor corrispondono ai nomi che gli utenti cercano e rimangono stabili per collegamenti profondi.
• Le differenze sostanziali tra versioni indicano l’intervallo interessato, la sostituzione corrente e la conseguenza di migrazione.
• La data verificata riflette una revisione comportamentale e un team o ruolo nominato possiede la prossima revisione.
• Procedure, diagnosi e cronologia dei rilasci collegano alle pagine sorelle canoniche invece di essere duplicate in modo incompleto.
• L’indicizzazione pubblica è intenzionale; il materiale obsoleto, duplicato, privato e sensibile alla sicurezza ha un trattamento di ricerca appropriato.
• I record FAQ corrispondono alle risposte visibili e il CTA rispetta il compito successivo di un lettore in fase di supporto.

Errori comuni

Scrivere una pagina di presentazione della funzionalità per un utente esistente. “Sblocca esportazioni potenti” ritarda il dato di cui il lettore ha bisogno. Inizia con comportamento, applicabilità e vincoli; la copia dei benefici appartiene solo dove chiarisce lo scopo.

Trasformare ogni attività in documentazione. Una configurazione in 20 passaggi sepolta sotto un elenco di campi non serve né alla consultazione né al completamento. Separa la procedura ordinata in una guida pratica e collegala dalla relativa sezione di prerequisiti o attività correlate.

Pubblicare una pagina per ogni etichetta dell’interfaccia. Pagine sottili si sovrappongono e moltiplicano la manutenzione. Raggruppa i campi attorno a un oggetto prodotto stabile a meno che un’impostazione non abbia un comportamento distinto.

Usare “ultima” come versione. L’ultima cambia. Indica il rilascio testato, l’intervallo supportato, la piattaforma e la data di verifica, poi aggiornali attraverso il processo di rilascio.

Mantenere pagine vecchie e nuove indicizzabili senza un confine. Consolida il comportamento compatibile; altrimenti etichetta la versione vecchia, collega alla pagina corrente e controlla l’indicizzazione intenzionalmente.

Nascondere i prerequisiti dentro gli errori. Se solo gli Amministratori possono modificare un campo, dillo prima del riferimento. Non far scoprire a un Visualizzatore il confine di ruolo dopo aver seguito un esempio.

Copiare screenshot invece del comportamento. Un’acquisizione è prova di uno stato dell’interfaccia, non la specifica. Scrivi etichette, percorsi, valori e condizioni in testo accessibile e registra la versione acquisita.

Falsificare l’aggiornamento. Cambiare la data senza ripetere il test del comportamento fa sembrare la pagina più sicura mentre aumenta il rischio. Aggiorna il registro di verifica solo dopo che il suo proprietario ha controllato le affermazioni applicabili.

Lasciare che la ricerca pubblica esponga dettagli interni. Percorsi di escalation interni, segreti, identificatori di clienti, istruzioni di exploit e comportamenti non annunciati non diventano sicuri perché riducono lo sforzo di supporto. Separa l’aiuto pubblico dalla conoscenza autenticata e interna.

Collegamenti interni

Collega verso l’alto ai tipi di post SEO quando l’autore potrebbe aver bisogno di una diversa forma di risposta. Collega da un prerequisito di documentazione alla guida pratica canonica solo quando il lettore deve completare prima quel compito. Collega da uno stato di errore alla risoluzione dei problemi invece di inserire un elenco generico di correzioni. Collega da una differenza di versione all’evento di rilascio quando la cronologia delle modifiche aggiunge contesto; le note di rilascio dovrebbero collegarsi alla documentazione corrente come fonte di verità duratura.

Organizza i collegamenti attorno agli oggetti prodotto e allo stato del lettore. Mantieni un collegamento specifico accanto all’affermazione che crea la domanda successiva invece di fare affidamento su un lungo elenco di articoli correlati.

Una pagina corrente canonica dovrebbe possedere il comportamento stabile. Mantieni le pagine di versione solo per comportamenti materialmente diversi di cui gli utenti hanno ancora bisogno, e rendi esplicita quella distinzione. Usa anchor stabili come #retention, non #table-2.

Come misurare i risultati

Misura se gli utenti recuperano la risposta corretta per la loro versione. Il traffico da solo è un’evidenza debole: un picco può riflettere un prodotto difettoso o una risposta obsoleta.

Registra le query target, l’URL di posizionamento, l’indicizzabilità, le versioni supportate, le ricerche di supporto, le uscite verso attività correlate e un evento di prodotto appropriato. Poi verifica:

• impressioni di ricerca e visite qualificate per query su oggetto prodotto, campo, limite, sintassi, ruolo e versione;
• perfezionamenti della ricerca interna, ricerche con zero risultati e ricerche ripetute che rivelano terminologia mancante;
• coinvolgimento con sezioni con anchor anziché tempo indifferenziato sulla pagina;
• click verso la corretta destinazione di configurazione, risoluzione dei problemi, rilascio o supporto;
• contatti di supporto la cui domanda la pagina dovrebbe rispondere, segmentati per versione e ruolo dove la privacy lo permette;
• citazioni che preservano il valore insieme al suo piano, versione, unità o prerequisito;
• URL obsoleti che ancora si posizionano o vengono citati dopo consolidamento o ritiro;
• modifiche alla documentazione causate da rilasci, cambiamenti dell’interfaccia, cambiamenti delle policy e casi di supporto ricorrenti.

Usa il tracciamento dei prompt per domande di consultazione marchiate e varianti di versione. Usa l’intelligence delle fonti e delle citazioni per vedere quale URL un motore di risposta cita e se il suo riassunto preserva le condizioni. Apri AmICited Cockpit per confrontare URL citati, visibilità, attività di atterraggio organico e l’evento di prodotto o supporto scelto nella stessa finestra di osservazione.

Segui come misuriamo i risultati per separare scoperta, rappresentazione, coinvolgimento, progressione del compito e fidelizzazione. Annota rilasci e incidenti prima di interpretare i movimenti. Una risposta a zero click funziona solo quando preserva il valore corrente e le sue condizioni.

FAQ

Domande frequenti