Category: TWL

We had planned to meet half-an-hour before the event, to make sure that everything was set up just right. However, the keys to start the Zoom meeting were held hostage by a ROTIP event (random obnoxious traffic in Porto) of force 6, which expanded a 15-minute short trip into a 90-minute exasperation. Without any real means to communicate the delay, we just had to push on and pray for the patience of the attendees. We can’t quite know if anyone gave up before the wait was over.

Joaquim Baptista

We had 23 persons when we finally started the meeting at 18h15. I took some minutes to present the organizers and sponsors:

• Since 2013, Technical Writers @ Lisbon organized 15 formal events (together with EuroSIGDOC and APCOMTEC) with 40 presentations, attended by 346 persons.
• Since 2009, EuroSIGDOC organized 7 academic conferences and at least one seminar.
• Since 2006, APCOMTEC has organized events, workshops, a Summer School, and launched a Postgraduate Diploma with ISCAP.
• Since 1886, ISCAP has been teaching in the Porto region and now virtually.

Paulo Tavares

Paulo started his presentation at 18h23. He pledged to avoid random English to the point of proposing a word bingo with candidate word offenders.

Paulo was Outsystems employee #27, then left for Google and returned years later to Outsystems with an MBA. He noticed the lack of articulation between:

• Product, which created documentation.
• Training, which created online and classroom courses.
• Professional Services, which created a knowledge base.

He proposed to unify the three efforts under the umbrella of Technical Knowledge, with the purpose to satisfy the knowledge needs of users using whatever form made sense. As a consequence of this change in perspective, the unified team:

1. Focused on covering the needs of users, instead of just documenting product features.
2. Became responsible for defining the best way to satisfy user needs.
3. Started to manage the overall knowledge set as a product.
4. Broke team processes into capabilities, to figure out which parts of the processes could be done by subject matter experts or freelancers.
5. Scaled work by enabling the contribution of Outsystems professionals, freelancers, and community members. Scaling needed clear guidelines, templates, a process to select who could contribute, and frequent feedback to contributors.
6. Gave feedback to product developers (as usual with technical writing) to shape the product.
7. Hosted the documentation in GitHub to accept contributions from the community.

Finally, Paulo wrapped up his presentation with the following advice:

• Reframe success by defining what are the knowledge needs and measuring what matters.
• Rethink knowledge as a product, which you need to define and manage.
• Embrace the needs of the users and stand up for them. Let the users lead the way.

Breakout rooms and questions

As the presentation finished at 19h20, some people left. To give the remaining 14 participants the opportunity to interact “almost like face-to-face”, we randomly split the participants into 3 breakout rooms. The objective was for the participants to network, exchange comments and, hopefully, return with relevant questions.

The presence of several current and former Outsystems employees influenced the networking in each breakout room. When we reassembled the crowd by 19h35, some questions had already been answered. Just like a face-to-face meetup, I might add.

Nevertheless, each group asked a couple of questions. Paulo engaged Outsystems employees in the audience to answer some of the questions.

The meeting ended at 20h45.

— Joaquim Baptista

Final words

Our profession argues endlessly about job titles, and we take for granted that we just do “whatever it takes”. We seldom see people articulating the value of our profession in terms that make sense to business, and Paulo did that brilliantly.

Thanks to ISCAP for sponsoring Zoom.

Second invitation (12-Dec)

This is a gentle reminder for our meeting next Monday, starting at 18h.

• Zoom direct link
• Zoom ID: 839 3807 7126
• Zoom password: 927953

I look forward to meet you on Monday,

— Joaquim Baptista

PS: Next Wednesday there will be a sister event on UX Writing. Check it out on meetup.

The invitation (28-Nov)

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

I miss face-to-face events, but you cannot say these events were ever perfect. For example, last-minute surprises often prevented me from traveling to events.

Virtual events are not perfect either. I miss being close to people. Still, with some ingenuity, we can recreate some of the interactions that made it worthwhile to travel to physical events. And I believe we did this quite well on June 2nd.

So, we are planning a full “formal” event, featuring a presentation, participant interaction and feedback, and a post-event report:

• Monday, December 14th, 18h00-19h30.
• Zoom ID: 839 3807 7126
• Zoom password: 927953

Paulo Tavares (OutSystems) — Technical Knowledge: Rethinking Tech Comm Teams

In a product setting, technical communication exists for one reason: to enable users to accomplish their goals with the product. To successfully accomplish this goal, we need to break down the traditional organizational silos of Documentation, Training, Product and Support, and move the conversation to a higher level: one of Technical Knowledge.

With Technical Knowledge as the focus, each of these areas is empowered and equipped to think about the problem from a unique perspective and to collaboratively – and proactively – come up with the best solution for the user from the early product design stages.

Notes of interest:

• Paulo will present in Portuguese, and conversations during the event will be in Portuguese.
• The participation is free, subject to room capacity (300 people).
• There will be an opportunity for participants to interact, so plan ahead your audio and video.

Feel free to extend this invitation to friends and other interested parties. More interesting participants will improve the learning experience for everyone.

Thanks to our sponsors for all the support: ISCAP (virtual room), APCOMTEC (marketing and more) and EuroSIGDOC (site).

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

PS: The 2nd edition of the post-graduate course in Technical Communication starts in January. You can still apply.
https://www.pea.iscap.ipp.pt/programas/pos-graduacoes-executivas-1/comunicacao-tecnica

PPS: Subscribe to the mailing list to be the first to know about any events. https://groups.google.com/g/technical-writers-lisbon

The 13th formal meeting was spurred by opportunity. Rosário Durão was passing through Portugal, and the date suddenly emerged as the only option to hear her in Lisbon. Farfetch accepted to host an evening meetup in the new Lisbon office, but required one of the speakers to be from Farfetch itself, which means that Joaquim had to be the second speaker.

The earliest participants arrived at 18h30, so that they had time to tour the amazing views from the terrace.

Most of the participants entered the building through the wrong door, managed to go up to the second or third floor, and got quite confused in front of closed doors. Frantic phone calls ensued.

Ultimately people had to go back to the street and enter the building through the correct door. All this activity made the first presentation start at 19h30.

Joaquim Baptista

Joaquim presented his recent experience and opinions on AsciidocFX, a freeware editor that provides good facilities to take structured notes.

AsciidocFX customizes the well-known Atom editor to handle AsciiDoc, a plain text format that is much better than Markdown but still weaker than ReStructured Text. AsciiDoc is readily extensible, and seamlessly incorporates PlantUML drawings, for example.

AsciidocFX deploys everything needed to convert the text and diagrams into PDF, HTML, and ePub books. The typography is good enough to use without special configuration. Writers can quickly draft documents combining both text and technical diagrams.

However, both the AsciidocFX editor and the Asciidoctor parser have their own flaws. These flaws prevent their adoption as a backbone for serious technical writing. Joaquim is moving the Farfetch infrastructure to DITA, but AsciidocFX earned its place as a technical scratchpad.

Rosário Durão

Shortly after 20h, the audience encouraged Rosário to innovate by presenting in English over slides in Portuguese.

She explained the principles of crisis communication, which requires both planning and courage. Crisis communication must involve the public, establish credibility, and contribute to overcome the crisis.

The planning phase forces the company to identify its operating risks. Accepting and dealing with the operating risks helps to create a safe environment that is a prerequisite for innovation, especially in large companies where internal politics can easily hinder change.

The presentation ended with an open conversation where the audience considered how the principles applied to their own companies.

Daniel Bofill and Laura Goetze

Daniel has been a speaker at Technical Writing meetings since the very beginning, so when he started to take AcroYoga seriously it felt very natural to ask for a demonstration.

Daniel and Laura had been warming up during the presentations, in a space behind the audience. Shortly before 21h, we joined them for the demonstration.
After a short introduction, Daniel and Laura demonstrated the strength and equilibrium required in AcroYoga. More importantly, they explained how the two partners communicate with sight and motion.

AcroYoga requires trusting others physically, which can be quite difficult for some people. AcroYoga can be used to teach trust.

Daniel and Laura demonstrated that trust with another Laura, which was asked to let herself became a pendulum among them. Daniel proceeded to challenge another audience member into a more acrobatic exercise.

The demonstration ended with the lunar part of AcroYoga, where one of the partners cares for the body of the other, which assumes a more passive posture. It became beautifully clear how AcroYoga fosters intimacy between trusting partners.

Pizza break

Farfetch offered pizza and drinks, which was a novelty at Technical Writer meetups.

Pizza made people stick around for an extended networking period of about one hour. People talked and experienced some of the amenities in the new office, including the suspended chair and the signature ball pool renowned for freeing the inner child inside grown ups.

Final words

Usually all participants receive a paper questionary, but not this time. It was not before the end of the meeting that dawned on me that I had completely forgotten to bring and distribute the public notes forms. I asked for feedback through email.

Rosário had promised to raffle one free registration for her upcoming trainings in Portugal, but AcroYoga and Pizza apparently made us forget. Later I collected the names of the participants, and Rosário drew two names: Marco Correia and Ana Pinto.

Special thanks to Rosário for once again sharing her knowledge in Lisbon, to Farfetch for hosting the meetup, and to Andreia, Cristina, and Luís for handling all the logistical details.

The invitation (13-May)

We are excited to announce our 13th formal meeting, sponsored by Farfetch.

• Thursday, May 25th, 19h00–22h00 (come early).
• Farfetch Lisbon office.
• Rua do Instituto Industrial 7 – 3rd floor, 1200-225 Lisboa (a 10m walk from Cais do Sodré).
• You will have to identify yourself to the security guard on the ground floor.

Come see Farfetch’s new Lisbon office, learn from your fellow speakers, and network over pizza!

Joaquim Baptista (Farfetch): Plain Text with AsciidocFX

Joaquim shows how the editor AsciidocFX turns the plain text format Asciidoc into an insightful drafting tool, even if Asciidoc falls short as a production writing tool.

Rosário Durão (New Mexico Tech University): Innovate with Security

Rosário shows how risk and crisis communication leads companies to identify and deal with their business risks. Managing risk creates a safe environment that is a prerequisite for innovation, especially in large companies.

Daniel Bofill (SISCOG) and Laura Goetze: Communication within AcroYoga

Daniel and Laura demonstrate their passion for AcroYoga, where movement and play elevates the connection between practitioners to new levels of union and trust.

The participation is free, but subject to room capacity. Please reserve your place at Meetup.com. Feel free to extend this invitation to friends and other interested parties. More interesting participants will improve the learning experience for everyone.

Thanks to our sponsors for all the support: Farfetch (room and coffee-break), APCOMTEC (marketing) and EuroSIGDOC (site).

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

PS: In case you missed it, the 12th Report is available at http://pxquim.com/files/2017-03-twl-report.pdf

PPS: Rosário Durão will offer one free registration for her upcoming trainings in Portugal. See DesignThynk.com for details.

Attachments

The 13th Report — 22-page report of the meeting, including the slides of the presentations.

After some weeks of preparation, we finally held the 12th edition of Technical Writers @ Lisbon, this time at Feedzai’s Lisbon office in Parque das Nações.

Participants started arriving before and around 9AM as scheduled in a joyful mood and commenting about the amazing office view overlooking the Tagus river. We gathered in the lounge area marked by an informal atmosphere, with a TV, sofas and a pool table that also doubles as a ping-pong table.

Not much after 9AM presentations started with some familiar faces in the audience and quite a few new ones. Twenty people attended the meeting, including not only technical communicators but also software engineers and people from other backgrounds.

Joaquim Baptista

Joaquim opened the event with a short introduction to the group and quickly explained the rules of the game, including the usual public notes and how he would then publish a summary of the event in a report.

Nuno Grazina

Feedzai has experienced tremendous growth in the past few years and is now at that “not quite a big company but no longer a startup” stage. To go along with this growth, the company started a Technical Communication team as they can no longer afford to just release software with some last-minute docs.

Nuno explained what Feedzai is looking for in a Technical Communicator and why it has been so hard to find such people. The presentation started by introducing how industry terms like Technical Writer are starting to seem more and more outdated, as a Technical Communicator does so much more than just writing.

However, those are the terms the market recognizes and the job titles we still must use when posting job offers. And what Feedzai has observed is that most people that respond to these ads end up failing not only on language aspects but also by being unable to extract relevant technical knowledge and expose it in a relevant way.

Then, Nuno presented 10 key characteristics that a Technical Communicator should have, and the ones Feedzai is looking for when hiring. Some of these traits may be innate and behavioral, while others are more technical. But what they have in common is that they need to be nurtured and developed.

The conclusion, and after some Q&A discussion, is that as companies realize the value of having a technical communicator in their ranks, the market is still not responding to the challenge. And while we can’t move our eyes off the prize and just lower the bar or give up on trying to find this super-being, unicorn or mythical creature, it’s up to us to push forward and find alternatives. And the most fitting one seems to be considering not the individual as the unicorn but the team itself. The sum of each individual’s best skills will end up fulfilling these 10 key traits and even taking them further.

Coffee break

After the first presentation, we moved to the kitchen area for coffee and some snacks gently provided by Feedzai. Everyone was engaged in conversation whether it was about what had just been discussed, the company itself or other related topics.

Helena Pires

Helena joined Vision-Box in 2014, coming from a linguistics background and extensive experience in editorial coordination and translations. She wasn’t a technical writer before that, and landing at a technological company, having to quickly learn the ropes of a new job, she experienced first-hand the necessity of having some structure and guidelines.

When a new member joined the team, and started asking questions, she drew on her past experience and started working on a Style Guide as a way of exposing a reference of the team’s learnings and best practices.

Helena described the Style Guide as a broad and encompassing tool that includes spelling and grammar rules, writing guidelines, how to organize the different types of documents, correct usage of technical terms, etc. Documenting hardware manuals, software manuals and end-user guides, and handling translations for all these types of content made it clear that the Style Guide could not just be mere generic recommendations and suggestions.

The sheer variety of content, its complexity and the intricacies of the documentation toolchain (in DITA) stressed the need for a very thorough and complete code of best practices. Although it is a continuous work in progress, it became clear to the audience that this tool is much more than what we might think of when considering a regular Style Guide.

The Q&A session generated a lot of interest from the participants, as it was a very practical topic that resonated with the audience. In the end, there was a general consensus that having their own versions of such Style Guide would be very useful to anyone in the audience.

Jorge Leal

Jorge presented his personal account of what technical communication means to him and how his experiences led him to move from Spain to Lisbon where he currently works at Feedzai.

He started out by explaining his view on how a combination of passion for writing and literature and an early exposure to technology, brought the “technical” and the “writing” together. He studied English Philology and now works in the engineering department of a software company. That may seem strange, but for him it is only natural.

It’s also natural for him to think in broader terms than just technical writing. He described his views on what modern technical communication should be: Current, Human, Proper and Fresh. Docs must be correct and up-to-date but they also must feel like a human wrote them to be easily understood by other humans in an easy and appealing way.

He concluded his presentation reflecting on what his experiences led him to believe is the best way to continually learn and improve as a modern technical communicator. In general, always looking forward, trying to find better and innovative solutions, communicating in a personal and unique voice, not getting stuck in old patterns and not settling for what’s already comfortable.

The audience was very engaged by seeing a seemingly old concept being presented in such a personal and heartfelt way. The Q&A session was confirmed the initial idea that in Technical Communication, what really makes the unicorn is the combination of unique people, points of view, and skills in the same functional unit. And that’s what we should strive to achieve as Technical Communicators.

Final words

Special thanks to the speakers for the diverse and though-provoking presentations, and to Feedzai for just letting us borrow their workspace for a whole morning.

— Nuno Grazina, nuno.grazina@feedzai.com

After years of driving the meetings of Technical Writers @ Lisbon, I felt a special pleasure in seeing Nuno accept the challenge and organize a very successful meeting. He invited and coordinated the speakers, secured the location and the coffee-break, and put together a perfect morning. I learned from the three presentations.

The eternal challenge of the community has been to make these sessions regular. Let us know if you can offer a location, or if you would like to present. Presenting what you know is a good way to consolidate your own knowledge. And presenting is never difficult when you present among friends.

— Joaquim Baptista, px@acm.org

PS: If you care about such things, we finished the morning on schedule at 12h30.

Second invitation (23-Mar)

Greetings again,

This is a gentle reminder for the meeting next Saturday, with some updated information.

• The building is right next to the Oriente station. See the photo below.
• The building is closed on Saturdays. Ring the bell, wait for the security personnel, then go up to the 11th floor. Wave or knock on the door.
• The event will be in the lounge. Expect an informal space.

The tentative agenda is the following, subject to delays imposed by your questions:

• 09:00 — Introduction to the group, and rules of interaction.
• 09:30 — Nuno Grazina — Technical Communicators: Why we rarely find the in the wild.
• 10:15 — Coffee-break, sponsored by Feedzai.
• 10:45 — Helena Pires — Documentation changes but style remains: The importance of a Style Guide in technical documentation.
• 11:30 — Jorge Leal — Aesthetically functional.
• 12:15 — Wrap up.
• 12:30 — Lunch. Join us to continue the conversation!

PS: Note that the report of the 11th meeting is (finally) live here or at pxquim.com.

First invitation (12-Mar)

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

We are excited to announce our 12th formal meeting:

• Saturday, March 25th, 9h00–13h00 (be sharp).
• Feedzai Lisbon office.
• Avenida D. João II, Lote 1.16.01 Piso 11, 1990-083 Lisboa.
• The main door to the building will be closed. Ring the bell.

Nuno Grazina (Feedzai): Technical Communicators: Why we rarely find them in the wild

Nuno will provide an overview of the main traits of a good technical communicator, and discuss why setting the bar so high is making it that much harder for Feedzai to hire the right people.

Helena Pires (Vision-Box): Documentation changes but style remains: The importance of a Style Guide in technical documentation

Helena will provide a survival guide for writers with no technical background who want to thrive in a hi-tech environment, and give some insights on the importance of having a Style Guide in technical documentation.

Jorge Leal (Feedzai): Aesthetically functional

When looking for functionality and clarity, sometimes appearance is overlooked. In this presentation, Jorge will tackle technical writing from an aesthetic point of view: what we should aim for when documenting is not only for it to be concise, but also appealing and current.

The participation is free, but subject to room capacity.

Thanks to our sponsors for all the support: Feedzai (room and coffee-break), APCOMTEC (marketing) and EuroSIGDOC (site).

We are also delighted to welcome Nuno Grazina as organizer! For this meeting, he both secured the location and selected the speakers!

— Nuno Grazina, Feedzai, nuno.grazina@feedzai.com
— Alexandra Albuquerque, APCOMTEC president, info@apcomtec.org
— Carlos Costa, EuroSIGDOC chair, carlos.costa@acm.org
— Joaquim Baptista, EuroSIGDOC vice-chair, px@acm.org

PS: Feel free to extend this invitation to friends and other interested parties. More interesting participants will improve the learning experience for everyone.

Attachments

The 12th Report — 29-page report of the meeting, including the slides of the presentations.

This 11th formal session introduced the roles and tasks of technical writers to MSc. students in Management of Information Systems.

The class has ten working students, which attend the classes after their regular work. Students arrived at their own pace, with Prof. Ângela Nobre using the initial time to talk to students about upcoming classwork. Eventually, eight of the ten students arrived.

My presentation proceeded without any incidents, and then students asked about the profession and considered how their companies might apply technical writing. The questions were lively and plentiful, creating a very positive experience.

Why did the report take so long?

This report took four months to complete.

Reports make sense when practitioners present new talks, as a way to capture some of the rich interaction that follows. Other practitioners usually offer further insights into each presentation.

Sessions aimed at students reuse past presentations, which makes the corresponding reports repetitive. Also, students do not feel part of the community. Therefore, students mostly abstain from contributing to the public notes, besides thanking for the session.

While presentations to students make sense to disseminate technical writing, I believe that we should engage students in a different way, perhaps using active learning practices.

Invitation (11-Nov)

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

Next Tuesday there will be a class for students in the MSc. in Management of Information Systems at Instituto Politécnico de Setúbal, 50 Km South of Lisbon. Since the class will be delivered in Portuguese, the rest of the announcement will also be in Portuguese.

Saudações!

No âmbito da cadeira Organizações e Sistemas de Informação do Mestrado em Gestão de Sistemas de Informação, a professora Ângela Nobre organiza uma aula aberta sobre escrita técnica:

• Terça, 15 de Novembro, 18h30-20h30
• Instituto Politécnico de Setúbal, Escola Superior de Ciências Empresariais, Sala C1-07

A aula terá uma única apresentação (a mesma que foi apresentada na conferência CAPSI):

Joaquim Baptista, escritor técnico sénior

Gestão do Processo de Negócio, Tecnologia e Inovação Organizacional: o papel estruturante da Escrita Técnica.

Tem sido habitual nestas aulas abertas uma animada interacção entre oradores e alunos. Estão todos convidados a participar… especialmente os residentes na margem Sul que se queixam que “Lisboa é longe”.

Attachments

The 11th Report — 11-page report of the meeting, including the slides of the presentation. For technical reasons, the report must currently be hosted on an external site.

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.

My 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.

On 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

Eunice 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.

Paulo 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.

Joã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.

Finally, 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.

At 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.

Fifteen people attended the meeting, including nine people that stayed for lunch.

Mariana set up camp at the entrance, while I prepared the large open space on the first floor. Not knowing how many people to expect, we started at the largest space, where about 50 chairs face a projection screen.

Joaquim Baptista

Most people arrived after 9h, and I started my presentation at 9h15. The presentation was aimed at people new to the group, to alleviate the confusion that we sensed at FCSH.

I told my story of how I entered technical writing, what caused me to start the group, and how the group has moved forward with the generosity of so many speakers and sponsors.

The presentation generated some unexpected discussion about the tech writing in general. I cut the discussion short when I sensed that the next speakers would give the context that the audience was asking.

Considering that the audience was far from 50, we moved to the nearby area with enough tables for 22, and much more comfortable to take notes.

Nuno Grazina

Nuno was a former colleague of mine, so I was quite interested in his story.

Nuno was at Vision Box for 1.5 years, when the company grew from 80 to 200 people, and R&D grew from 15 to 50.

The Bid team initially had enough time to start each proposal from scratch. Nuno joined the team to offload the writing work from the team leader.

Nuno questioned the contents of proposals, aiming to have proposals that answer the right questions. He started a virtuous cycle of continuous improvement, adding reusable content with each new proposal. Over time, a team of three persons grew the ability to quickly create proposals by reusing parts of previous proposals.

When writing became the easy part, the sales cycle shrank while increasing the confidence of the customers.The Bid Team gained free time to innovate and reach out to other parts of the company. They created demos, proposed new product features, and eventually gained the product roadmap.

Nuno succeeded by using thought processes alone, without adopting any specific tool. He complained about the limitations of Word on documents over 70 pages, when even moving content around becomes difficult.

The Bid Team never created a database of reusable content, which means that the three members of the team fielded questions about reusable content for proposals. Nuno ultimately felt overloaded with questions and left the company.

Nuno’s story is a compelling case for the importance of the thought practices of technical writing (the tools of the trade) on proposal writing, and business processes in general.

During the discussion period, Paulo Ribeiro came forward as the head of Technical Writing at Vision Box, a department that faced different challenges. He continued my principles at Altitude Software, adopting DITA Open Toolkit and the editor Syntax Serna freeware, later replaced with Oxygen. He also repelled the need for an expensive CCMS.

Coffee break

The €0,55 coffee machine downstairs avoided the need to hunt for a coffee house outside. Everyone agreed on a short break, and we restarted quickly.

Rui Costa

I was eager to listen to Rui, with a career as a technical writer longer than my own. Rui has accumulated a long career in multinational companies, and shared insights on the different cultures and company strategies that he experienced.

He discovered “users” when he accepted to give computer lessons to a nine year old Italian boy. He then became a technical writer at Olivetti, a very large and successful company at the time that disappeared completely in Portugal.

He moved on to Papelaco, a Portuguese company from Torres Vedras that succeeded in becoming a multinational. At some point the company went to Germany to present its products at a fair, but a few days later had sold itself to a larger company. Rui recalled how the employees lost the magic thrill of belonging to a special Portuguese company.

Rui joined Nokia-Siemens Networks, later Coriant. He told the story of a company with a mix of German and Finnish management cultures that was never settled. He was also part of a larger team of writers.

He later joined Collab, where he found a situation similar to that of Papelaco years earlier. Collab, a division of Novabase, are feeling the growing pains of international growth, and learning that trying to win every business opportunity comes at a hefty price. Overworked as the sole writer, he faced a clear tradeoff between maintaining quality standards and delivering on time — choosing the former, to the detriment of the later.

I could relate to Rui’s bitterness at Collab. Circumstances often forced me to accept the possible instead of the desirable, either as writer or as team leader.

Daniel Bofill

Daniel shared details of the ongoing project of improving documentation at SISCOG. He has been working with international consultants to introduce the best technologies and processes company-wide.

The proposed content management strategy did a good job of convincing the audience, especially the new people in the audience. He plans to adopt DITA, reaping its usual benefits. He also plans to create embedded help with a dynamic web server.

During the discussion period, Nuno Grazina and Paulo Ribeiro questioned the need for an expensive CCMS.

I did very well without a CCMS in Altitude Software, but then I was never in a position to deliver dynamic content. The team never caught up with updating and rewriting the legacy content into modular topics that could support useful forms of dynamic delivery.

Lunch

We finished the formal program on time, for the first time ever, but the conversation continued in small groups. It took time for a group of nine to start moving and go look for a restaurant. We enjoyed traditional Portuguese cuisine in a typical Lisbon “tasca”, with even more conversation, until 16h30.

— Joaquim Baptista, px@acm.org

---

(The two invitations for this event follow.)

Second invitation (29-Jan)

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

This is a gentle reminder for our 9th formal meeting next Saturday, January 30th. Time will be tight, so please be sharp:

• 09h00: Joaquim Baptista, About Technical Writers @ Lisbon.
• 09h30: Nuno Grazina, How to write proposals.
• 10h30: Break, on your own.
• 11h00: Rui Costa, 20/20 hindsight? Lessons from the TW front.
• 12h00: Daniel Bofill, Update on a company-wide CMS.
• 13h00: Lunch, on your own.

The meeting room is on the 1st floor, and we will have the place for ourselves. Which is a problem: we will have to guard the entrance door on the ground level. So:

• Arrive on time if possible.
• If you know someone that might help us at the door, please have them contact me.
• Don’t panic if the door is closed when you arrive. Wait a bit, then call me: 91 784 2996.

There are €0,50 coffee machines in the place. Hopefully there will also be open coffee-shops nearby, but I could not check.

Although lunch is not strictly part of the meeting, a few of us usually stick around after cleaning up the room and have lunch nearby. You are welcome to join us.

See you next Saturday!

— Joaquim Baptista, EuroSIGDOC vice-chair, px@acm.org

PS: Remember that in the 8th formal meeting Rosário Durão taught us about active learning? One month later, Nature had the following to say:

At this point it is unethical to teach any other way.
— M. Mitchell Waldrop, Nature, 15 July 2015.

PPS: Happy birthday, Rosário!

First invitation (5-Jan)

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

We are excited to announce our 9th formal meeting:

• Saturday, January 30th, between 9h00 and 13h00 (be sharp).
• Startup Campus powered by BANIF.
• Rua Rodrigo da Fonseca nº 11 — 1250-189 Lisboa.

Joaquim Baptista, About Technical Writers @ Lisbon (9h00-9h30)
Joaquim introduces the tasks of professional technical writers and explains the guidelines and objectives of these meetings.

Nuno Grazina, How to write proposals (9h30-10h30)
Nuno talks about successful proposal writing, based on his rapid progression at Vision-Box from bid analyst to program manager.

Rui Costa, 20/20 hindsight? Lessons from the TW front (11h00-12h00)
Rui shares insights from 26 years of technical writing experience at Olivetti, Papelaco, De La Rue, Siemens, and Novabase.

Daniel Bofill, Update on a company-wide CMS (12h00-13h00)
Daniel explains how a unified CMS (Content Management Strategy) could simplify documentation practices and team collaboration at SISCOG.

The price of participation is to provide your email to Startup Campus. You will receive announcements about their acceleration programs for entrepreneurs.

Thanks to our sponsors for all the support: Startup Campus powered by BANIF (room), APCOMTEC (marketing) and EuroSIGDOC (site). And special thanks to Shannon Graybill for welcoming this event.

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

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

PPS: Plan to attend TCeurope next April 15th in Porto.

PPPS: Live Sketching captured Joaquim’s 5-minute Ignite presentation of Nov-2015. As usual, they did an amazing job!