La documentazione del software è semplicemente un insieme di articoli. Ma anche questi possono essere frustranti. All'inizio cerchi a lungo l'istruzione necessaria. Poi, ti confronti con un testo poco chiaro. Fai come scritto, ma il problema non si risolve. Cerchi un altro articolo, ti innervosisci... Dopo un'ora ti arrendi e te ne vai. Questo è il funzionamento di una cattiva documentazione. Cosa la rende tale e come rimediare — leggi sotto.
Nella nostra vecchia documentazione c'erano molti difetti. Da quasi un anno la stiamo rifacendo per evitare che lo scenario descritto qui sopra riguardi i nostri clienti. Dai un'occhiata, e .
Problema 1. Articoli incomprensibili e mal scritti
Se non riesci a capire la documentazione, qual è il suo senso? Ma nessuno scrive articoli incomprensibili di proposito. Succede quando l'autore non pensa al pubblico e agli obiettivi, scrive in modo ridondante e non controlla il testo per errori.
- Pubblico. Prima di scrivere un articolo, è importante considerare il livello di preparazione del lettore. È logico che in un articolo per principianti non si dovrebbero saltare i passaggi di base e lasciare termini tecnici senza spiegazione, mentre in un articolo su una funzione rara, utile solo ai professionisti, non si dovrebbe dilungarsi sul significato della parola PHP.
- Obiettivo. Un'altra cosa a cui è meglio pensare in anticipo. L'autore deve fissare un obiettivo chiaro, definire l'azione utile dell'articolo e decidere quale sarà il comportamento del lettore dopo averlo letto. Se questo non viene fatto, risulterà una descrizione per il semplice gusto di descrivere.
- Acqua ed errori. Troppa informazione superflua e linguaggio burocratico, errori e refusi ostacolano la comprensione. Anche se il lettore non è un perfezionista grammaticale, la negligenza nel testo può allontanarlo.
Seguendo i consigli sopra, gli articoli diventeranno più chiari – garantito. Per fare ancora meglio, prendi ispirazione dai nostri .
Problema 2. Gli articoli non rispondono a tutte le domande
È un problema quando la documentazione non tiene il passo con lo sviluppo, non risponde alle domande reali e gli errori non vengono corretti per anni. Questi problemi riguardano più l'organizzazione dei processi all'interno dell'azienda che l'autore stesso.
La documentazione non tiene il passo con lo sviluppo
La funzionalità è già stata rilasciata, il marketing prevede di farne un annuncio, e qui scopriamo che non c'è ancora un nuovo articolo o una traduzione nella documentazione. A causa di ciò, abbiamo persino dovuto posticipare il rilascio. Possiamo chiedere a tutti di inviare le informazioni agli scrittori tecnici puntualmente, ma questo non funzionerà. Se non automatizziamo il processo, la situazione si ripeterà.
Abbiamo apportato modifiche in YouTrack. La richiesta di scrivere un articolo sulla nuova funzionalità arriva all'autore tecnico nel momento in cui inizia il testing della funzionalità. Allo stesso tempo, il marketing viene informato per prepararsi alla promozione. Le notifiche arrivano anche nel nostro messenger aziendale Mattermost, quindi è impossibile perdere le novità dagli sviluppatori.
La documentazione non riflette le richieste degli utenti
Siamo abituati a lavorare in questo modo: una funzionalità esce, noi ne parliamo. Descriviamo come attivarla, disattivarla e fare impostazioni avanzate. Ma cosa succede se il cliente utilizza il nostro software in un modo che non avevamo previsto? O se si verificano errori a cui non abbiamo pensato?
Per avere una documentazione il più completa possibile, si consiglia di analizzare le richieste di supporto, le domande sui forum tematici e le ricerche sui motori di ricerca. È utile trasferire i temi più popolari agli scrittori tecnici, affinché possano integrare gli articoli esistenti o scriverne di nuovi.
La documentazione non viene migliorata
È difficile raggiungere la perfezione subito; ci saranno comunque degli errori. Si può sperare nel feedback dei clienti, ma è improbabile che segnalino ogni refuso, imprecisione, articolo poco chiaro o non trovato. Oltre ai clienti, anche i dipendenti leggono la documentazione, il che significa che possono vedere gli stessi errori. Questo può essere un'opportunità! È necessario solo creare le condizioni in cui sia facile segnalare un problema.
Abbiamo un gruppo nel portale interno dove i dipendenti possono lasciare commenti, suggerimenti e idee sulla documentazione. Serve un articolo al supporto, ma non c'è? Un tester ha notato un'inesattezza? Un partner ha segnalato errori ai manager dello sviluppo? Tutto in questo gruppo! Gli scrittori tecnici correggono immediatamente alcune cose, spostano altre in YouTrack e riflettono su altre. Affinché il tema non venga trascurato, di tanto in tanto ricordiamo l'esistenza del gruppo e l'importanza del feedback.
Problema 3. È difficile trovare l'articolo necessario
Un articolo che non può essere trovato non è migliore di un articolo che non esiste. Il motto di una buona documentazione dovrebbe essere "Facile da cercare, facile da trovare". Come possiamo raggiungerlo?
Ordinare la struttura e definire il principio di scelta degli argomenti. La struttura deve essere il più trasparente possibile, in modo che il lettore non si chieda "Dove posso trovare questo articolo?". In sintesi, ci sono due approcci: dall'interfaccia e dai compiti.
- Dall'interfaccia. Il contenuto replica le sezioni del pannello. Così era nella vecchia documentazione di ISPsystem.
- Dai compiti. I titoli degli articoli e delle sezioni riflettono le esigenze degli utenti; nei titoli ci sono quasi sempre verbi e risposte alla domanda 'come fare'. Ora stiamo passando a questo formato.
Qualunque approccio tu scelga, assicurati che il tema corrisponda alle richieste degli utenti e sia trattato in modo tale da risolvere esattamente il loro problema.
Impostare una ricerca centralizzata. In un mondo ideale, la ricerca dovrebbe funzionare anche quando ci si sbaglia o si commettono errori di linguaggio. La nostra ricerca in Confluence al momento non riesce a farlo. Se hai molti prodotti e la documentazione è condivisa, adatta la ricerca alla pagina in cui si trova l'utente. Nel nostro caso, la ricerca dalla homepage funziona su tutti i prodotti, mentre se ti trovi già in una sezione specifica, funziona solo sugli articoli in essa.
Aggiungere un indice e 'briciole di pane'. È utile che ogni pagina abbia un menu e le briciole di pane — il percorso dell'utente fino alla pagina attuale con la possibilità di tornare a qualsiasi livello. Nella vecchia documentazione di ISPsystem era necessario uscire dall'articolo per accedere all'indice. Era scomodo, quindi nella nuova documentazione abbiamo corretto questo.
Disporre i collegamenti nel prodotto. Se le persone continuano a contattare il supporto con la stessa domanda, è sensato aggiungere un suggerimento con la sua soluzione nell'interfaccia. Se hai dati o comprensione su quando l'utente incontra il problema, puoi anche avvisarlo tramite una newsletter. In questo modo dimostri cura e riduci il carico sul supporto.
A destra nella finestra pop-up è presente un link all'articolo sulla configurazione di DNSSEC nella sezione gestione domini di ISPmanager
Impostare i link incrociati all'interno della documentazione. Gli articoli che sono correlati tra loro devono essere "collegati". Se gli articoli formano una sequenza, assicurati di aggiungere frecce avanti e indietro alla fine di ciascun testo.
È probabile che una persona cerchi prima la risposta alla propria domanda su un motore di ricerca piuttosto che da te. È frustrante se non ci sono link alla documentazione per motivi tecnici. Quindi, occupati dell'ottimizzazione per i motori di ricerca.
Problema 4. Un layout obsoleto ostacola la comprensione
Oltre a testi scadenti, il design può rovinare la documentazione. Le persone sono abituate a leggere materiali ben impaginati. Blog, social media, media — tutto il contenuto è presentato in modo non solo bello, ma anche leggibile e gradevole per gli occhi. È quindi facile comprendere il dolore di chi vede il testo come nello screenshot seguente.
In questo articolo ci sono così tanti screenshot e evidenziazioni che non aiutano, ma anzi ostacolano la comprensione (l'immagine è cliccabile).
Non bisogna trasformare la documentazione in un longread pieno di effetti, ma è necessario considerare alcune regole di base.
Impaginazione. Definisci la larghezza del testo principale, il font, la dimensione, i titoli e i margini. Coinvolgi un designer, e per accettare il lavoro o gestire la situazione da solo, leggi il libro di Artem Gorbunov "Tipografia e Impaginazione". Presenta solo una delle visioni sull'impaginazione, ma è più che sufficiente.
Evidenziazioni. Definisci quali elementi del testo richiedono enfasi. Di solito si tratta di percorsi nell'interfaccia, pulsanti, snippet di codice, file di configurazione, blocchi "Attenzione". Stabilite come dovranno essere evidenziati questi elementi e documentatelo. Ricorda che meno evidenziazioni ci sono, meglio è. Quando ce ne sono troppe, il testo risulta "rumoroso". Anche le virgolette possono creare rumore se usate troppo frequentemente.
Screenshot. Concorda con il team in quali casi siano necessari screenshot. Non è necessario illustrare ogni passaggio in dettaglio. Un numero eccessivo di screenshot, inclusi quelli di singoli pulsanti, può ostacolare la comprensione e rovinare il layout. Definisci le dimensioni e il formato delle evidenziazioni e delle didascalie negli screenshot e documentali. Ricorda che le illustrazioni devono sempre corrispondere al testo scritto e essere aggiornate. Ancora una volta, se il prodotto viene aggiornato regolarmente, sarà difficile tenere il passo con ogni cambiamento.
Lunghezza del testo. Evita articoli eccessivamente lunghi. Suddividili in parti e, se non possibile, aggiungi all'inizio dell'articolo un sommario con link ancorati. Un modo semplice per rendere l'articolo visivamente più breve è nascondere i dettagli tecnici, rilevanti solo per un pubblico ristretto, sotto un spoiler.
Formati. Combina più formati negli articoli: testo, video e immagini. Questo migliorerà l'esperienza del lettore.
Non cercare di nascondere i problemi con un'impaginazione accattivante. Onestamente, anche noi speravamo che il 'packaging' potesse salvare la documentazione obsoleta — non è andata così. Nei testi c'era così tanto rumore visivo e dettagli superflui che il regolamento e il nuovo design non hanno potuto aiutare.
Molto di quanto descritto sopra sarà determinato dalla piattaforma che utilizzi per la documentazione. Noi, ad esempio, usiamo Confluence. Anche con questo ci sono stati dei problemi. Se ti interessa, leggi il racconto del nostro sviluppatore web: .
Da dove iniziare a migliorare e come sopravvivere
Se la tua documentazione è complessa come quella di ISPsystem e non sai da dove iniziare, comincia con i problemi più gravi. Se i clienti non comprendono la documentazione, lavora per migliorare i testi, stabilisci delle linee guida e addestra gli scrittori. Se la documentazione è obsoleta, affronta i processi interni. Parti dagli articoli più letti sui prodotti più richiesti: chiedi supporto, guarda l'analitica del sito e le ricerche nei motori di ricerca.
Diciamo subito che non sarà facile. E neanche veloce, probabilmente. A meno che tu non stia iniziando ora e stia già facendo le cose nel modo giusto. Una cosa è certa: col tempo migliorerà. Ma il processo non finirà mai :-).
Fonte: habr.com
