All posts by Joaquim Baptista

20 May 2015, 7th formal, FCSH

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 not return on May 20th due to professional conflicts.

What happened?

The room was nicely filled with 15 students from the masters of Writing and Text Edition, plus the professors Clara Nunes Correia and Antónia Coutinho. Although they went to the trouble of requesting a larger room to leave space for outsiders, we had a single outsider.

Joaquim Baptista started by explaining the major difficulties and evolution of technical writing in Altitude Software between 1997 and 2014, including details of the hiring and coaching processes. Then, he explained all the different tasks that a technical writer can do, actually a summary of the tasks he did during his work at Altitude Software. This vision forms the basis for his new consulting business.

20150520-200844Daniel Bofill explains technical writing. Daniel Bofill explained the complexity of SISCOG products, especially their customization. He added details of the project to systematize all documentation, which was approved one month ago. He stressed that he was presenting the problems at SISCOG, and that he is still searching for the solutions.

Answering to a question, Daniel Bofill explained his view that technical writing is about the technique of writing, instead of writing about technical stuff.

Nine persons returned their public reports, mostly filled with curiosity and kind words.

There was some initial misconception in class that “Technical Writers @ Lisbon” was a comercial enterprise, and that misconception was only dismissed near the end of class. Some of the comments reflect that initial confusion.

I would like to thank professors Rute Costa, Clara Nunes Correia, Antónia Coutinho, and all the attendees for their attention and their questions. We certainly felt welcome.

2015-05-twl-report2-icon

The Invitation

Formal Meeting:

  • Wednesday, 20 May, between 18h00 and 21h00 (be sharp).
  • FCSH (Faculdade de Ciências Sociais e Humanas), tower B, floor 3, room T16.
  • Avenida de Berna, 26 — 1069-061 Lisboa.
Joaquim Baptista, Knowledge Management consultant
Joaquim will revisit his 17 years of experience at Altitude Software, and then he will explain the skills that an experienced technical writer brings to the market. Joaquim presented his work at Altitude Software on June-2013, and updated the presentation on May-2014, while the second part of the talk was first presented on April-2015.
Daniel Bofill, SISCOG
Daniel will present the complexity inherent to the documentation of the flexible SISCOG products. Daniel has been working on a business case to manage all SISCOG content centrally. Daniel presented his work at SISCOG on October-2013, and updated the presentation on May-2014 and April-2015.

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

This particular session will be spoken in Portuguese, although the slides remain in English.

Thanks to our sponsors for all the support: CLUNL (room), APCOMTEC (marketing), EuroSIGDOC. And special thanks to Prof. Rute Costa and Prof. Clara Nunes Correia for welcoming this event.

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

PS: Unfortunately, Rui Diogo Serra was busy at this date. I will compensate by extending my presentation with my published experience at Altitude Software.

PPS: Don’t forget our joint full-day event on 23-May at ISCTE with ISTAR-IUL, APCOMTEC, and EuroSIGDOC: http://pxquim.com/blog/2015-05-23-twl-iscte.html.

PPPS: Yes, we will have TWO formal events in the same week!

Attachment

Technical Writers @ Lisbon: The 7th Report
Report of the meeting, including the slides of the presentations. 19 pages.

7 May 2015, 6th formal, ISCTE

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 my experiences with different writing tools.

Nineteen people attended the special class, including fourteen students. Presenting the 60 slides ended up taking all the 90 minutes available, leaving no time for questions. Alas, students had to hurry up to the next class, which happened in a room in the opposite side of the building.

20150507-182915b20150507-182848bThe audience was kind in the fourteen public reports. Half of the audience appreciated the historical perspective, but one person wondered whether the materials were out-of-date. Five persons enjoyed seeing the variety of editors, LaTeX, and LinuxDoc.

Only three persons explicitly mentioned that the presentation was too long. I interpret that fact as a sign that the topic is interesting enough. But the long presentation prevented any interaction, and eight persons wanted more interaction, examples, or live demonstrations.

2015-05-twl-report-iconThe Invitation

We have another formal meeting coming up!

Formal meeting:

  • Thursday, May 7th, between 18h00 and 19h30 (be sharp).
  • ISCTE-IUL (Instituto Universitário de Lisboa), building II, room D109.
  • Avenida das Forças Armadas — 1649-026 Lisboa.
Joaquim Baptista, Knowledge Management Consultant
Joaquim will comment on technical writing tools by drawing on his experience with LaTeX, Linuxdoc, reStructuredText, Markdown, TWiki, Pelican, Perl, Python, SGML and XML, DITA, XSL-FO, XLIFF, and others.

The presentation is mainly aimed at students of Software Engineering at ISCTE, although everyone is welcome. The participation is free, but subject to room capacity.

Attachment

Technical Writers @ Lisbon: The 6th Report
Report of the meeting, including the slides of the presentation. 19 pages.

22 April 2015, 5th formal, FCSH

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 challenge to reach new audiences, mostly by reusing old but good presentations, suitably updated. She invited us to talk to a mix of students at FCSH (the Faculty of Social and Human Sciences of the New University of Lisbon).

The multipurpose room 1 at the Research and Development building was practically filled to capacity, with over 40 people. The audience consisted of students of either Translation or Terminology Management, at different levels ranging from undergraduate to PhD candidate. Sadly, we failed to secure some photos.

As usual, the presenters were prepared to speak either in Portuguese or in English, depending on the needs of the audience. The decision to speak in Portuguese was made minutes before Rui started to talk.

The 5th ReportThe event started with Rute Costa welcoming everyone. Then, Joaquim Baptista briefly introduced the community Technical Writers @ Lisbon and explained how the attendees could intervene both by asking questions and by leaving comments in the public notes, which would be published in this report.

Rui Diogo Serra was the first speaker. As a product manager, he explained the complex processes used by Anubis Networks to develop and support its products, where different kinds of documentation play important roles.

Joaquim Baptista explained all the different tasks that a technical writer can do, actually a summary of the tasks he did during his work at Altitude Software. This vision forms the basis for his new consulting business.

Daniel Bofill explained the complexity of SISCOG products, especially their customization. He added details of the proposed project to systematize all documentation. The project was given the go ahead earlier in the same day.

We had several interesting questions after each presentation, although not the level of interaction previously seen in other formal events. Being the first presenter, Rui took most of the questions, enabling Joaquim and Daniel to tailor their presentations somewhat.

21 persons returned their public reports. The honesty of the comments is expected, and greatly appreciated. In fact, the main benefit for presenters is learning from the interaction. Again, the first presenter took most of the heat, while the last presenter got the most praise.

As promised, I created a 26-page report with the slides and the public comments from the audience. I also took the opportunity to answer some of the questions raised by the audience.

I would like to thank Rute Costa and all the attendees for their attention and their questions. We certainly felt welcome.

The invitation

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

We will expand the goodness of this group to a new audience at FCSH, with a new format: a formal meeting that mostly reuses previous presentations.

Formal Meeting:

  • Wednesday, 22 April, between 18h00 and 21h00 (be sharp).
  • FCSH (Faculdade de Ciências Sociais e Humanas), building ID, floor 0, room “multiusos 1”.
  • Avenida de Berna, 26 — 1069-061 Lisboa.
Rui Diogo Serra, Anubis Networks
Rui presented his work at Anubis Networks on October-2013. Since then, Anubis Networks was bought by BitSight, an American company. Rui will update his presentation with fresh insights on working with his new American colleagues.
Daniel Bofill, SISCOG
Daniel presented his work at SISCOG on October-2013, and updated the presentation on May-2014. Daniel has been working on a business case to manage all SISCOG content centrally, and he will update his presentation accordingly.
Joaquim Baptista, consultant
Joaquim presented his work at Altitude Software on June-2013, and updated the presentation on May-2014. Joaquim has recently started an independent consulting business, and he will explain the skills that an experienced technical writer brings to the market.

The participation is free, but subject to room capacity.

Thanks to our sponsors for all the support: CLUNL (room), APCOMTEC (marketing), EuroSIGDOC. And special thanks to Prof. Rute Costa for welcoming this event.

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

PPS: Note FameLab 2015, a friendly competition to communicate science topics to a global audience.

PPPS: Note that you enter the building directly from the street; you do not enter through the main gate of the campus. Security will be expecting us. If you are old enough, you may recall this entrance as being the “DRM” (Distrito de Recrutamento Militar de Lisboa). However, the building was renewed completely.

16+17 May 2014, 3rd formal, ISCTE

ISDOC’2014, ISCTE, 18H00–19H00 + 9H00–17H00

2014-05-twl-report-icon

Rosário Durão
    New Mexico Tech, teacher and researcher since 1996

Carlos J. Costa
    ISCTE, teacher and researcher since 1993

Joaquim Baptista
    Altitude Software, technical writer since 1997

Daniel Bofill
    SISCOG, technical writer since 2012

Marco Neves
    FA-UL, teacher and researcher since 2007

keynote, panel, two experience reports
and lunch

    16 practitioners
    27 students
    18 researchers
    11 academics

with formal ACM proceedings
and our own 32-page report