The annual Tekom conference is promoted as the largest event for technical communication in the world. But when attending the conference three years ago, I noticed that the main focus was on “typical” technical communication such as hardware documentation, legal standards, and alike. Topics related to software documentation, agile development, and APIs were only rarely seen. This seemed to have changed when having a look at this year’s agenda. That’s why I gave it another try - for one day (only Tuesday). Let me share my experiences and highlights with you.
Documentation for Agile Release Cycles - Petra Herbst
Wow…what a great start! The first talk I attended was already one of my favorites. Petra seems to have a similar working environment to what we have here at ePages. She’s closely collaborating with developers who work in two-week sprints and review her documentation tasks, as well as with Product Owners with whom she creates stories together, including tasks for TechWriting. This task creation can be facilitated by using a story template that already includes tasks for developers (write first draft), POs (check if the team forgot to write the first draft for features that should be documented), and TechWriters (check and enhance first draft). Maybe that’s an approach we could reuse for our process one day.
My favorite take-aways that I 100% agree with:
- “Developers are much more fond of writing documentation when they can do it in their developer tools right next to the code.” That’s why Petra moved documentation from Confluence to Asciidoc.
- “Everyone is responsible for documentation”, including POs, Devs, and TechWriters.
- “A story is done when the documentation is done.”
Interactive Docs Meetup - Chris Ward
Chris took the chance to organize a meetup about interactive docs. This meetup did not only focus on API documentation (e.g. on the usage of Postman Collections), but also on general questions like:
- Can I replace my documentation with a video?
- How can I use voice recognition for documentation?
- Should my documentation include images and screenshots? If so, how do I best localize them?
Especially the last question and the related discussion was very insightful for me. I’ll definitely have a look at SVGs and how they can support localization.
Technical Writing in an Agile World - Judith Forstner
Judith and her TechWriter and developer colleagues changed from Waterfall development to a Scrum-based method. She explained how the TechWriters found their way into the new process, and how they collaborate with developers. Initially, they came up with two options:
To sum it up: installing a dedicated TechWriter in the team didn’t work out as there were not enough TechWriters. But in a short trial phase, they figured out that a dedicated TechWriter was highly accepted in the development team, and that he was able to develop a better product know-how. Of course, there were also some downsides, such as possible idle times if the development team is not working on tasks that are relevant for documentation. But if you have enough resources, why not give it a try?
Trend-Slam for Technical Communication
I have to admit, the slam was not really related to software documentation. But it was a nice and modern format, and a great end of the day. In a very entertaining way, Ulrike Parson and Dieter Gust argued about five topics related to technical communication, e.g. the current status of PDFs and XML. Both had strong opinions and consciously polarized.
A really creative format that I’d definitely recommend to every TechWriter, and that I’d love to see on next year’s agenda.
Summary
I was surprised - in a positive way. Software documentation really made it to the Tekom, and also on a high quality level. The above mentioned talks were only a selection of the offered talks related to software documentation. Markdown, review processes, and Scrum also made it to the agenda. Nevertheless, the main focus is still on hardware documentation topics. But it’s definitely possible to spend the whole day just on non-hardware topics. Not to forget: some of them are even interesting for both areas of documentation, e.g. corporate language, or the above mentioned slam. So my personal result: Tekom 2019 and software documentation definitely fit together!
About the author
