18 June 2016, 10th formal, Atelier Concorde

Come Saturday morning, it was surprisingly hard to park next to Atelier Concorde, quite unlike the time that I had visited the before. The meeting was in the project room of Atelier Concorde, fresh out of an exhibition. Three of the walls were covered with drawings. The drawings created a cheerful mood, quite different from the feeling of clean white room in my previous visit.

Thirteen people attended the meeting, including eight people that stayed for lunch. Mariana doubled as the event photographer, which means that I got photographed by a real camera while speaking.

Joaquim Baptista

Most people arrived after 9h, and I started my presentation at 9h25 with eleven people in the room. While the presentation was aimed at people new to the group, most persons had not seen the presentation at CAPSI, the Portuguese conference on information systems.

20160618-094400My presentation had three parts. First I showed how a startup developing a product will eventually face growing issues in effectively capturing and using its own knowledge. These issues will initially be tacked by one of the existing departments of the company.

Then, I explained the skills that technical writers bring into a company, starting with the ability to gather knowledge consistently, and then transferring that knowledge into different artifacts.

Finally, I presented the organizations that advocate technical writing in Portugal, namely APCOMTEC, EuroSIGDOC, and our own Technical Writers @ Lisbon.

Daniel Bofill

SISCOG imported its Word content into RoboHelp shortly before Daniel was hired. I knew that Daniel had outgrown RoboHelp, so I was surprised as Daniel described its major features.

He started with master pages, which provide structure to topics, but not to the body of topics. They seem to just take care of the boilerplate. On the other hand, after you write topics you are limited in how you can change its master page.

20160618-102743On larger topics, SISCOG found that users appreciate mini table of contents. RoboHelp is strong at editing CSS, hiding the complexity behind dialogs and combo-boxes.

Conditional build tags can hide topics or parts of topics. However, sometimes hidden topics are included in CHM help files and can be found through search. The editor paints conditional areas, but fails when several tags apply to the same text.

User-defined variables are used only to include versioning information in the cover page, and to have the name of the application. However, RoboHelp has the interesting concept of sets of related variables, where a set of variables changes together.

Singe-source layouts generate several different outputs from the same source, but a better name would be repurposing. You can buy RoboHelp plugins to generate outputs in more formats.

Daniel must have a RoboHelp project for each application, instead of a single master repository to generate several helps from subsets of topics. SISCOG is working on compensating this by simulating a repository that uses scripts whereby topics can be shared among projects. He has a different layout for each customer, with customized conditions and CSS.

During questions and answers, Daniel acknowledged that SISCOG has RoboHelp 8, while the current version is 15. Still, he believes that RoboHelp is way behind Madcap Flare. Daniel longs for the flexibility of DITA. For example, SISCOG sells 136 plugins that customers can buy individually to add functionality.

Intermission

We had coffee and cookies, upstairs by the entrance, offered by Aline Lopes. Which means that we had all the intermission time to talk, without the logistic issues of moving to a coffee house and back.

Eunice Gonçalves Duarte

20160618-112015Eunice had set up a table in the corner of the project room, with pieces of cork and a few toys. With the room lights dimmed, two small lamps drew the attention onto the table.

Eunice explained the process: toys, props, a portable web camera that can focus really close, and a laptop to record everything. After talking about her experiences, she just invited everyone to play while she blew soap bubbles into the stage.

After a few moments of hesitation, magic happened. People started moving the toys, and then improvised a story, while someone else moved the camera around.

The footage captured will require extensive processing before it can be released.

Paulo Ribeiro

Vision-Box was in a phase of vigorous growth when Paulo was hired, together with Rui and Helena. Bruno joined them later to extract 2D snapshots from 3D CAD models.

They quickly figured out that they needed to move beyond Word. Lacking the time to explore alternatives, Paulo decided to improve on what was he had used at Altitude Software. He adopted DITA, the DITA Open Toolkit, and Apache FOP.

He fought against XSLT and XSL-FO to get good-looking PDFs, a process that took two or three months. He recommended the tutorial book DITA for Print by Leigh W. White.

As XML editor, they initially used the unsupported freeware Syntext Serna. Later, they settled with oXygen XML Author, which Paulo recommends.

20160618-122548Paulo considered using a CCMS (component content management system), but ultimately felt that these fell into two camps: either limited and cheap, or complete and way too expensive. Paulo felt that a CCMS would not be a good fit to a team of four, and that he would be trapped inside the tool. Instead, the temporary Subversion repository that they set up while choosing a CCMS became the definitive solution.

At the end of 2015, they had 150 ditamaps, 2500 topics, 380k words, and 5000 images. Most topics are composed of images with just a little text.

Three months after they started, they were already lost in their own directory structure. They regained balance by focusing reuse on the more stable topics. Topics that frequently changed in each project were just copied and modified. Most manuals documented unique combinations of existing hardware designs, requiring unique drawings while sharing a common structure and some text. However, they often had no access to the actual hardware.

Over time they invested in automation, typically using Python. They started by automating the process of watermarking images, saving the Human designer some serious time. They also created scripts to validate DITA sources, alleviating the need for a CCMS.

Paulo and Helena feel that success happened because the team was small and cohesive, and Vision-Box gave them the time to experiment. They took about an year to put all the pieces together.

Helena had the most doubts at the beginning but, in her own words, became fan #1. In Paulo’s words, the major lesson is that good enough is best.

João Lourenço

In his own words, João “earns his living doing this”, meaning presenting. And he proved his point with a mature presentation, which leads the audience through a large number of carefully constructed slides that provoke the audience and then the ensuing psychological wave.

He started with a challenge: why would Word not be good enough for a writing a thesis? He immediately presented the analogy of buying a car to conclude that “it depends”: there is no perfect car for every driving situation, and there is no perfect tool for every writing need.

Then he illustrated some advantages of LaTeX over word, namely spacing (between letters and between words) and justification by paragraph.

20160618-130527João used a graph to show that Word excels for simple documents, while LaTeX requires a larger investment up-front that pays off as documents grow larger and more complex.

So, should a thesis be considered a simple document or a large and complex document? Thesis are complex documents because they have chapters, sections, appendixes, annexes, figures, tables, lists of the above, cross-references, bibliography citations, and glossary… all regulated by strict University publishing rules governing fonts, margins, line spacing, covers, and spine… and further complicated by the need to establish working workflows with advisors, where the thesis gets reviewed and revised.

João told one episode: three days before a deadline, one of his students using Word got into a situation where he could neither print nor save his theses. It took a divide and conquer approach, deleting parts of the thesis in sequence, to identify the culprit, which was a specific cross-reference. The student had stumbled into a bug in Word.

This episode reflects my own experience. Every single student that I ever met that used Word to write his thesis (and sometimes paper or major work) had a “war story” to tell, usually weeks or days before the work was due. I knew a few students that just retyped the entire thesis from the last printout.

João has always been an evangelist for LaTeX, suggesting his MSc and PhD students to use it instead of desktop publishing alternatives. After this episode, however, he started to force students to use LaTeX. So far he had 30 MSc and PhD students.

How can students learn LaTeX? Google was a game changer, and João enumerated several sites that help with parts of LaTeX.

For me, it was quite significant that he did not mention TUG, the TeX Users Group. This group of experts gathered initially around the paper journal TUGboat, then embraced the Internet to create the Comprehensive TeX Archive Network (CTAN, following the footsteps of Perl’s CPAN). TUGboat still exists; its articles (often 2–3 pages long) can be esoteric, but also enlightening and inspiring. Then again, the average reader of TUGboat would probably be considered an expert by most standards.

20160618-132845Finally, João introduced his own LaTeX template, named “unlthesis”. Besides typesetting pages according to official requirements, the LaTeX template also creates the front matter and back matter pages, and even the spine of the final book.

Over time, communities of users has formed around a Google group (for more advanced users) and a Facebook group (for beginners, including beginners to LaTeX itself). João can no longer offer direct support by email, or he would do little else.

Why did João start the template? After forcing his students to use LaTeX, he felt obliged to help them. He ended up coding a template that, in his own words, does everything except writing the thesis. This “maximal” approach contrasts with most University LaTeX thesis, which offer a “minimalist” starting point that still requires the student to encode in his document many formatting requirements.

João believes that this “maximal” approach is the reason for the wider use of his LaTeX template. The usage went beyond Computer Science students to other departments at FCT, then to other Schools at UNL. He knows that students from random foreign Universities have adopted and customized his LaTeX template.

How hard was it? João struggled to learn plain TeX. After having read the TeXbook myself and learning about the mind-bending macro \expandafter, I definitely sympathize with him. He also struggled to incorporate user requests, and felt the need to refactor code and to create his own “domain language” to define covers and front matter.

The template is currently maintained by two developers, with help from a few more contributors. He knows for certain that the template is used for a few hundred users per year at FCT/UNL, plus quite a few scattered around. He says that some users are happy…

He delivers LaTeX training at the UNL Doctoral School, where he meets students from all backgrounds. While some science students such as doctors will be hit or miss, Linguists just love LaTeX. I find it hardly surprising that Linguists would appreciate books and good typesetting.

2016-06-twl-report-iconAt the Doctoral School, the real issue against LaTeX adoption have been the advisors, which are used to a Word-based workflow. João argues that students should author every single word in their thesis, lest they be caught off-guard while defending the thesis. Therefore, advisors should comment the thesis, but not write into it.

João has found the iPad to be the ultimate thesis revision tool. He takes draft PDF files from students, then used a virtual pen to scratch and hand-write extensively. However, the student must incorporate comments himself, ensuring sound authorship of the thesis.

At least two of the attendees pledged to try LaTeX for their thesis or papers.

This was our 10th formal meeting, and João was the 30th speaker. We could not have picked a better speaker to this auspicious moment.

Lunch

We finished close to 14h, and proceeded to stow that chairs and tables that we had used. But we did so while still talking, so Eunice had to kick us out of the basement.

Eight of us proceeded to lunch, which we had in a “tasca” found after a steep ramp and two corners. There was wine and beer to go along with bread, cheese, roast suckling pig, and other delicacies. The conversation considered the merits of an “autothesis” class, which will be left as an exercise for the reader.

We said our good-byes at 16h30, about 8h after the first of us arrived on site.


(The two invitations for this event follow.)

First invitation (6-Jun)

Greetings to all technical writers, and to everyone interested in technical communication!

In informal meetings, we have talked for some time about exploring the diversity of tools used in the community. We are excited to announce that our 10th formal meeting will cover three very different kinds of tools, by people that actually use them.

  • Saturday, June 18th, between 9h00 and 13h00 (be sharp).
  • Atelier Concorde, www.atelierconcorde.org.
  • Rua Leite Vasconcelos 43A, 1170-198 Lisboa.

Tools will shape you writing in surprisingly deep ways. Most companies just write with what “came with the box”, usually Word. However, every tool makes some things easy, some hard, and some impossible.

The perfect tool for some situation may be the impossible tool for another situation. Writers often praise and curse their tools, often in the same sentence, always with passion. Not surprisingly, innovative companies will often find themselves off the beaten path.

Joaquim Baptista, Technical Writing for Portuguese Product Companies
The economic crisis in Portugal is stimulating the creation of product companies that sell worldwide. Over time, these companies accumulate a capital of technical knowledge, domain knowledge, and user knowledge. Joaquim will show how technical writing helps product companies manage and engineer their knowledge.

Daniel Bofill, RoboHelp: 5 Essential Features to Build User Manuals
SISCOG’s clients require user manuals that can help them keep up with the complexity and high level of customization of their software. Daniel will look into some of the features RoboHelp provides that aid authors be more efficient such as user defined variables, conditional build tags, CSS editing, single source layouts, and more.

Paulo Ribeiro, Do-it-yourself Technical Writing
Paulo will report on the organic introduction of tools and processes into a company, as the needs of the company developed. He mostly used open source technologies that incurred small or no costs to the company.

João Lourenço, LaTeX for MSc and PhD thesis
João will argue that students should write their thesis using LaTeX instead of a common word processor such as Word. João will introduce his LaTeX template to write MSc and PhD thesis, so that the output follows the official guidelines automatically. João will also talk about his experience in creating the template, and curating its community of users.

The participation is free, but refreshments will be on your on. Some of us will probably stay for lunch afterwards, and you are welcome to join us.

Please extend this invitation to friends and other interested parties. More interesting participants will improve the learning experience for everyone. Please publicize the EuroSIGDOC site, the Google group, and the Meetup group!

Special thanks to Eunice Gonçalves Duarte, our new sponsor, for graciously offering the room and the projector. And thanks to the long-time sponsors APCOMTEC (marketing) and EuroSIGDOC (site).

— Alexandra Albuquerque, APCOMTEC, info@apcomtec.org
— Carlos Costa, EuroSIGDOC chair, carlos.costa@acm.org
— Joaquim Baptista, EuroSIGDOC vice-chair, px@acm.org

PS: By the end of my engineering course, I was known as “The Parker Man”.

PPS: Eunice is also a performer, and she was asked to perform at the meeting. Stay tuned.

Second invitation (16-Jun)

This is a gentle reminder for our meeting next Saturday, starting at 9h.

This next meeting will feature three tales from the trenches, by people that lead the evolution of tools and processes in their daily jobs.

During the coffee break, Eunice Gonçalves Duarte (aka “semáforo”), will also demonstrate and comment on her performance techniques. Eunice has graciously offered the room for the meeting.

I look forward to meet you on Saturday,

— Joaquim Baptista

PS: Did the Greeks start technical writing, like everything else, 2000 years ago?

Attachments

The 10th Report — 41-page report of the meeting, including the slides of the presentations.