Articole de documentație: Referință versionată pentru utilizatori existenți

Un articol de documentație este o referință întreținută pentru cineva care utilizează deja un produs, API, serviciu, dispozitiv sau proces operațional. Răspunde la o întrebare precisă de consultare — ce face o setare, ce valori acceptă un câmp, ce acces este necesar, ce versiune se comportă într-un anumit fel sau unde se aplică o limită — fără a obliga cititorul să treacă mai întâi printr-un argument de marketing.

Contractul său este domeniu → cerințe prealabile → comportament curent → referință exactă → excepții → sarcină conexă. Pagina reușește atunci când un utilizator găsește informația corectă pentru versiunea și rolul potrivit. Transformarea fiecărei etichete de interfață într-un URL public nu ajută.

Întrebări la care răspunde

Întrebarea principală este: „Ce înseamnă acest comportament al produsului în versiunea și contextul meu?” Întrebările suplimentare includ:

• Se aplică această pagină produsului, planului, rolului, regiunii, platformei și versiunii mele?
• Ce trebuie să fie deja adevărat înainte să folosesc această funcționalitate sau să consult acest câmp?
• Care sunt valorile acceptate, valorile implicite, limitele, formatele și efectele secundare?
• Ce comportament este curent și ce s-a schimbat față de o versiune anterioară?
• Ce exemplu demonstrează regula fără a ascunde condiții importante?
• Ce ar trebui să citesc în continuare dacă am nevoie de o procedură, diagnostic sau istoric al modificărilor?
• Este această informație sigură și utilă în căutarea publică sau necesită context autentificat?

Când să folosești acest tip de postare

Folosește documentația atunci când o pagină stabilă trebuie să sprijine consultări repetate. Subiectul are nevoie de un proprietar autorizat, un comportament testabil și un semnal de întreținere, cum ar fi o lansare, API, plan sau modificare a interfeței.

O pagină numită „Cum să configurezi câmpurile de export” poate fi totuși documentație atunci când valoarea sa durabilă este un catalog de câmpuri și utilizatorii sar direct la parametri individuali. Invers, „Exportă primul tău raport” este un ghid practic atunci când cititorul trebuie să urmeze o secvență și să verifice un fișier descărcat. Gramatica titlului nu decide formatul; sarcina cititorului și forma răspunsului decid.

Cel mai potrivit pentru aceste tipuri de afaceri

1. SaaS. Cea mai potrivită, deoarece rolurile, planurile, setările, integrările, API-urile, modelele de date și ritmul lansărilor produc nevoi exacte de referință. Documentația ar trebui să distingă comportamentul interfeței de comportamentul API și permisiunile utilizatorului de drepturile de abonament.
2. Ecommerce. Potrivită pentru administrarea comercianților, feeduri de produse, reguli de plată, retururi, integrări și utilizare post-cumpărare. Separă ajutorul pentru clienți de documentația pentru comercianți, astfel încât un cumpărător să nu ajungă pe o referință de implementare.
3. Marketplace-uri. Potrivită acolo unde cumpărătorul, vânzătorul, furnizorul și rolurile de administrator văd stări diferite. Fiecare articol trebuie să identifice actorul, deoarece aceeași etichetă poate expune controale sau obligații diferite.
4. Agenții. Utilă pentru portaluri clienți, standarde de livrabile, fluxuri de lucru recurente și instrumente partajate. Publică referința reutilizabilă pentru clienți doar public atunci când nu expune controale interne, acreditări sau detalii operaționale proprietare.
5. Servicii B2B. Utilă pentru sisteme de onboarding, predări de date, specificații de fișiere, stări de aprobare și portaluri de servicii. Evită prezentarea unui angajament contractual ca pe un fapt generic de centru de ajutor atunci când termenii variază în funcție de cont.
6. Producători și afaceri industriale. Valoroasă pentru comenzi, software, compatibilitate, configurare, înregistrări de întreținere și parametri tehnici. Materialul critic pentru siguranță necesită revizuire controlată, aplicabilitate explicită a modelului și o rută către manualul autorizat.

Intenția de căutare

Intenția de căutare este rezultatul pe care o persoană îl așteaptă de la o interogare. Intenția documentației este de obicei navigațională plus informațională: cel care caută cunoaște produsul sau obiectul și dorește un fapt exact, cum ar fi „perioada de păstrare a exporturilor Northstar”, „valorile de stare Northstar” sau „dimensiunea paginii API Northstar”. Marca, funcționalitatea, limbajul sarcinii fără erori, versiunea și platforma apar adesea împreună.

Rezultatul ideal se deschide aproape de răspuns. Folosește titluri descriptive, ancore stabile, valori acceptate și calificatori de versiune. O afirmație extrasă trebuie să își păstreze condiția: „În planurile Team și Enterprise, exporturile finalizate rămân disponibile timp de 30 de zile.”

Documentația publică ar trebui să se claseze atunci când răspunde la o întrebare durabilă fără a dezvălui date ale contului: formate suportate, câmpuri API publice, compatibilitate, limite, semnificația configurării și comportament documentat.

Documentația nu ar trebui să se claseze atunci când oglindește o singură etichetă UI, duplică o pagină curentă, acoperă o versiune învechită fără nevoie continuă, expune detalii sensibile sau necesită context privat de cont. Folosește ajutor autentificat, ghidare în aplicație, noindex, consolidare sau o stare de arhivă clară. Cererea de căutare nu justifică niciodată publicarea secretelor sau a căilor de exploatare.

Structura paginii

Benzile de cuvinte sunt controale de producție, nu cote minime. O referință îngustă de câmp poate fi mai scurtă; o referință de funcționalitate versionată poate necesita mai mult spațiu, deoarece aplicabilitatea și excepțiile previn greșelile costisitoare.

Cele mai multe articole de documentație substanțiale se încadrează între 1.500 și 2.800 de cuvinte. Adaugă detalii doar acolo unde previn ambiguitatea: domeniu, cerință prealabilă, valoare, implicit, efect secundar, excepție sau modificare de versiune.

Elemente obligatorii

Cititorii de referință scanează. Plasează informația de aplicabilitate înaintea referinței, astfel încât o valoare corectă din punct de vedere tehnic să nu fie aplicată planului sau lansării greșite.

Frontmatter

Urmează specificația frontmatter. Pe această specificație de tip de postare, entity = "post-type-documentation-article". Pe o pagină de documentație produsă, folosește o valoare stabilă de obiect de produs, cum ar fi northstar-scheduled-export-settings, nu o frază promoțională precum effortless-reporting și nici un număr de versiune care ar forța o nouă identitate după fiecare lansare.

Folosește schemaType = "Article". Marcajul schema trebuie să descrie pagina vizibilă; nu selecta HowTo doar pentru că un exemplu conține trei acțiuni. Adaugă date structurate FAQ doar atunci când întrebările și răspunsurile vizibile se potrivesc exact cu acestea. Semantica de referință API sau specifică software-ului poate fi reprezentată în altă parte în modelul de date al site-ului, dar un tip de schemă mai specific nu ar trebui inventat în frontmatter fără suport de șablon.

Stochează câmpurile pe care sistemul de întreținere le poate aplica: zona de produs, planurile, rolul, platforma, gama de versiuni, data verificării, proprietarul și URL-ul de înlocuire. lastmod înseamnă că comportamentul a fost revizuit, nu că o greșeală de tipar a fost corectată. Păstrează URL-ul canonic de-a lungul lansărilor compatibile.

Exemplu complet

Acest exemplu fictiv de analitică demonstrează o pagină de referință, nu o procedură completă de export.

# Setări de export programat

Exporturile programate creează un fișier CSV sau JSON dintr-un raport salvat la o oră UTC fixă și îl livrează la o destinație aprobată. Sunt disponibile pentru Editori și Administratori în planurile Team și Enterprise. Această referință se aplică aplicației web Northstar Analytics 6.4 și a fost verificată pe 27 august 2026.

## Înainte de a folosi această referință

Ai nevoie de un raport salvat existent, o destinație activată și acces de Editor sau Administrator. Un Vizualizator poate descărca un export existent, dar nu poate crea sau modifica o programare. Administratorii destinației pot impune limite suplimentare de păstrare sau dimensiune a fișierului.

## Referință setări

| Setare | Valoare acceptată | Implicit | Efect și constrângeri |
|---|---|---|---|
| Nume | 1–80 caractere | Numele raportului | Identifică programarea; schimbarea lui nu redenumește fișierele anterioare. |
| Format | `csv` sau `json` | `csv` | CSV folosește ordinea vizibilă a coloanelor din raport. JSON folosește chei stabile de câmp. |
| Ora execuției | `HH:MM` în UTC | `08:00` | Modificările de oră de vară/iarnă nu mută ora de execuție UTC. |
| Include rânduri goale | Activat sau dezactivat | Dezactivat | Disponibil doar pentru rapoarte tabelare; ignorat pentru rapoarte sumar. |
| Păstrare | 1–30 de zile | 7 zile | Fișierele existente expiră independent de programarea care le-a creat. |

## Comportament și limite

O programare citește configurația raportului salvat când execuția începe. Editarea raportului modifică astfel fișierele viitoare, dar nu și fișierele deja generate. Pauzarea unei programări previne noi execuții; nu șterge fișierele păstrate. Ștergerea destinației dezactivează livrarea și plasează programarea în starea `Necesită atenție`.

## Exemplu

Pentru un CSV zilnic necesar la 09:00 în Bratislava, în timpul orei standard, setează ora de execuție UTC la `08:00`. Revizuiește ora când regulile de oră de vară/iarnă se schimbă, deoarece programările rămân fixate la UTC.

Exemplu invalid: introducerea `Europe/Bratislava` în câmpul orei de execuție. Câmpul acceptă o oră UTC, nu un identificator de fus orar.

## Diferențe între versiuni

- Versiunea 6.4: Exporturile JSON folosesc chei stabile de câmp; eticheta coloanei afișate nu mai devine cheia.
- Versiunile 6.1–6.3: Cheile JSON urmează etichetele coloanelor afișate. Integrările existente ar trebui verificate înainte de upgrade.
- Înainte de 6.1: Exportul JSON programat nu este disponibil. Folosește CSV sau fă upgrade la o versiune suportată.

## Dacă un export nu sosește

Nu adăuga soluții speculative aici. Deschide ghidul de depanare „Exportul programat nu a sosit”, care verifică starea programării, autorizarea destinației, limitele de fișiere și incidentele de serviciu în ordine diagnostică.

## Sarcini conexe

- Creează primul tău export programat — configurare ordonată și verificare de succes
- Depanează un export programat lipsă — diagnostic bazat pe simptome
- Note de lansare Northstar Analytics 6.4 — modificări de comportament și notă de migrare

## Înregistrare verificare

Verificat față de aplicația web 6.4 de către proprietarul produsului Reporting pe 27 august 2026. Revizuiește când se schimbă permisiunile, formatele, păstrarea, programarea sau comportamentul destinației.

Galerie de design

Folosește setări, limite, roluri și informații de versiune identice în toate variantele, astfel încât revizuirea designului să măsoare viteza de regăsire, nu diferențele de text.

Listă de verificare a calității

Un articol de documentație este gata doar atunci când fiecare afirmație aplicabilă este adevărată:

• Deschiderea numește obiectul exact și oferă comportamentul curent înainte de context sau beneficii.
• Aplicabilitatea produsului, planului, rolului, regiunii, platformei și versiunii este explicită acolo unde schimbă răspunsul.
• Cerințele prealabile apar înaintea setărilor sau exemplelor care depind de ele.
• Fiecare termen tehnic este definit la prima utilizare, exprimat printr-o etichetă de interfață familiară sau legat la definiția sa canonică.
• Câmpurile, valorile, valorile implicite, unitățile, formatele, limitele și efectele secundare provin dintr-o sursă autorizată sau un test verificat de produs.
• Tabelele de referință folosesc dimensiuni consistente; celulele goale nu ascund valori implicite sau excepții necunoscute.
• Exemplele menționează condițiile care le fac valide și includ un exemplu invalid sau limită atunci când confuzia este probabilă.
• Avertizările apar înaintea comportamentului distructiv, ireversibil, sensibil la securitate, costisitor sau care modifică permisiunile.
• Capturile de ecran includ o versiune de captură și un echivalent text; imaginea nu este singura sursă a unei valori sau instrucțiuni.
• Titlurile și ancorele se potrivesc cu substantivele pe care utilizatorii le caută și rămân stabile pentru linkuri adânci.
• Diferențele materiale între versiuni menționează gama afectată, înlocuitorul curent și consecința migrării.
• Data verificată reflectă o revizuire comportamentală, iar o echipă sau un rol numit deține următoarea revizuire.
• Procedurile, diagnosticarea și istoricul lansărilor trimit la paginile surori canonice în loc să fie duplicate incomplet.
• Indexarea publică este intenționată; materialul învechit, duplicat, privat și sensibil la securitate are un tratament de căutare adecvat.
• Înregistrările FAQ se potrivesc cu răspunsurile vizibile, iar CTA respectă sarcina următoare a unui cititor în stadiul de suport.

Greșeli comune

Scrierea unei pagini de prezentare a funcționalității pentru un utilizator existent. „Deblocați exporturi puternice” întârzie informația de care cititorul are nevoie. Condu cu comportamentul, aplicabilitatea și constrângerile; textul de beneficii aparține doar acolo unde clarifică scopul.

Transformarea fiecărei sarcini în documentație. O configurare în 20 de pași îngropată sub o listă de câmpuri nu servește nici consultării, nici finalizării. Separă procedura ordonată într-un ghid practic și linkuiește-o din secțiunea relevantă de cerințe prealabile sau sarcini conexe.

Publicarea unei pagini pentru fiecare etichetă de interfață. Paginile subțiri se suprapun și multiplică întreținerea. Grupează câmpurile în jurul unui obiect de produs stabil, cu excepția cazului în care o setare are un comportament distinct.

Folosirea „ultima versiune” ca versiune. Ultima versiune se schimbă. Menționează lansarea testată, gama suportată, platforma și data verificării, apoi actualizează-le prin procesul de lansare.

Păstrarea paginilor vechi și noi indexabile fără o delimitare. Consolidează comportamentul compatibil; în caz contrar, etichetează versiunea veche, linkuiește la pagina curentă și controlează indexarea intenționat.

Ascunderea cerințelor prealabile în erori. Dacă doar Administratorii pot modifica un câmp, spune-o înaintea referinței. Nu face un Vizualizator să descopere limita de rol după ce a urmat un exemplu.

Copierea capturilor de ecran în locul comportamentului. O captură este dovada unei stări de interfață, nu specificația. Scrie etichetele, căile, valorile și condițiile în text accesibil și înregistrează versiunea capturată.

Falsificarea actualității. Schimbarea datei fără retestarea comportamentului face pagina să pară mai sigură, în timp ce crește riscul. Actualizează înregistrarea de verificare doar după ce proprietarul său verifică afirmațiile aplicabile.

Lăsarea căutării publice să expună detalii interne. Căile interne de escaladare, secretele, identificatorii clienților, instrucțiunile de exploatare și comportamentul neanunțat nu devin sigure deoarece reduc efortul de suport. Separă ajutorul public de cunoștințele autentificate și interne.

Linkuri interne

Linkuiește în sus către tipuri de postări SEO atunci când autorul poate avea nevoie de o formă diferită de răspuns. Linkuiește dintr-o cerință prealabilă de documentație către ghidul practic canonic doar atunci când un cititor trebuie să finalizeze mai întâi acea sarcină. Linkuiește dintr-o stare de eroare către depanare, în loc să inserezi o listă generică de soluții. Linkuiește dintr-o diferență de versiune către evenimentul de lansare atunci când istoricul modificărilor adaugă context; notele de lansare ar trebui să trimită înapoi la documentația curentă ca sursă durabilă de adevăr.

Organizează linkurile în jurul obiectelor de produs și al stării cititorului. Păstrează un link specific lângă afirmația care creează următoarea întrebare, în loc să te bazezi pe o listă lungă de articole asociate.

O pagină curentă canonică ar trebui să dețină comportamentul stabil. Păstrează paginile de versiune doar pentru comportament material diferit de care utilizatorii au încă nevoie și fă această distincție explicită. Folosește ancore stabile precum #retention, nu #table-2.

Cum să măsori rezultatele

Măsoară dacă utilizatorii regăsesc răspunsul corect pentru versiunea lor. Traficul singur este o dovadă slabă: o creștere bruscă poate reflecta un produs defect sau un răspuns învechit.

Înregistrează interogările țintă, URL-ul de clasare, indexabilitatea, versiunile suportate, căutările în suport, ieșirile către sarcini conexe și un eveniment de produs potrivit. Apoi revizuiește:

• impresiile de căutare și vizitele calificate pentru interogări de obiect de produs, câmp, limită, sintaxă, rol și versiune;
• rafinările căutării interne, căutările cu zero rezultate și căutările repetate care dezvăluie terminologie lipsă;
• implicarea cu secțiunile ancorate, mai degrabă decât timpul nediferențiat pe pagină;
• clicurile către configurarea corectă, depanarea, lansarea sau destinația de suport;
• contactele de suport a căror întrebare ar trebui să fie răspunsă de pagină, segmentate pe versiune și rol acolo unde confidențialitatea permite;
• citările care păstrează valoarea împreună cu planul, versiunea, unitatea sau cerința prealabilă;
• URL-urile învechite care încă se clasează sau sunt citate după consolidare sau retragere;
• modificările de documentație cauzate de lansări, schimbări de interfață, schimbări de politici și cazuri recurente de suport.

Folosește urmărirea prompturilor pentru întrebări de consultare cu brand și variante de versiune. Folosește inteligența surselor și citărilor pentru a vedea ce URL citează un motor de răspunsuri și dacă rezumatul său păstrează condițiile. Deschide Cockpit-ul AmICited pentru a compara URL-urile citate, vizibilitatea, activitatea organică de aterizare și evenimentul de produs sau suport ales pe aceeași fereastră de observație.

Urmează cum măsurăm rezultatele pentru a separa descoperirea, reprezentarea, implicarea, progresul sarcinilor și retenția. Adnotează lansările și incidentele înainte de a interpreta mișcările. Un răspuns cu zero clicuri funcționează doar atunci când păstrează valoarea curentă și condițiile sale.

FAQ

Întrebări frecvente