A documentazione di u software hè solu una cullizzioni di articuli. Ma ancu elli ponu arrabbià. Prima, cercate l'istruzzioni ghjusta per un bellu pezzu. Allora capisce u testu obscur. Fate cum'è scrittu, ma u prublema ùn hè micca risoltu. Circate un altru articulu, site nervoso... Dopu à una ora, sputate nantu à tuttu è parte. Questu hè cumu funziona a documentazione cattiva. Ciò chì face cusì, è cumu per riparà - leghje sottu u cut.
Ci era parechje difetti in a nostra vechja documentazione. Dapoi quasi un annu, l'avemu rielaboratu per chì u scenariu descrittu sopra ùn cuncerna micca i nostri clienti. guarda, и .
Prublemu 1. Articuli incomprensibili, pocu scritti
Se a documentazione hè impussibile à capisce, chì hè u puntu di questu? Ma nimu scrive articuli incomprensibili apposta. Sò ottenuti quandu l'autore ùn pensa micca à l'audienza è u scopu, versa l'acqua è ùn verifica micca u testu per errori.
- L'udienza. Prima di scrive un articulu, avete bisognu di pensà à u livellu di preparazione di u lettore. Hè logicu chì in un articulu per un principiante, ùn deve micca saltà i passi basi è lascià i termini tecnichi senza decodificà, è in un articulu nantu à una funzione rara chì solu i prufessi necessitanu, masticate u significatu di a parolla PHP.
- Goal. Un'altra cosa da pensà prima di u tempu. L'autore deve stabilisce un scopu chjaru, determinà l'azzione utile di l'articulu, decide ciò chì u lettore farà dopu avè lettu. Se questu ùn hè micca fattu, uttene una descrizzione per a descrizzione.
- Acqua è bug. Un saccu di infurmazioni innecessarii è cléricalismu, errori è typos interferiscenu cù a percepzioni. Ancu s'è u lettore ùn hè micca un Nazi Grammaticu, sloppiness in u testu pò disattivà.
Cunsiderate i cunsiglii sopra, è l'articuli diventeranu più chjaru - garantitu. Per fà ancu megliu, apprufittate di i nostri .
Prublemu 2. L'articuli ùn rispondenu micca à tutte e dumande
Hè male quandu a ducumentazione ùn mantene micca cù u sviluppu, ùn risponde micca e dumande reali, l'errori in questu ùn sò micca curretti per anni. Quessi sò prublemi micca tantu di l'autore, ma di l'urganizazione di prucessi in a cumpagnia.
A documentazione ùn riesce à seguità u sviluppu
A funzione hè digià in a liberazione, i piani di cummercializazione per copre, è poi si trova chì u novu articulu o traduzzione ùn hè ancu micca in a documentazione. Per via di questu, avemu ancu avutu a posponà a liberazione. Pudete dumandà à tutti di turnà u compitu à i scrittori tecnichi à tempu, ma ùn hà micca travagliatu. Se u prucessu ùn hè micca automatizatu, a situazione si ripete.
Avemu fattu cambiamenti à YouTrack. U compitu di scrive un articulu nantu à una nova funzione casca à u scrittore tecnicu in u mumentu chì a funzione hè pruvata. Allora u marketing ampara nantu à questu per preparà per a prumuzione. E notificazioni venenu ancu à u messenger corporativu di Mattermost, cusì hè simplicemente impussibile di sminticà e nutizie da i sviluppatori.
A documentazione ùn riflette micca e dumande di l'utilizatori
Avemu travagliatu cusì : una funzione hè surtita, ne parlavamu. Descrittu cumu per accende, spegne, fate aghjustamenti fini. Ma chì se u cliente usa u nostru software in modi chì ùn avemu micca aspittatu? O hà bug chì ùn avemu micca pensatu ?
Per fà a documentazione cum'è cumpleta pussibule, vi cunsigliemu di analizà e dumande di supportu, dumande nantu à i fori tematichi, dumande in i mutori di ricerca. Dà i temi più populari à i scrittori tecnichi per aghjunghje à l'articuli esistenti o scrivite novi.
A documentazione ùn hè micca aghjurnata
Hè difficiule di fà subitu, i sbagli seranu sempre. Pudete confià nantu à u feedback di i clienti, ma hè improbabile ch'elli signalanu ogni typo, imprecisione, incomprensibile o micca truvatu articulu. In più di i clienti, l'impiegati leghjenu a documentazione, chì significa chì vedenu i stessi errori. Pò esse usatu! Hè solu necessariu di creà e cundizioni in quale serà faciule per rapportà un prublema.
Avemu un gruppu nantu à u portale internu induve l'impiegati lascianu cumenti, suggerimenti è idee per a documentazione. U supportu hà bisognu di un articulu, ma ùn hà micca? U tester hà nutatu una imprecisione? L'associu s'hè lagnatu à i gestori di sviluppu per i sbagli? Tutti in stu gruppu! Scrittori tecnichi riparanu qualcosa subitu, trasferiscenu qualcosa à YouTrack, pigliate qualcosa per pensà. Per mantene u tema vivu, di tantu in tantu vi ricurdemu l'esistenza di u gruppu è l'impurtanza di i rispunsevuli.
Prublemu 3. Avete da circà l'articulu ghjustu per un bellu pezzu
Un articulu chì ùn si pò truvà ùn hè micca megliu cà un articulu chì ùn esiste micca. U mottu di una bona documentazione deve esse "Facile à circà, faciule à truvà". Cumu ottene questu?
Organizà a struttura è determina u principiu di scelta di temi. A struttura deve esse u più trasparente pussibule per chì u lettore ùn pensa micca "Induve possu truvà questu articulu?". Per riassume, ci sò dui approcci: da l'interfaccia è da i travaglii.
- Da l'interfaccia. U cuntenutu duplicate e sezzioni di u pannellu. Cusì era in l'antica documentazione ISPsystem.
- Da i travaglii. I tituli di l'articuli è e rùbbriche riflettenu i travaglii di l'utilizatori; I tituli anu quasi sempre verbi è risposte à a quistione "cumu fà". Avà andemu à stu furmatu.
Qualunque sia l'approcciu chì sceglite, assicuratevi chì u tema hè pertinenti à i bisogni di l'utilizatori è hè cupartu in una manera chì l'utilizatore risolverà accuratamente a so quistione.
Stabbilisce una ricerca centralizzata. In un mondu ideale, a ricerca deve travaglià ancu quandu avete sbagliatu o fate un sbagliu cù a lingua. A nostra ricerca in Confluence finu à avà ùn pò micca piacè cun questu. Sì avete parechji prudutti è a documentazione hè generale, adatta a ricerca à a pagina chì l'utilizatore hè. In u nostru casu, a ricerca nantu à a pagina principale travaglia per tutti i prudutti, è se site digià in una sezione specifica, allora solu per l'articuli in questu.
Aghjunghjite cuntenutu è breadcrumbs. Hè bonu quandu ogni pagina hà un menu è breadcrumbs - a strada di l'utilizatori à a pagina attuale cù a capacità di vultà à ogni livellu. In l'antica documentazione di l'ISPsystem, duvete abbandunà l'articulu per entra in u cuntenutu. Era inconveniente, cusì l'avemu riparatu in u novu.
Pone ligami in u pruduttu. Se a ghjente vene à sustene cù a listessa quistione una volta è più, hè ragiunate per aghjunghje un tooltip cù a so suluzione à l'interfaccia. Sì avete dati o capiscenu à quale puntu l'utilizatore hà avutu un prublema, pudete ancu avvisà cù una lista di mailing. E mostra cura, è caccià a carica da u supportu.
A destra in a finestra pop-up ci hè un ligame à un articulu nantu à a cunfigurazione di DNSSEC in a sezione di gestione di domini di ISPmanager.
Stabilite riferimenti incruciati in a documentazione. L'articuli chì sò ligati devenu esse "ligati". Se l'articuli sò in una sequenza, assicuratevi di aghjunghje frecce in avanti è in daretu à a fine di ogni testu.
Hè assai prubabile, una persona andarà prima à circà una risposta à a so dumanda micca à voi, ma à un mutore di ricerca. Hè una vergogna s'ellu ùn ci hè micca ligami à a documentazione quì per ragioni tecniche. Allora pigliate cura di l'optimizazione di u mutore di ricerca.
Prublemu 4. U layout anticu interferiscenu cù a percepzioni
In più di i testi cattivi, u disignu pò arruvinà a documentazione. A ghjente hè abituata à leghje materiali ben scritti. Blogs, rete suciale, media - tuttu u cuntenutu hè presentatu micca solu bella, ma ancu faciule di leghje, piacevule à l'ochju. Per quessa, hè facile à capisce u dulore di una persona chì vede u testu cum'è in u screenshot sottu.
Ci sò tanti screenshots è highlights in questu articulu chì ùn aiutanu micca, ma solu interferiscenu cù a percepzione (a stampa hè clicable)
Ùn deve micca fà una longa lettura di a ducumentazione cù una mansa di effetti, ma avete bisognu di piglià in contu e regule basiche.
Disposizione. Determina a larghezza di u testu di u corpu, u font, a dimensione, l'intestazione è u padding. Implica un designer, è per accettà u travagliu o manighjate sè stessu, leghjite u libru di Artyom Gorbunov Typography and Layout. Presenta solu una di e viste nantu à u layout, ma hè abbastanza.
Allocazioni. Determina ciò chì deve enfasi in u testu. Di solitu questu hè un percorsu in l'interfaccia, i buttoni, l'inserzioni di codice, i schedarii di cunfigurazione, i blocchi Pay Attention. Specificate quale serà a selezzione di questi elementi è risolve in i regulamenti. Tenite in mente chì menu secrezioni, u megliu. Quandu ci sò assai, u testu hè "rumore". Ancu i virgolette creanu rumore si sò usati troppu spessu.
Screenshots. Accordu cù a squadra quandu i screenshots sò necessarii. Di sicuru, ùn hè micca necessariu di illustrà ogni passu. Un gran numaru di screenshots, incl. i buttoni individuali, interferiscenu cù a percepzioni, spoil the layout. Determinà a dimensione, è ancu u formatu di i punti culminanti è i captioni nantu à i screenshots, fighjate in i regulamenti. Ricurdativi chì l'illustrazioni deve sempre currisponde à ciò chì hè scrittu è esse aghjurnatu. In novu, se u pruduttu hè aghjurnatu regularmente, serà difficiule di seguità ogni unu.
Lunghezza di u testu. Evite articuli troppu longu. Spartite in parte, è s'ellu ùn hè micca pussibule, aghjunghje cuntenutu cù ligami di ancora à u principiu di l'articulu. Un modu faciule per fà un articulu visualmente più curtu hè di ammuccià i dettagli tecnichi chì un cerculu strettu di lettori hà bisognu sottu un spoiler.
Formati. Unisce parechji formati in articuli: testu, video è imagine. Questu hà da migliurà a percepzione.
Ùn pruvate micca di copre i prublemi cù un bellu layout. Onestamente, noi stessi speremu chì u "wrapper" salvassi a documentazione obsoleta - ùn hà micca travagliatu. Ci era tantu rumore visuale è dettagli innecessarii in i testi chì i regulamenti è u novu disignu eranu impotenti.
A maiò parte di ciò chì sopra serà determinata da a piattaforma chì utilizate per a documentazione. Per esempiu, avemu Confluence. Hà avutu ancu à trattà cun ella. Sè interessatu, leghjite a storia di u nostru sviluppatore web: .
Induve cumincià à migliurà è cumu sopravvive
Se a vostra documentazione hè vasta quant'è quella di l'ISPsystem è ùn sapete micca ciò chì pigliate, cuminciate cù i prublemi più serii. I clienti ùn capiscenu micca u dock - migliurà i testi, facenu regulamenti, furmà i scrittori. A ducumentazione hè fora di data - piglià nantu à i prucessi internu. Accuminciate cù l'articuli più populari nantu à i prudutti più richiesti: dumandate supportu, vede l'analisi di u situ è e dumande di u mutore di ricerca.
Dicemu solu chì ùn serà micca faciule. È hè improbabile ancu chì succede rapidamente. A menu chì ùn site appena principiatu è fate a cosa ghjustu subitu. Una cosa hè certa, sarà megliu cù u tempu. Ma u prucessu ùn finirà mai :-).
Source: www.habr.com