APCOMTEC has been promoting a Summer School since 2019. This year, Alexandra Albuquerque had the opportunity to promote the Summer School as an Erasmus+ Blended Intensive Program.

Since today, some of my professional writing is finally public, in the form of an article explaining the major concepts of Git. This is a companion "making of" article.

This presentation started as an unexpected opportunity to present at the ISTC Meets. Usually, the sessions are planned many months in advance.

I have agreed to fill-in for a slot at the "ISTC Meets" webinars. I decided to recover and update part of a mythical 3-hour class I delivered at ISCTE in 2015, focusing on my experience in using different tools in specific scenarios.

Today was my last working day at FARFETCH. I found myself sharing two stories at the office that had an impact on colleagues.

In APCOMTEC's reality, each event is nothing short of a small miracle that somehow persists exist against all odds.

How do you explain a large complex system that is under constant rework to pursue an evolving business reality?

The unexpected news of the day (or the year, or the decade) is that EuroSIGDOC just won the Diana award, for their long-term contribution to the field of communication design. The work of Technical Writers @ Lisbon was one of the reasons for the award.

Oops! APCOMTEC did it again!

The usual suspects have been considering how to expand on the successful Summer School organized since 2018 by TCeurope and now APCOMTEC.

As teachers and organizers were mingling in the Summer School earlier this year, we learned that Nick Hill had done an extended presentation …

As I took my motorcycle back to Lisbon though the leisurely N1 road on the afternoon of Jun 18th, the words of two former students kept coming back to my mind. "I like my new job so much that it doesn't feel like work at all!"

It's time for face-to-face events again, or perhaps hybrid events. APCOMTEC, with the support of all the usual suspects, is organizing a half-day presential event on Saturday, November 6th.

SIGDOC'2021 experimented with a mixed format that combined regular online events, both synchronous and asynchronous, with eight additional presential meetups called "hubs". For the Lisbon Hub, EuroSIGDOC interviewed Robert Pierce, Konstanze Alex, and myelf.

As part of the Farfetch F-Tech Talks, I reported on the tools and processes used at Farfetch to create and publish API documentation, and how they evolved over time.

The API documentation combines traditional DITA topics with API references generated automatically through Open API specifications. The generation of API references …

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 …

33 persons attended the 15th formal meeting, which took place virtually through the BlueJeans conference system. After the presentation by José Aragão, we challenged the participants to apply their new skills.

20 persons accepted the challenge. We split the participants among five virtual rooms, and asked them to rewrite four …

I had the privilege to teach structured writing at the first edition of the Postgraduate Course on Technical Communication at ISCAP (Portugal), sponsored by APCOMTEC, the Portuguese association for technical communication.

The seven students were working professionals looking forward to change or improve their careers. I was surprised when these …

“An image is worth a thousand words. Why can't you draw me that picture? Or create a five-minute video to replace those manuals?”

I have heard similar sentences over the years. Although a good image may make me think of a thousand words, I could never take a thousand words …

I wanted to attend the Technical Communication UK conference for years. The conference offered a reasonably priced residential fee in a countryside hotel. For a foreigner, this means an affordable conference, with more opportunities than usual to network with local colleagues.

Networking happed over breakfast, lunch, dinner, evenings... and even …

This talk and demonstration was presented at the Product Tank Lisbon meetup to a group of 36 people, including some technical communicators.

The three-hour workshop that I delivered at the Summer School had been accepted as a 90-minute workshop at the TCUK conference. Even after throwing away the screenplay part …

During the last TCeurope Summer School, I taught 12 people how they might use comics to communicate the effects of technology in people.

APCOMTEC (the Portuguese Association for Technical Communication) proposed the Summer School in 2018 as a first step to advance Technical Communication training at ISCAP (a school of …

Eight persons attended the 14th formal meeting, which happened to be the lowest attendance ever at a formal event. Of course, that did not make the talks any less interesting, or the conversation any less insightful. You just had to be there, for the talks, for the pizza, and for …

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

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 …

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 …

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 …

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 …

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 …

Eleven people attended the presentation by Rosário Durão at ISCTE. She presented her ongoing research on ways of visualizing science and technology.

The VISTAC research project aims to distinguish between what is universal and what is culturally specific in visuals and visual conceptualization in different parts of the world.

The …

Five persons attended the informal meeting at the bar “Foxtrot” at Bairro Alto. The first person arrived at 18h30. The group broke up at 22h00. Nobody remembered to take pictures. We were too busy talking...

The conversation ended with a surprising offer for a room. In the future, this room …

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 …

The economic crisis in Portugal stimulated the creation of product companies that sell worldwide. Over time, these companies accumulate a capital of knowledge (technical, domain, user) that benefits from governance and engineering by dedicated professionals, traditionally called technical writers.

Technical writers have the ability to learn, organize, and transform knowledge …

Eight people attended the informal meeting at the bar “Irish & Co.” at Parque das Nações. The first person arrived at 18h00, but two people arrived around 20h00. The group broke up at 21h00.

The chat was varied and lively. We had a few vacation reports (some of us drove all …

Nineteen different people attended the meeting, including sixteen in the morning, twelve at lunch, and fourteen in the afternoon. Some people only came in the morning or afternoon.

At the end of the day, I believe that the attendees met new people, enjoyed themselves, and learned. Of course, we always …

After the class at FCSH on April 22nd, professor Rute Costa praised the event to her colleagues. Some students did not attend the first class because of scheduling conflicts, so Rute asked us to go back for a second class. We set a new date. Unfortunately, Rui Diogo Serra could …

Carlos Costa challenged me to give a class on the importance of technical writing to his students of Software Engineering. However, he warned me that these students preferred technical topics and might despise management topics, for example. In the end, I decided to approach this class by recounting 21 of …

Looking back at what Technical Writers @ Lisbon has achieved in the last two years, we surprised ourselves with the interest and quality of the presentations at our formal events. However, only a handful of people attended each presentation, and few people attended all of them.

Professor Rute Costa accepted our …

Twelve people attended the informal meeting at the bar “39 degraus” (29 steps) at Cinemateca Portuguesa.

The first person arrived before 18h00, but the conversation started shortly after 18h10. People kept arriving as late at 20h00. Eleven people stayed for dinner, mostly with a choice of burgers or fresh pasta …

The five minutes of presentation by the CódigoPro team were based on the seven slides below. I added the main points made on each slide.

Traditional business model

Since I knew that most people in the room did not know CódigoPro, I spent precious minutes explaining the strengths of their …

Although all past projects are hosted at the community site of the Global Editors Network, you need an account to download all the information and to contact the authors.

Público, Contextualizando (winner):

A tool for newsrooms, enabling syndication of news related to breaking stories. Source newsrooms (for example, Público in …

Pedro Lomba, Secretary of State, visited the EditorsLab on Friday morning. Pedro has the curiously long title of “Adjunct Secretary of State of the Adjunct Minister for Regional Development”.

Pedro publicly stated his enthusiasm for technology. He believes that journalism is not over, because individual creativity is not over.

As …

Ricardo Lafuente of Journalism++ talked about data journalism. He talked Thursday at 15:30, in Portuguese.

Ricardo started by recalling that, in 2013, the New York Times interactive had 18 journalists and 30 graphical designers. If we have less money than them, we must remain frugal.

In summary:

1. Use free …

Google was represented at EditorsLab by Luis Collado, the head of Google Books and Google News for Spain and Portugal. He talked Thursday at 10:30.

Luis started his presentation with two very strong ideas. First, that Google believes in the value of information, which is the base of a …

In the words of Evangeline de Bourgoing (the program manager), the goal of EditorsLab is to build innovative prototypes, to encourage innovation in the newsroom, and to encourage collaboration between the journalist, the designer and the developers, that are not as used to work together.

• The Global Editors Network is …

For the first time, the Global Editors Network brought to Portugal the EditorsLab friendly competition, in association with Google and the Portuguese Publishers Association (APImprensa). The competition happened at CENJOR, February 26 and 27th, 2015.

Competing teams comprise a journalist, a designer and a developer. I was invited to participate …

As we tried to fit a formal meetup before the end of the year, we faced a shortage of Saturdays. So, we took the opportunity to try something different: a formal meetup in a Thursday evening.

By 7 p.m. we had set up the auditorium. Manuela was thoughtful enough …

As I clean my desk at Altitude Software in the week before my final dismissal, I stumble across my old ID card for “Clube EASYPHONE”. I can hardly recognize myself in the photo. I've lost that beard years ago! Where did that 30-year old boy from 1998 go?

It was …

Seven people attended the informal meeting at the terrace of Hotel Altis Avenida. This time, everyone found the correct Altis hotel.

The meeting started shortly after 18h00, and we broke-up the meeting after 20h30. However, four people had a follow-up conversation at Starbucks, and two of those continued the conversation …

From 31 March until 29 June the IC Clear consortium will run four ONLINE pilot modules of the IC Clear course to which you can apply. Module 0 starts on 31 March and ends 27 April (4 weeks). The other three modules 1, 2, and 3 follow module 0 and …

I was surprised to realize that only six people were attending the workshop that had the four of us travel all the way to Aveiro. There were a few sit-ins for the first hour, but they withdrew by the lunch break.

History of Plain Language

True to her style, Frances …

The creator of the ColorADD system, Miguel Neiva, could not speak at the event, and was replaced by António Guedes de Oliveira.

António Oliveira started by distributing colored paper and plastic glasses to part of the presenters, then showed a few color images. The paper glasses changed the colors in …

Four people shared a car from Lisbon to Aveiro in order to attend the third technical communication meeting by APCOMTEC, the Portuguese association of Technical Writers. In particular, I had the company of Maria Spínola, Laura Barros, and Carlos Costa.

Everyone agreed that getting out of bed early enough to …

Presentations by local technical writers have shown a surprising diversity of writing and content governance scenarios on mature software companies. Mature companies have unique business problems that require unique technical and human solutions.

On Altitude Software, writers struggle to control the complexity created by the organic growth of a mature …

ISDOC‘2014 (Information Systems and Design of Communication) benefited from crossing the growing traditions of EuroSIGDOC conferences in Lisbon and informal practitioner meetings in Lisbon. Everyone involved was important.

There was a warm atmosphere at the conference this year that contrasted with the contemplative mood typical in previous years. This …

Four people attended the informal meeting: Daniel Bofill, Laura Barros, Carlos Costa, and myself. We met at 18h30, and left at 22h15.

First we talked about structured writing and about upcoming conferences, namely TCUK’2014 (16–18 September, in Brighton, UK) and UX-Lx (4-6 June, in Lisbon).

Then we talked …

13 persons met for two hours of friendly conversations.

The group started gathering outside but, by 19h30, it was too cold to stay outside. As the six of us were about to occupy two small tables in the corner, more people started to arrive, and the employees quickly set up …

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 …

Eleven people attended the informal meeting at the terrace of Hotel Altis Avenida (and a few people noticed that there are other Altis Hotels in Lisbon).

The meeting started shortly after 18h00, and the last four people left the hotel at 21h30.

We just talked, together or in small groups …

We had 31 registrations, including 21 professionals, 7 teachers, 7 researchers, 3 students, and 1 journalist. We had 26 persons attend the meeting.

We started at 9h15 with brief welcome speeches by Carlos Costa (on behalf of ISCTE and EuroSIGDOC) and Ana Rita Remígio (on behalf of APCOMTEC). Some of …

See What I Mean: how to use comics to communicate ideas
By Kevin Cheng
Rosenfeld Media, 2012
ISBN: 978-1933820279

This is a small book that ultimately got me to dabble with comics professionally, as a means to convey technical information. The book is small enough and practical enough to ever …

Being effective means that you make time to tackle your hard-to-solve problems, by solving the easy ones very quickly.

This talk was presented on 22 June 2011 at Agile Portugal 2011, which was held at the Faculty of Engineering of the University of Porto, in Portugal.

Managing a long-term agile team working on continuous improvements to a product creates specific challenges that are not usually felt in project-based approaches …

Ana Neves invited me to repeat the OSDOC'10 presentation at her event "Organização 2.0: Ferramentas sociais nas organizações" (Enterprise 2.0: Social tools in enterprises).

I repeated the presentation at ISCTE to an interested and enquiring audience.

References

Ana Neves is a consultant and the owner of Knowman, a …

For a technical writer, what is content strategy? And is content strategy relevant if you are not a consultant?

I watched as the new the term "content strategy" appeared and then evolved at the list contentstrategy@googlegroups.com since 2009, and I kept thinking that all these clever people were …

To announce the presentation The Birth of a Company-Wide Wiki at Organização 2.0, Ana Neves did an interview and then wrote a case study in Portuguese.

Her interview clarifies some details of the story.

Carlos Costa invited me to present my OSDOC'10 paper to his graduate students on open source software at ISCTE. The presentation took place in building ISCTE II, auditorium B203, Saturday, December 18th, at 11h00.

Attendance was open. The expectation is that invited classes at ISCTE might start a local community …

A small software company with a worldwide presence uses one wiki to store or access most company information. Using open source software, the wiki started as a small team tool and then grew to reach technical people. An innovative content strategy proposal later extended the reach of the wiki to …

A small software company with a worldwide presence uses one wiki to store or access most company information. Using open source software, the wiki started as a small team tool and then grew to reach technical people. An innovative content strategy proposal later extended the reach of the wiki to …

The Pentium Chronicles: the people, passion, and politics behind Intel's Landmark Chips
By Robert P. Colwell
Wiley-IEEE Press, 2006
ISBN 978-0-471-73617-2

You would imagine that a large company such as Intel would be extremely well organized... yet Bob recalls how the Pentium chip started to be designed in a storage …

This talk was presented on 26 June 2010 at Agile Portugal 2010, which was held at the Faculty of Engineering of the University of Porto, in Portugal.

Scrum assumes that a 2 to 4 week sprint can be planned in advance, with the work fully divided into 4 to 16 …

SHiFT was a grass-roots Portuguese conference about emerging technologies, whether they’re the latest internet trend or the latest social or engineering development.

Since SHiFT had an unconference part, I took the opportunity to test the presentation already prepared for OSDOC'10 on a small audience.

See the presentation at ISCTE …

A small documentation team working on a tight budget can now use the tool ecosystem enabled by the DITA standard to create the sophisticated content that previously required long and expensive projects. The author spent just nine person-weeks over three years to replace a custom XML system with a DITA …

uScrum (uncertainty Scrum) is an agile process developed by a small team at Altitude Software to manage the process of gathering information and writing documentation.

uScrum proposes different practices to estimate tasks, depending on their difficulty as defined by an order of ignorance. Understanding the difficulty of tasks has allowed …

The Social Life of Information
By John Seely Brown, Paul Duguid
Harvard Business School Press, 2000
ISBN 0-87584-762-5

Fascinating stories of people using newly invented technology at Xeroc PARC, such as the notebook, the local ethernet network, the word processor, and even the humble photocopiers. Because "The logic of information …

Just-in-time training workshops earned a reputation for the technical writers and disseminated new knowledge throughout the company, effectively training expert employees on new software releases with a series of light sessions.

The Seven Deadly Sins of Management
by Jonathan Ellis and René Tissen
Profile Books, 2003
ISBN 1-86197-526-0

I read this book in the Summer of 2003, after the NASDAQ bubble burst that took part of Altitude Software with it. The book explains how good ideas can go bad and, in …

The Tom Peters Seminar: Crazy times call for crazy organizations
By Tom Peters
Vintage, 1994
ISBN 978-0679754930

The book features many examples of unexpected ways to organize work towards satisfying customers. The examples are delightful. I started to see excellence in the small things, and learned to seek excellence in …

Ackoff's Fables: irreverent reflections on business and bureaucracy
Russell L. Ackoff
John Willey & Sons, 1991
ISBN 0-471-53194-4

Russel Ackoff was an American that also worked in India and taught in Mexico. He retells stories from those three cultures, including the US Navy, and then reflects on them.

This was another …

The Third Wave
By Alvin and Heidi Toffler
Random House Publishing Group, 1980
ISBN 9780688035976

I read the Portuguese edition of this book together with my wife during our 1999 Summer vacations in Nazaré. We both found the book delightful. The Tofflers explain history as a sequence of technological waves …

The Leader-Manager: Guidelines for Action
by William D. Hitt
IEEE Press, 1988
ISBN 935470409

This was my first book about management. I bought it as soon as it became apparent that I might became a manager later on, which means that I bought it in 1997 and probably read it …

Smalltalk-80: Bits of History, Words of Advice
By Glenn Krasner (editor)
Addison-Wesley Publishing Company, 1983
ISBN 0-201-11669-3

This collection of papers reports how different teams tried to implement Smalltalk-80 in different environments. Some chapters read like novels, and at the time I was astonished at the variety of approaches and …