La base di conoscenze: Il tuo migliore amico come scrittore tecnico

Conosci la sensazione di stare di fronte a una montagna di informazioni e non sapere da dove iniziare.
Come scrittore tecnico, questo è il tuo "pane quotidiano".

Ma cosa succederebbe se avessi uno strumento per aiutarti a conquistare questa montagna? Ecco di cosa si tratta oggi: Ci immergiamo nel mondo delle basi di conoscenza e vediamo come ti supportano nel tuo lavoro di scrittore tecnico.

Una base di conoscenza è come un cervello digitale per la tua azienda, il tuo team e / o i tuoi progetti. Raccoglie, struttura e conserva tutte le conoscenze necessarie per creare la tua documentazione. Dalle specifiche tecniche alle istruzioni agli sfondi, troverai tutto in un unico posto. Ciò non solo consente di risparmiare tempo, ma garantisce anche che i documenti siano sempre accurati e aggiornati. Se qualcuno si prende cura di lei. ??

Cos'è una Knowledge Base?

Pensa a una base di conoscenze come a una sorta di archivio centrale. Si tratta di una raccolta di informazioni che è disponibile in una forma organizzata e ricercabile. La cosa speciale a riguardo: È accessibile a tutti nel team.

L'idea alla base: Che si tratti delle ultime caratteristiche del prodotto, dei termini giusti o degli errori comuni, invece di inviare un'e-mail con ogni problema o frugare nelle vecchie chat, basta guardare nel database. Questo non solo ti rende più efficiente, ma anche veri gestori della conoscenza.

Specifiche tecniche: Il cuore del tuo lavoro

Se stai costruendo una base di conoscenze, le specifiche tecniche sono il be-all e end-all. Pensa a cose come:

Schemi architettonici: Come sono collegati i diversi componenti?
Documentazione API: Quali sono gli endpoint e come funzionano?
Descrizioni funzionali: Cosa fa il prodotto e qual è la logica dietro di esso?

Memorizzando queste informazioni centralmente, ti assicuri che tutti coloro che lavorano alla documentazione siano sulla stessa pagina. Questo evita errori e salva un numero infinito di turni di voto.

Gli strumenti giusti per la tua base di conoscenze

Il tuo successo nella costruzione di una base di conoscenze dipende in gran parte dagli strumenti giusti. A seconda delle dimensioni del progetto e del flusso di lavoro del team, ci sono varie soluzioni adatte a te. Alcuni strumenti si basano su linguaggi di markup semplici come Markdown, mentre altri, come soluzioni all-in-one, coprono tutte le fasi della documentazione.

Strumenti di ufficio comuni come Word / Google Docs / Notepad ++ ti aiutano a scrivere, ma vengono poi memorizzati da qualche parte come singoli file e una ricerca su vari documenti non sarebbe l'ideale. Per una migliore visualizzazione, spesso si utilizzano strumenti del portfolio Adobe (Illustrator, Photoshop, InDesign, ecc.) Ma tutto questo deve essere archiviato nel modo più coerente, strutturato e accessibile possibile, in modo che in seguito idealmente non sia necessario alcun grande sforzo per rendere questo contenuto disponibile agli utenti.

Quindi diamo un'occhiata ad alcune delle opzioni più comuni che gli scrittori tecnici possono supportare oggi.

1. Marcatura & Docs-as-Code

Cos'è questo? Markdown è un linguaggio di markup estremamente semplice e intuitivo. Scrivi i tuoi testi in semplici file di testo con una formattazione minima e puoi quindi convertirli in HTML. In combinazione con un sistema di controllo di versione come Git, questa è la base per un approccio "docs-as-code" in cui la documentazione è trattata come software.
Benefici:
- Semplice e veloce: Markdown è così semplice che tutti lo capiscono subito. Ideale per brevi, brevi note o documenti su cui lavorano anche gli sviluppatori.
- Controllo della versione: Ogni cambiamento è tracciato. Puoi sempre vedere chi ha cambiato cosa e quando e puoi tornare a una versione precedente se necessario.
- Collaborazione: Sviluppatori e scrittori tecnici possono lavorare insieme nello stesso ambiente (ad esempio Git).
Svantaggi:
- Formattazione limitata: Il markdown spesso non è sufficiente per layout complessi, tabelle o formattazione speciale.
- Nessuna gestione centrale: Senza strumenti aggiuntivi (come un generatore statico di siti web), è difficile gestire una base di conoscenze complessa.

Gli strumenti di Markdown sono disponibili praticamente per tutte le piattaforme e in varie varianti:

Mac: MacDown, Scrittore iA, oppure Contrassegnato 2 iOS / Android: Scrittore iA Finestre: ghostwriter oppure Mostro di Markdown Linux: ReText o anche il ghostwriter Web: Dillinger oppure StackModifica

2. AsciiDoc & Docs-as-Code

Cos'è questo? AsciiDoc è un'alternativa più potente a Markdown. È anche un linguaggio di markup semplice, ma offre molte più funzionalità per la documentazione tecnica. Ancora una volta, l'idea è quella di scrivere la documentazione in file di testo e gestirla attraverso sistemi di controllo di versione.
Benefici:
- Sintassi completa: AsciiDoc supporta funzioni come riferimenti incrociati, variabili, testi condizionali e tabelle complesse. Ideale per una documentazione professionale e completa.
- Riutilizzabilità: È possibile definire moduli di testo (ad esempio una nota di sicurezza) in un unico posto e riutilizzarli in molti documenti. Ciò consente di risparmiare tempo e garantisce coerenza.
- Flessibile: I file di testo possono essere esportati in diversi formati (HTML, PDF, EPUB).
Svantaggi:
- Curva di apprendimento: Iniziare è un po 'più impegnativo di Markdown perché la sintassi è più complessa.
- Nessun WYSIWYG: Non vedi direttamente come appare il risultato finale, ma devi prima compilare il documento.

Anche per AsciiDoc Esistono vari strumenti/strumenti distribuiti su tutte le piattaforme: Linux, Mac e finestre Gli utenti possono tutti Asciidotto, SciTE oppure AsciiDocFX Raggiungendo, questo Progetto AwesomeAsciiDoc Github Ma elenca anche plugin, strumenti e tutto ciò che il tuo cuore desidera.

3. DITA & il kit di strumenti aperti DITA

Cos'è questo? DITA (Architettura di tipizzazione delle informazioni Darwin) Standard basato su XML per la preparazione e la pubblicazione della documentazione tecnica. Si tratta di un approccio strutturato basato sull'idea di Argomenti (piccole unità di informazione riutilizzabili) basate. Questi argomenti saranno discussi in un Mappa di DITA Definisce la struttura della tua documentazione. Questo Kit di strumenti aperti DITA (DITA-OT) è al centro del sistema, un motore di pubblicazione open source che converte i file DITA in diversi formati di output come PDF, HTML e altro ancora. Strumenti come questo Editor XML di oXygen fornire un'interfaccia intuitiva per creare file DITA e utilizzare il DITA-OT.
Benefici:
- Massima riutilizzabilità: Gli argomenti scritti una volta possono essere riutilizzati in innumerevoli documenti. Questo è ideale per linee di prodotti o documenti con molte sezioni simili.
- Coerenza e standardizzazione: La struttura rigorosa garantisce la qualità e l'uniformità della documentazione.
- Separazione di contenuto e formato: Ti concentri solo sul contenuto. Il layout è poi determinato dal DITA-OT. In questo modo è possibile generare un documento con un clic per l'aiuto online o come manuale PDF.
Svantaggi:
- Elevata complessità e curva di apprendimento: Iniziare con DITA e XML richiede tempo e formazione speciale. Non è sicuramente per un progetto veloce.
- Costo elevato: Gli editor XML professionali, che sono praticamente indispensabili per un lavoro efficiente con DITA, sono solitamente soggetti a una tassa.

Come esempio a pagamento, ti darò qui. Framemaker di Adobe oppure ossigeno, Sono sulla pagina open source/freeware. Codex uno. A causa dello standard XML aperto e del toolkit, tuttavia, chiunque può utilizzare anche OpenJDK. Amazon Corretto oppure Azul Zulu Crea la tua base.

4. Document360

Cos'è questo? Document360 è una moderna piattaforma di knowledge base basata su cloud progettata specificamente per la creazione di help online, portali self-service e knowledge base interne.
Benefici:
- Soluzione all-in-one: Dalla creazione alla pubblicazione all'analisi del comportamento dell'utente, tutto è combinato in un unico strumento.
- Facile da usare: L'interfaccia utente è intuitiva e facile da usare anche per i non tecnici. L'editor supporta Markdown, che consente un avvio rapido.
- Strumenti di analisi: Puoi vedere quali articoli vengono letti, quali termini di ricerca usano gli utenti e dove ci sono lacune di conoscenza. Questo vi aiuterà a migliorare continuamente la vostra documentazione.
Svantaggi:
- Costi: Come soluzione software-as-a-service (SaaS), ci sono tariffe mensili o annuali che variano a seconda delle dimensioni del team.
- Dipendenza: Sei vincolato alla piattaforma e non puoi semplicemente elaborare il contenuto in un altro strumento.

Questo è una piattaforma standalone, ClosedSource, con tutti i corrispondenti vantaggi e svantaggi. Interfacce a praticamente tutti gli strumenti di helpdesk e collaborazione Tuttavia, sono disponibili, quindi l'integrazione in Techstack esistente non è un ostacolo importante.

5. Adobe RoboHelp

Cos'è questo? RoboHelp è un classico e consolidato Help Authoring Tool (HAT) di Adobe. Si tratta di uno strumento desktop che consente la creazione di aiuto online, basi di conoscenza e molto altro ancora.
Benefici:
- Funzioni estese: RoboHelp offre tutto ciò che il cuore di Technical Writer desidera: dal riutilizzo dei contenuti alla gestione delle variabili fino a layout complessi.
- Integrazione: Si integra bene con altri prodotti Adobe e sistemi esterni.
- Base stabile: Come prodotto di lunga durata, ha una grande comunità ed è molto maturo.
Svantaggi:
- Complessità: A causa delle molte caratteristiche, iniziare può essere travolgente.
- Costi: RoboHelp è anche uno strumento a pagamento che rappresenta un investimento.

Il nonno tra gli strumenti, Adobe Robohelp In realtà, questa lista non è del tutto corretta. Tuttavia, e proprio perché è estremamente esteso e anche un pioniere di molti altri strumenti a causa della sua età, non dovrebbe passare inosservato.

Istruzioni e processi: La tua guida

Una buona base di conoscenze contiene non solo informazioni statiche, ma anche istruzioni e processi dinamici. Questi possono essere, ad esempio:

Istruzioni di imbarco: Come introduci nuovi membri del team nel tuo lavoro?
Guide di stile: Quali regole si applicano alla lingua, alla formattazione e alla terminologia dei vostri documenti?
Flussi di lavoro: Come passa il processo dalla ricerca alla pubblicazione di un documento?

Tali istruzioni non solo ti aiuteranno, ma anche altre squadre. Il team di supporto può iniziare rapidamente, gli sviluppatori possono cercare come dare un feedback e anche i nuovi colleghi possono trovare la loro strada molto più velocemente. Questo rende il tuo lavoro più trasparente e il tuo team più agile.

Lo sfondo come scrittore tecnico

Come scrittore tecnico, sei il mediatore tra gli esperti e gli utenti. Hai la capacità unica di spiegare problemi complessi in modo tale che siano comprensibili a tutti. Una base di conoscenza è il tuo alleato più forte, perché ti aiuta a svolgere perfettamente questo ruolo di mediazione.

Raccogliendo le conoscenze in azienda, puoi vedere dove ci sono lacune e da dove devi iniziare. Riconosci i punti dolenti degli utenti e puoi affrontarli specificamente nella tua documentazione. Una base di conoscenze ben mantenuta non è solo un archivio di informazioni, ma anche uno specchio della tua esperienza e del tuo valore per l'azienda. Mostra che non solo scrivi, ma rendi anche l'intera conoscenza dell'azienda strutturata e accessibile.

Conclusione: Non solo uno strumento, ma un superpotere

Una base di conoscenza è molto più di un semplice strumento. È una decisione strategica che ti rende come scrittore tecnico e tutto il tuo team più efficiente, trasparente e migliore. Centralizzando la conoscenza, puoi concentrarti su ciò che sai fare meglio: Comunicare questioni complesse in modo semplice e chiaro.

TL: RD

Inizia a raccogliere e strutturare le tue conoscenze. Ne vale la pena!