Technical Writers @ Lisbon (October-2013)

We had just 11 registrations, including organizers and speakers, but we also expected about 15 students of MOSS (Masters on Open Source Software) to attend. For personal reasons, several past participants informed us that they would not be able to attend.

24 persons attended the meetup, including 14 MOSS students. The whole meetup was spoken in English.

The meetup was scheduled to start at 9h00, but the MOSS students were notably absent. Writers used the time to chat, while MOSS students took a break after starting class at 8h00 on Saturday. Most MOSS students are full-time workers that go an extra mile to attend the Master’s course.

We started the introductions at 10h00. After introducing the upcoming community of technical writers to MOSS, we stressed the importance of the public notes, and distributed ISCTE folders, SISCOG pens, and note pages to participants.

Daniel Bofill

Daniel Bofill

"Our aim is to optimize."

Daniel Bofill was the first speaker. Daniel started with the company presentation, then introduced the User Manuals team, the documentation processes, and outstanding issues. The 0h30 presentation was followed by the same time of follow-up questions, where Daniel clarified many issues. Daniel amazed the audience with his knowledge of railroad scheduling.

The SISCOG documentation team combines a more technical writer (full-time) with a strong language specialist (part-time). The SISCOG documentation is strongly influenced by having a small number of clients, each with a combination of optional modules and customized development. Clients also demand specific terminology, leading Daniel to contemplate the creation of documentation variants for company dialects, much to the amazement of Frances Gordon.

By 11h00, the coffee break provided the opportunity to engage in lively discussion around the famous standup tables of the nearby ISCTE cafeteria.

Frances Gordon

Frances Gordon

“At the end of the day, it is about understanding the user.”

Frances Gordon resumed the meetup at 11h20. She presented the governance of words as part of an overall content strategy. She feels that writers have always done content strategy, and noticed how the SISCOG presentation illustrates the different parts of the (genial) Brain Traffic diagram.

Frances explained how English acquired doublets and triplets of words with the same meaning, as the British Islands were invaded time after time, with each new invader adding words to the language.

Frances explained the role of style sheets in governing words, especially when many writers must write consistently, or when words must express the brand. Frances showed her preferred format for Excel-based style sheets, then noted typical flaws that she met in customer engagements. Also, style sheets are fun to use in an iPad.

At the very extreme, the American military establishment created Simplified Technical English, which limits both words and grammar.

Frances presented the case for governing words brilliantly, leading to questions about automated grammar checks, assisted writing, and automatic text generation.

Rui Diogo Serra

Rui Diogo Serra

“SMEs know how to write them.”

Rui Serra faced the difficult task of starting at noon, at a time when people where starting to contemplate lunch. Rui hurried through his carefully structured presentation, presenting AnubisNetworks as a company where engineers and system architects write to customers with similar expertise. The AnubisNetworks documentation comprises a sophisticated set of documents, coordinated and revised by documentation managers.

Rui works mostly as a product manager, and therefore he has the power to demand experts to write the documentation, although the quality may vary. Mature products with a slow rate of change enable Rui to review most documents during “test months”.

Over time, AnubisNetworks tried and abandoned several tools. The documentation is currently produced with a mix of wikis (including customer wikis), common word processors, LaTeX, Camstasia, and several common graphical editors. Box provides versioning and editing control.

Rui concluded his presentation with an assessment of the AnubisNetworks documentation process, noting positive outcomes, dangers, and future wishes. A final slide summarized the questions facing Rui at AnubisNetworks.

Rui offered a strong presentation with many insights, rushed by lunch, but still with time for comments and questions.

“...the passion that every speaker has for their work...” — Anonymous #2

To wrap-up the event, the organizers thanked ISCTE for hosting the meetup (in a superb room), and MOSS students for their participation. We also noted that EuroSIGDOC is our academic sponsor, while APCOMTEC is our Portuguese home.

8 persons had lunch together at a nearby restaurant featuring a quality buffet. For practical reasons, the MOSS students had lunch at a different restaurant, filled to capacity.

What do the organizers say?

Joaquim Baptista and Carlos J. Costa The laurels of this second “formal” meetup must go to the speakers, for the essence of these meetups is the generosity of the speakers in sharing their experience. After each presentation, the dawning community thrives on the inquiring questions and straight answers, and then again in the coffee breaks and informal meetings.

Several interested persons wrote to note that they would not be able to attend the meetup. Although the meetup was still well attended, the organizers wonder if the short lead time limited attendance.

Due to intellectual property restrictions of her company, Frances Gordon could not share her presentation slides for this report. However, Frances is also the first consultant that agreed to speak to the group. This issue will probably return in the future.

The next tentative objective is to schedule an informal meetup well before Christmas, and a formal meetup in February 2014.

Institutional support

Technical Writers @ Lisbon has the support of:


Technical Writers @ Lisbon: The 2nd Report
Report of the meetup, including the slides of two presentations. 27 pages.