Ca o paranteză, cele două evenimente legate de technical writing la care am fost eu până acum (Graphic Design and Tools for Technical Writers și Single Source Publishing Using DITA and DITA Tools) au fost interesante pentru mine ca ocazii de networking, dar mai puțin din punctul de vedere al informațiilor pe care le-am obținut – partea de grafică nu e prea importantă în munca mea de acum, iar introducerea în DITA a fost la nivel de începători absoluți și a constat în cea mai mare parte în lucruri pe care le știam deja. La Tekom Roadshow nu am mers pentru că părea axat pe DITA, iar șansele ca eu să mă ocup cu așa ceva în viitorul apropiat erau (și sunt) minime, deci nu se justifica investiția. (…Serios, toată Europa lucrează în DITA și noi suntem singurii ciudați care au ales RoboHelp?!)

Închizând paranteza, conferința bulgarilor este mult mai complexă (chiar merită cei 70 euro), iar subiectele de discuție par mai variate. Cele care m-ar interesa pe mine în mod deosebit sunt:

• George Bina, Syncro Soft (Craiova) – am folosit pentru câteva luni oXygen, softul craiovenilor, și am rămas extrem de impresionată de asistența extraordinară pe care o oferă pe forum (chiar și nenumăraților useri – ca mine – care de fapt se pierdeau în subtilitățile DocBook-ului, nu în oXygen!). Prezentarea se numește Single-Source Publishing Using Multiple Formats, dar sincer m-aș duce indiferent de subiect. Acum vreo 2 ani angajau un technical writer și atunci chiar mi-a părut rău că nu locuiesc in Craiova.
• Sissi Closs (profesoară la Universitatea de Științe Aplicate din Karlsruhe), cu prezentarea The tekom Profiling Tool: How to Define Job Roles and Competence Profiles for Technical Writers, care sună a ceva care mi-ar fi foarte de ajutor la muncă, unde sunt implicată și în procesul de recrutare, și în training.
• Vanya Kiritzova și Margarita Staneva (VMWare Bulgaria), despre o carieră în technical writing – Plot Your Technical Writing Career Like a Pro. Eu personal sunt mulțumită de traiectoria mea profesională de până acum, dar întotdeauna e util să auzi idei noi.
• Axel Luther (SAP Germania), despre documentație video (Product and Instructional Videos – A Perfect Supplement to Classical Product Documentation)… pentru că eu urăsc să mă uit la videoclipuri și nu înțeleg de ce ar vrea cineva să se tortureze așa (Și pentru că accept faptul că documentația mea se adresează unor clienți care probabil nu gândesc ca mine, deci va trebui să învăț mai mult și despre partea video.)
• Dimiter Simov și Ekaterina Mitova (SAP Bulgaria), cu prezentarea Are You Ready for User Feedback?, o întrebare care se aude din ce în ce mai des în ședințele departamentului meu…
• Lukasz Gornicki (SAP Polonia) – Documenting REST API (workshop), pentru că se pare că documentația de API e viitorul și eu sunt puțin în urmă
• Yordan Ugrinov (VMWare Bulgaria), un workshop cu titlul Web Analytics for Documentation: Use Cases, Best Practices, and Caveats. Încă o dată subiectul potrivit la momentul potrivit, pentru că recent am implementat Google Analytics pentru produsul pe care lucrez și… recunosc că nu prea știu la ce ar trebui să mă uit.

(Dacă lista asta pare lungă, mergeți pe site-ul ETC – chiar am făcut o selecție, programul complet este mult mai variat.)

Cu puțin noroc, dacă se aliniază planetele, release-urile și zilele de concediu, ne auzim cu un aproape-live-blogging din Sofia peste o lună și ceva!

This method can be used for any of the settings visible in the GUI (and even for some that are not visible). In the following example I will assume that I have several modules, with at least one SSL defined for each, and that I’m trying to deactivate Mark of the Web for all of them.

In short, we will compare the XML with Mark of the Web turned on and the XML with Mark of the Web turned off and we will then use search & replace to change the option in all modules.

1. From the source folder of one of the RoboHelp projects, open the file <SSL_name>.ssl in a text editor (I use Notepad++). You will get something like this:
   
2. Open an empty document or tab and copy the entire contents of the file in it. You need to do this because the next steps will change the initial XML and you need both versions for the comparison.
3. In RoboHelp, open the respective project and double-click the same SSL you used at step 1.
   
4. Change the options as needed – in my case, I cleared Mark of the Web. (You can change multiple options at the same time, but you risk getting confused, so it’s safest to take them one by one.)
5. Save the SSL. The XML at step 1 is immediately modified and you now have two versions of the same file – a before and an after.
6. Identify the modified row. In Notepad++, I use a plugin called Compare. If I select Plugins > Compare > Compare, Notepad++ compares the last two files opened and highlights the changes.
   Be careful though, because (for reasons that escape me) some rows are rearranged the moment the SSL is saved, so you will see a lot of apparent changes that are actually irrelevant to what we are trying to do. Either way, the files are not big and it’s fairly easy to find the row with the modified value by simply scrolling and eyeballing it.
   
   As you can see, <element name=”m_bSupportMOTW” value=”1″ /> in the initial file means that Mark of the Web is on, while <element name=”m_bSupportMOTW” value=”o” /> means that it’s off.
7. Replace the old row with the new one in all relevant SSLs. In Notepad++, that can look like this:
   
   …which translates as :
   • Replace <element name=”m_bSupportMOTW” value=”1″ /> with <element name=”m_bSupportMOTW” value=”o” /> …
   • …in all files called WebHelp.ssl…
   • …located in D:\technical_documentation or one of its subfolders.

Tada! It all took 5 minutes in total, and you can continue by using a script to regenerate the entire help with the new option.

Metoda de mai jos se poate aplica pentru orice setare din GUI (și chiar pentru unele care nu sunt vizibile). În exemplul următor, voi presupune că am mai multe module, cu cel puțin un SSL deja definit în fiecare, și încerc să dezactivez Mark of the Web în toate.

Pe scurt, o să compar versiunea de XML cu Mark of the Web activat cu versiunea de XML cu Mark of the Web dezactivat și apoi o să rulez un search & replace ca să fac modificarea în toate modulele.

1. Din folderul-sursă al unuia dintre proiectele RoboHelp, deschide fișierul <nume_SSL>.ssl într-un editor text (eu folosesc Notepad++). O să obții ceva de genul ăsta:
   
2. Deschide un document/tab gol și copiază tot conținutul fișierului în el. Faci asta pentru că pașii următori vor modifica XML-ul inițial, și îți trebuie ambele variante ca să putem face comparația.
3. În RoboHelp, deschide proiectul respectiv și fă dublu-click pe același SSL pe care l-ai deschis la pasul 1.
   
4. Modifică opțiunile după cum vrei – în cazul meu, am debifat Mark of the Web. (Poți să modifici și mai multe opțiuni în același timp, dar riști să te încurci, deci e mai sigur să le iei una câte una.)
5. Salvează SSL-ul. XML-ul de la pasul 1 se modifică imediat și acum ai două variante ale aceluiași fișier – before și after.
6. Identifică rândul care s-a modificat. În Notepad++ eu folosesc un plugin numit Compare. Dacă selectez Plugins > Compare > Compare, Notepad++ compară ultimele două fișiere deschise și subliniază modificările.
   Atenție totuși, pentru că (din motive care îmi scapă) unele rânduri sunt rearanjate în momentul în care se salvează SSL-ul, așa că vor apărea multe modificări care de fapt sunt complet irelevante pentru ce încercăm noi să facem. În orice caz, fișierele nu sunt prea mari și rândul cu valoarea schimbată e ușor de găsit ochiometric, pur și simplu scrollând.
   
   După cum se vede, <element name=”m_bSupportMOTW” value=”1″ /> din fișierul inițial înseamnă că Mark of the Web e activat, iar <element name=”m_bSupportMOTW” value=”o” /> înseamnă că nu.
7. Înlocuiește rândul vechi cu rândul nou în toate SSL-urile care te interesează. În Notepad++, asta poate să arate cam așa:
   
   …ceea ce se traduce prin:
   • Înlocuiește <element name=”m_bSupportMOTW” value=”1″ /> cu <element name=”m_bSupportMOTW” value=”o” /> …
   • …în toate fișierele care se numesc WebHelp.ssl…
   • …care se găsesc in D:\technical_documentation sau un subfolder al lui.

Tada! Totul a durat 5 minute în total, și mai departe poți folosi un script ca să îți regenerezi rapid întregul help cu noua opțiune.

We have a rather large online help system – about 6000 topics in 40 separate modules – generated using RoboHelp, in WebHelp format, and delivered both on a website and as an MSI.

The problem

The search takes too much – 25-30 seconds when run on the server. If the help is installed locally, the search is much faster, but most of the clients use the website.

The reasons

After a few rounds of testing and a lot of googling, I reached the conclusion that the biggest culprit is the RoboHelp search (but some structural improvements in the content wouldn’t hurt either).

The solutions

Because content changes are more difficult to implement in the short term, I started testing various options of optimizing the search.

Attempt no. 1: No PDF and Word searches

Because each module has a PDF version that contains the same stuff as the online help, I first excluded all such documents from the search.

Result: no performance improvement. (But I still think it was a good idea, because we are avoiding duplicate content in the searches.

Attempt no. 2: Searching on all terms by default

Because RoboHelp 2015 has a new option for this, I enabled “AND” search by default in all modules.

Result: no performance improvement (but I wasn’t expecting one anyway). I don’t know why we had to wait so many years for such an obvious setting, but better late than never, I guess. Now the search should be working like everybody probably imagined it was working already.

Attempt no. 3: Optimizing for LAN

Yeah, it’s not really intuitive, after all we are publishing to the internet. Well, apparently the option kept its name from the dial-up days…

Some background first: to enable the search functionality, RoboHelp generates some files (with names like package_n_xml.js) in the folder whxdata. Every search loads every one of these files… so the more files, the more requests to the server and the slower everything runs. Here is where our option comes in: when the output is optimized for internet, RoboHelp generates more, smaller package files (because this was more efficient in the old days, I guess); when the output is optimized for a local network, RoboHelp generates fewer, larger package files.

So… I started comparing, after I generated the entire help system with each of the options:

• A search in Windows for the package*.js string, in the entire help system: the LAN-optimized version has 6 times fewer package files.
  
• A comparison at the merged project level: the LAN-optimized version has 6 times fewer files in the whxdata folder and there are 2 package files instead of 41.
  
• A comparison in Chrome Developer Tools: in the LAN-optimized version there are 190 requests, compared to 275 in the internet-optimized version.
  

The questions (for which I don’t yet have clear answers):

• Why aren’t there 6 times fewer requests? After a quick analysis in Developer Tools, I gathered that, for each module, at least 5 requests are sent: packageindex_xml.js, package_0_xml.js, synonym_xml.js, topictableindex_xml.js and topictable_0_xml.js, so there comes a point when the only way of improving the performance is reducing the total number of modules.
• Why is 5 times more data being downloaded when the content is optimized for LAN, especially considering that fewer requests are sent?

Result: an almost insignifiant performance improvement, far less than I was hoping for.

The final conclusion

After a month of testing, I know way more about the RoboHelp search… and I managed to improve the search by whooping 5 seconds (on days with a good connection).

What next?

Two things:

• Consolidating modules – fewer modules, fewer files, fewer requests, faster search.
• Implementing an external search – Google custom search or Zoom Search.

Avem un sistem de online help destul de mare – aproximativ 6000 de topicuri în 40 de module separate – generat din RoboHelp, în format WebHelp, și livrat atât pe un site, cât și ca MSI.

Problema

Searchul durează prea mult – 25-30 secunde de pe server. Dacă helpul e instalat local, searchul e mult mai rapid, dar majoritatea clienților folosesc site-ul.

Motivele

După câteva runde de teste și multe căutări pe Google, am ajuns la concluzia că cea mai mare parte a vinei o poartă searchul din RoboHelp (dar niște îmbunătățiri la nivel de structură a helpului nu ar strica nici ele).

Soluțiile

Cum modificările la nivel de conținut al helpului sunt mai greu de pus in practică pe termen scurt, am început să testez diverse opțiuni de a face searchul mai eficient.

Încercarea 1: Fără căutări in PDF si Word.

Pentru că fiecare modul are o versiune PDF care conține fix același lucru ca online help-ul, mai întâi am exclus toate documentele de genul asta din căutări.

Rezultat: nici o îmbunătățire de performanță. (Dar cred ca oricum a fost o idee bună, pentru că măcar nu va mai apărea conținut duplicat în căutări.)

Încercarea 2: Căutare implicită cu toți termenii

Pentru că in RoboHelp 2015 există o opțiune nouă în acest sens, am setat ca toate modulele să aibă căutarea cu „AND” activată by default.

Rezultat: nici o îmbunătățire de performanță (dar nici nu mă așteptam). Nu știu de ce a trebuit să așteptăm atâția ani pentru o setare la mintea cocoșului, dar bine că a apărut. Acum searchul ar trebui să funcționeze așa cum probabil își imagina toată lumea ca merge deja.

Încercarea 3: Optimizare pentru LAN

Da, nu e prea intuitiv, totuși noi publicăm pe internet. Well, se pare că opțiunea și-a păstrat denumirea din negurile dial-up-ului.

Niște background întâi: pentru căutare, RoboHelp generează niște fișiere (cu nume de forma package_n_xml.js) în folderul whxdata. La fiecare search e încărcat fiecare fișier de genul ăsta… și cu cât mai multe fișiere, cu atât mai multe requesturi către server și cu atât mai lent va merge totul. Aici intervine opțiunea noastră: când outputul este optimizat pentru internet, sunt generate multe fișiere package mici (pentru că, pe vremuri, asta ar fi fost mai eficient, bănuiesc); când outputul este optimizat pentru o rețea locală, sunt generate mai puține fișiere package mai mari.

Așa că… am început să fac comparații, după ce am generat întreg sistemul de help cu fiecare dintre opțiuni:.

• O căutare in Windows pe stringul package*.js, în tot sistemul de help: varianta optimizată pentru LAN are de 6 ori mai puține fișiere package.
  
• O comparație la nivel de merged project: varianta optimizată pentru LAN are de 6 ori mai puține fișiere in folderul whxdata și în loc de 41 de package-uri am obținut 2.
  
• O comparație în Chrome Developer Tools: în varianta optimizată pentru LAN se trimit 190 de requesturi, față de 275 în varianta optimizată pentru internet.
  

Întrebările (la care nu am încă răspunsuri clare):

• De ce nu se trimit de 6 ori mai puține requesturi? După o analiză sumară în Developer Tools, deduc că pentru fiecare modul par să se trimită minim 5 requesturi: packageindex_xml.js, package_0_xml.js, synonym_xml.js, topictableindex_xml.js și topictable_0_xml.js, deci de la un punct încolo singura modalitate de îmbunătățire a performanței e scăderea numărului total de module.
• De ce în cazul optimizat pentru LAN se descarcă de 5 ori mai multe date decât în cealaltă variantă, mai ales având în vedere că se fac mai puține requesturi?

Rezultat: o îmbunătățire aproape insesizabilă de performanță, mult mai puțin decât speram.

Concluzia finală

După o lună de teste, știu mult mai multe despre searchul RoboHelpului… și am reușit să optimizez căutarea cu 5 secunde (în zilele în care zbârnâie internetul).

Ce urmează?

Două chestii:

• Consolidare de module – mai puține module, mai puține fișiere, mai puține requesturi, search mai rapid.
• Implementarea unui search extern – Google custom search sau Zoom Search.

• Industria este foarte mică – la ultima mea numărătoare, pe LinkedIn erau cam 100 de technical writeri în vreo 50 companii și, chiar luându-i în considerare pe care care nu au profil, tot nu se ajunge la un numar prea mare.
• In România nu există nici un curs de technical writing în învățământul superior*, iar singura diplomă oarecum relevantă de care știu eu este cea de master în Teoria si Practica Editării de la Facultatea de Litere din București.
  (* În afara sistemului de învățământ, există GuideTC, o firma care ofera traininguri în domeniu, printre care și unul de “bazele technical writingului”. Nu am interacționat cu ei, deci nu știu nimic în afară de faptul că există.)

Pe scurt, multe companii nu își prea permit să aibă pretenții și, daca ai experiență transferabilă, ai mari șanse să convingi pe cineva că esti candidatul potrivit.

Experiența relevantă

Din ce am văzut eu (pe LinkedIn si la fostii sau actualii mei colegi), majoritatea technical writerilor care lucrează în momentul de față in România au background în:

• Traduceri
• Jurnalism
• Content writing
• Redactare de carte
• Învățământ
• Training
• Domeniul de activitate al firmei angajatoare (adică background în finanțe pentru firmele care fac software financiar, absolvenți de Politehnică pentru firmele care au nevoie de documentație de API, etc).

Limba engleză

În majoritatea cazurilor, o limbă straină (în general engleza) este o cerință obligatorie – de câțiva ani de când urmăresc anunțurile de angajare am văzut un singur job care presupunea documentație scrisă în română. Și când zic “cerință obligatorie” mă refer la limba vorbită la perfecție, aproape de nivelul nativ – clienții care îți citesc documentația nu trebuie sa își dea seama ca a fost scrisă în România (sau în India, sau în Ungaria, sau…), trebuie să se poată concentra asupra informațiilor din ea fără să se blocheze în greșeli gramaticale sau întorsături de frază ciudate. (Da, da, “toți românii știu engleză” – așa aveam și eu impresia acum câțiva ani. Între timp, mi-am dat seama că foarte mulți candidați își supraestimează abilitățile…)

Explicația pentru părinții mei: Știi că atunci când primești un mixer nou ai instrucțiuni de folosire? Ei, cam aia fac eu, numai că nu le traduc prin Google Translate din chineză.

Explicația pentru prietenii mei: Știi helpul de la Word? Ei, cam aia fac eu, dar pentru alt soft.

Explicația pentru colegii mei: Știi specificațiile pe care le scrii tu? Eu le traduc în ceva ce poate fi înțeles de client.

Explicația pentru candidații pe care îi intervievez: Treaba noastră e să le explicăm utilizatorilor ce face aplicația noastră – ceea ce poate include instrucțiuni de instalare, configurare, administrare și/sau utilizare propriu-zisă.

Și acum pe bune… ce faci în fiecare zi?

În ciuda numelui, partea de scris efectiv este un procent mai mic decât ați crede… foarte pe scurt, pașii sunt cam așa:

1. Cercetare. Aici aduni informații din toate sursele posibile (documente pierdute pe intranet, specificații pe wiki-ul intern, mailuri forwardate, ideea genială a programatorului de la etajul 2, și asa mai departe).
2. Structurare. Aici pui cap la cap informațiile de la pasul 1, într-o structură care are sens.
3. Editare. Aici citești și reformulezi și citesti iar și reformulezi iar, până când totul e fix atât de concis și de clar cât trebuie.
4. Publicare. Aici opera ta ajunge la clienti!

Bonusuri:

• Testezi dacă aplicația chiar funcționează cum scrie in specuri.
• Loghezi buguri când descoperi că nu.
• Te enervezi dacă programatorii au folosit un termen greșit în interfață
• Te bucuri dacă descoperi că au niște standarde pe care le urmează…
• …sau scrii chiar tu standardele.
• Înveți să traduci din romgleză, frangleză si chingleză într-o engleză literară (dar nici prea literară, nu suntem Shakespeare).
• Te bucuri când în sfârsit o să reușești să reformulezi ceva în cel bun mod.
• Te enervezi când clientul îți loghează un bug despre o funcționalitate care nici măcar nu era menționată in specificații.