ABONAMENTE VIDEO REDACȚIA
RO
EN
×
▼ LISTĂ EDIȚII ▼
Numărul 95
Abonament PDF

Abilitățile unui Technical Writer (II) - Cum lucrează?

Melania Duma
Technical Writer @ SDL Plc



Sonia Pavlenko
Technical Writer @ Accenture Industrial Software S
DIVERSE


Fie că e vorba de documentația utilizată intern de echipele de dezvoltare/producție, sau despre documentația suport pentru clienți, în spatele acestora se află de cele mai multe ori un Technical Writer (TechWr). În prima parte a articolului (publicată într-un număr anterior) am abordat activitățile și provocările unui Technical Writer. în această a doua parte ne propunem să expunem și să analizăm tehnicile și instrumentele pe care le folosește un TechWr.

Ce deprinderi are un TechWr?

Cum scrie un TechWr?

Crearea de conținut este influențată de cunoașterea domeniului despre care se scrie, de cunoașterea paradigmelor TechWr și a unor instrumente (tools) specifice. Toți acești factori influențează livrarea documentației. Vom detalia mai jos relația dintre acești factori.

1. Documentația trebuie scrisă în conformitate cu standarde și cerințe internaționale.

Documentația unui produs nu poate fi livrată oricum. În funcție de domeniul în care se lucrează, documentația va trebui realizată în conformitate cu o serie de standarde de calitate internaționale: ISO/ IEC/ IEEE, ANSI, DIN, VDI . În absența unei documentații care să răspundă standardelor internaționale, produsele nu pot fi comercializate, nu pot fi supuse auditului, nu pot fi reglementate sau patentate. Un TechWr nu poate cunoaște toate standardele din toate domeniile, dar are obligația de a identifica și de a învăța care sunt standardele ce se aplică domeniului de activitate despre care scrie, iar companiile au obligația de a aloca timp acestei activități de cercetare.

În ceea ce privește standardele internaționale pe care trebuie să le respecte documentația software, menționăm:

Standard ISO/IEC/IEEE Descriere
ISO 26511: 2018 Systems and software engineering -
Requirements for managers of information
for users of systems, software, and
services
ISO 26512: 2018 Systems and software engineering -
Requirements for acquirers and suppliers
of information for users
ISO 26513 Systems and software engineering -
Requirements for testers and reviewers
of user documentation
ISO 26514 Systems and software engineering -
Requirements for designers and
developers of user documentation
ISO 26515 Systems and software engineering -
Developing information for users in an
agile environment
ISO 82079 - 1:2019 Preparation of information for use
(instructions for use) of products

Tabel 1: Standarde ISO/IEC/IEEE pentru industria software

2. Documentația trebuie realizată în conformitate cu o paradigmă/ tehnică de scriere.

După ce standardele internaționale sunt înțelese, trebuie decisă tehnica de scriere sau paradigma cu care decidem să lucrăm (Boiko 2005). Pentru industria software și industriile conexe, paradigma cea mai răspândită este DITA (Darwin Information Type Architecture). DITA presupune următoarele principii (Closs 2016):

DITA este o metodologie, un standard și o aplicație XML care a fost integrată în majoritatea instrumentelor CMS (Content Management Systems) (Gollner 2015) folosite de TechWr. Sistemele CMS (sistemele ce gestionează ciclul complet de creare - organizare - publicare de conținut) ce au integrat DITA se bazează pe DITA Open Toolkit (DITA OT) care cuprinde elemente de limbaj, fișiere schema (DTD sau XSD), mostre de fișiere și transformatori. Pentru a lucra cu DITA, minimul necesar este DITA OT și un editor XML. Acestea vă vor permite să scrieți conținut DITA și să publicați conținutul în mai multe formate (RTF, PDF, HTML etc.).

Pe lângă metodologia DITA, există o serie de alte metodologii pentru structurarea informației, unele specifice doar anumitor domenii. Le prezentăm în cele ce urmează.

Paradigmă Descriere
DITA Folosită pentru documentarea produselor
software, cu posibilitatea de
extindere către alte domenii; Standard
internațional gratuit gestionat de OASIS
și IBM, cunoscut sub numele DITA OT;
Standard XML flexibil ce permite
specializarea adaptivă a structurii
conținutului, scrierea ghidată de
reguli, reutilizarea; Unitatea de bază
este topicul, o unitate de sine
stătătoare care descrie, explică, oferă
detalii suplimentare despre o temă;
Topicurile standard: concept, task
(instrucțiune), reference (referință),
glossary (glosar), troubleshooting
(soluții tehnice); Implementat de multe
editoare XML și sisteme CMS; Limitări
semantice la nivelul structurii unui
topic.
DocBook Folosită pentru publicațiile în formă
printată sau cele care au structura unei
cărți, de obicei publicații de
dimensiuni foarte mari; Standard XML cu
structură generică și semantică mai
limitată decât standardul DITA; Unitatea
de bază este modulul definit la nivel de
capitol sau sub-secțiune; Include
fișiere predefinite (dar customizabile)
de tip "stylesheet" pentru a publica
conținutul ca HTML, HTML Help sau PDF;
Momentan, standardul este disponibil ca
XML DTD sau XML Schema; Implementat de
multe editoare XML și sisteme CMS.
S1000D Folosită în industria militară sau
aviație, dar recent introdusă și în
industria feroviară, navală sau energie
eoliană pentru ghiduri ce țin de
utilizarea și mentenanța produsului;
Trebuie interpretată și customizată
pentru fiecare industrie; Standard XML
ce permite flexibilitate, scrierea
ghidată de reguli, reutilizarea; Unitate
de bază este modulul: *descriptive
information* (informație descriptivă),
fault information (informație probleme
tehnice), procedural information
(informație procedurală), *maintenance
planning information* (informație pentru
planificarea mentenanței), *parts
information* (informație referitoare la
componente); Oferă reguli pentru
crearea, gestionarea, distribuția
documentației, dar nu oferă soluții
unice/fixe pentru problemele din timpul
procesului de documentare Implementează
un standard de limbă engleză specific
acestei paradigme: ASD-STE100 Simplified
Technical English.
PiMod Folosită pentru industria
manufacturieră/mașinării/fabrici;
Standard open-source customizabil;
Unitatea de bază este modulul de tip:
task (instrucțiune/ sarcină de lucru),
descriptive (descriere), diagnosis
(diagnostic), tools (instrumente),
task intervals (interval între sarcini
de lucru), lubrication (lubrifiere),
glossary (glosar); Clasificarea se
face per produs și per tip de
informație; Se poate integra cu multe
sisteme CMS, unele având principiile
PiMod integrate nativ.
Information Mapping Folosită pentru dezvoltarea materialelor
de tip eLearning ; Structurarea
informației se bazează pe rezultatele
studiilor cognitive; Unitățile de bază
sunt block (sau topic) și map (hartă =
mai multe elemente block, având un
key block ce conține informația
principală și elemente block
adiționale); Tipurile de informație
standardizate sunt: procedure
(procedura), process (procesul),
principle (principiul), concept
(conceptul), structure (structura),
fact (elementul faptic),
classification (clasificarea).
Functional Design Folosită pentru manualele ce explică
programele software; Inițial bazată pe
Teoria Actelor de Limbaj (Speech Act
Theory); Restricționarea actelor de
limbaj permise în redactarea de
documentație: per text putem alege doar
din actele de vorbire omologate, iar
adăugarea de reguli de utilizare pentru
fiecare act de vorbire asigură calitatea
și consistența documentației; Unitățile
de bază sunt: element markup >
functional unit (unitate funcțională)
> sequence pattern (secvențe) >
information product (manual).

Tabel 2: Paradigme de scriere/structurare

Pe parcursul carierei sale, un TechWr va folosi una sau mai multe din aceste metodologii. Prin urmare, cunoașterea elementelor de bază ale fiecărei metodologii este recomandată.

3. Documentația trebuie să implementeze un șablon pentru structura internă a conținutului.

Scrierea efectivă de conținut poate fi realizată, teoretic cel puțin, în orice format, dar dacă dorim un conținut uniform, portabil, ușor de distribuit și integrat, actualizat fără efort astronomic, standardizat pentru a putea fi dezvoltat de orice membru al echipei, atunci redactarea într-un editor bazat pe limbaj markup este esențială.

Există o varietate de editoare, câteva dintre cele mai importante fiind: XMetaL, Structured FrameMaker, Oxygen XML Editor, Arbortext, XXE, Syntex Serna. Majoritatea sunt integrate cu DITA OT, ceea ce vă permite să scrieți topicuri în funcție de tip (concept - task - reference - glossary - troubleshooting) unde fiecare tip de topic vine cu un set de elemente și atribute permise și strict reglementate.

O componentă importantă o reprezintă schemele XML ce se pot salva în format DTD (Document Type Definition) sau XSD (XML Schema Definition) (Closs 2016). XML este un limbaj compus dintr-un set de reguli pentru stocarea informației. Avem nevoie de structuri diferite de date pentru fiecare tip de conținut pe care dorim să îl stocăm. Standardul DITA are o schemă XML actualizată de OASIS, perfect integrată de majoritatea editoarelor XML și de majoritatea sistemelor CMS. Pentru editarea în format XML, trebuie să cunoașteți interacțiunea dintre elemente și atributele elementelor. Elementele sunt incluse în taguri și pot conține date, alte elemente, atribute. Atributul este o definiție ce poate fi inclusă într-un element, fiind format din perechi nume-valoare (cheie-valoare).

Editoarele XML permit și stocarea de imagini, diagrame, video în format: TIFF, GIF, JPEG, BMP, SVG, CGM, MP3, JT.

4. Documentația trebuie să reflecte modalitatea în care informația a fost selectată.

În scrierea unui topic trebuie respectate structura XML convenită și o serie de principii ce asigură înțelegerea și asimilarea informației de către cititori (Bellamy et al 2012):

Deși limbajul XML ne facilitează formalizarea uniformă a informației, trebuie reținut că niciun instrument informatic nu ne va învăța cum să selectăm informația, cum să o adaptăm audienței, cum să o ierarhizăm.

Scriem informația cu intenția de a satisface o nevoie a cititorului. Astfel, putem aborda structurarea conținutului și tipul de instrucțiuni pe care le scriem punând accent pe produs, pe funcționalitate sau pe utilizator. Pentru a explica diferența dintre cele trei abordări, ne vom imagina că trebuie să structurăm un manual de utilizare pentru un aparat de fiert la abur (Tabelul 3).

5. Documentația trebuie centralizată și gestionată pe toate nivelele.

Organizarea conținutului trebuie realizată la nivel de topic (unitate de bază), dar și la nivel de map (unitate intermediară formată din mai multe topicuri) sau publicație (unitate maximală). Sistemele CMS (Content Management Systems) (cunoscut și sub numele CCMS - Component-based Content Management System) permit gestionarea completă a conținutului (creare - organizare - distribuire - mentenanță) integrând principiile unei paradigme de scriere (sau a mai multor paradigme), un editor XML și o componentă de publicare (Gollner 2015).

Tabel 3: Variante de structurare

Scrierea structurată într-un sistem CMS asigură:

Tabel 4: Procesele (C)CMS

În ceea ce privește publicarea efectivă de conținut, dacă utilizați un sistem de tip CMS sau CCMS, componenta de publicare în formate multiple e deja integrată în sistem, ceea ce înseamnă că după ce ați scris, organizat și marcat semantic conținutul, alegeți un template și generați publicația în formatul care corespunde acelui template: Windows Help, XHTML, CHM, PDF, Ebook etc. Printre instrumentele DITA utile pentru publicarea documentației menționăm: DITA OT, WebWorks ePublisher, Arbortext tools, RoboHelp.

Există o serie de sisteme alternative de gestionare a conținutului care nu vizează documentația tehnică, dar care pot furniza conținut pentru un sistem CMS:

O alternativă la un sistem CMS clasic poate fi utilizarea unor sisteme Wiki (Weinert & Brueggerman 2012) prin prisma următoarelor beneficii:

Sperăm ca acum Technical Writer-ul și abilitățile sale să vă fie un pic mai familiare decât struțo-cămila sau furculicion-ul, iar data viitoare când întâlniți un asemenea "specimen hibrid" să recunoașteți cel puțin numele jobului său.

Resurse

  1. Achteling, M. - Component-based Content Management Systems, indoition.com,

  2. Bellamy, L.; Carey, M. & Schlotfeldt, J., (2012) - DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA, IBM Press.

  3. Boiko, B., (2005) - Content Management Bible, USA - UK: John Wiley&Sons.

  4. Buehling, B. (2015) - Anatomy of an enterprise structure authoring system, tcworld Conference 2015

  5. Cameron, S., (2011) - Enterprise Content Management: A Business and Technical Guide, BCS.

  6. Closs, S. (2016) - DITA- the Topic-Based XML standard: a quick start, New York - London: Springer.

  7. Gollner, J. (2015) - Practical steps towards integrated content management, tcworld Conference 2015

  8. Kratchy, R. (2017) - Turning legacy documentation into user story based content, tcworld Conference 2017

  9. Weinert, A. & Brueggermann, M. E. (2012) - Wiki as CMS, tcworld magazine, June 2012

  10. **** Standard ISO/IEC 82079-1 (2012) - Preparation of instructions for use*

  11. **** Standard ISO 26511 (2012) - Systems and software engineering. Requirements for managers of user documentation*

  12. DITA

LANSAREA NUMĂRULUI 99

Prezentări articole și Panel:
Agile în izolare

Joi, 24 Septembrie, ora 18:00

Înregistrează-te

Facebook Meetup LinkedIn Youtube

VIDEO: NUMĂRULUI 98

Sponsori

  • comply advantage
  • ntt data
  • Betfair
  • Accenture
  • Siemens
  • Bosch
  • FlowTraders
  • MHP
  • Connatix
  • MetroSystems
  • BoatyardX
  • Colors in projects