soap! workshops | june 5 | coming soon

soap! conference | june 6

8:00
8:50
registration
9:00
9:15
warm welcome
9:15
9:55
AI, friend or foe for Documentarians?
▨ Chris Ward
▨ 40 min
There have been a handful of discussions around the impact of artificial intelligence and machine learning on the Documentarian. Will it replace the work we do, supplement it, or present us with new opportunities and tools? In this presentation, I survey the landscape and provide an overview of the present and potential future of technical writing alongside our artificial overlords.
I will look at tips and tricks for writing for conversational interfaces, and the opportunities for our community.
I will show prototypes of integrating a growing number of tools for building bots on top of existing documentation and ponder in which contexts they might be useful, and if they are worth it.
I will look at tools that help us write and manage knowledge better, and wonder who is in control of who?
I will look at the traditional academic areas of linguistics, how NLP sits alongside them, and how documentarians can sit perfectly in the middle.
10:00
10:25
Documenting the known unknowns
▨ Alison MacNeil
▨ 25 min
What do you do when there is a wide gap in understanding between the people who hold knowledge and the audience for the documentation you need to write about that knowledge? What if these two groups are incredibly specialised and your own background doesn’t fit either one of them?
This talk describes the process used by Alison and her colleagues to write documentation for a specialised database query language for working with genomic data. She will discuss some of the pitfalls that the team encountered on the project and how the team used a Docs-As-Code approach to solve many of these issues.
The speaker is a documentarian with 20 years of experience of writing for a variety of projects and she has had to use all that experience to work on this latest endeavour. Alison will talk about techniques she uses to get information from different actors within her company and the approaches she uses to gather feedback from the audience, techniques which are closely related to other software development processes, but also to journalism. She will talk about how to engender contribution from people who have very different work processes and how to make information accessible without sacrificing meaning.
10:30
10:55
To accept and support content as code is a tough managerial decision
▨ Panny Luo
▨ 25 min

I’ve been involved in many documentation projects that vary in ways of working. One of them has tech writers and developers co-author the content following the same software development process, therefore content is partly treated as code. As manager of the writers in this project, I support and encourage this daring trial with efficiency improvement while feeling worried if it demeans the value of writers. In my speech, I’d like to address this dilemma from a manager’s perspective.

10:55
11:20
coffee break
11:20
12:00
Living in Harmony: DITA and Markdown
▨ Patrick Bosek
▨ 40 min

Both DITA and Markdown are here to stay, and both serve different purposes. It’s important to use the right technologies for the right jobs and avoid creating new silos that have to be torn down and migrated in the future. I believe this can be done with a bit of planning and an open mind!

12:05
12:45
How to make your content more accessible?
▨ Kama Jania
▨ 40 min
Unfortunately, most digital products still lack basic features for users with disabilities. Have you ever felt frustrated when you didn’t hear something because the music was too loud or the street noise did not allow it? Or the sun was shining, and you didn’t take the sunglasses and didn’t distinguish between the different color-coded buttons on your smartphone screen? Or maybe you had a migraine and it was hard to read a sentence? Or you had an injury and you had to navigate your phone with one hand only? Imagine that for some people this is what daily life looks like and it is worth to create accessible content for them. After my talk, you will know what it means to design for all people and how designing content for users with disabilities improves the experience for everyone.
12:45
1:55
lunch break
1:55
2:55
Doing docs like code in the real world – an interactive case study
▨ Michał Skowron & Paweł Kowaluk
▨ 60 min
Our hero, a Tech Writer named Jim, works in a company that has a doc team and doc practices. Jim is just starting a new documentation project for a new product. Jim needs to make a series of decisions, each of which will take him closer to using the “docs like code” approach in the new project, or not. You, the audience, will actively participate in this journey. You will vote on each decision that our hero needs to make to help him arrive at the best solution.
3:00
3:25
Cracking the code of visual content
▨ Anton Bollen
▨ 25 min
Images, animations, and videos are essential components for modern technical communication. However, we often struggle to understand key factors about these visuals: How do they enhance content and assist learners, what do effective visuals look like, and how do we optimize graphics to be used in a code-driven environment?
We’ll provide concrete answers to these questions in this research-driven presentation and collectively improve our understanding and use of images, animations, and videos across all of our technical content.
3:25
3:50
coffee break
3:50
4:30
Content as code | Literally
▨ Basia Szwarc & Łukasz Górnicki
▨ 40 min
In our open-source project called Kyma (http://kyma-project.io) we believe that the content-code relationship can only result in well-written and accurate documentation. We treat our content as an integral part of code delivery, based on the same pipelines that code is. During this talk, we would like to share the hows and whys of this approach, showing you that creating content for Kyma goes well beyond Markdown and relies on specifications, autogenerated docs, and the insightful nature of the writer. To make it even more interesting, we bring you different views on the subject: Łukasz will share the benefits of keeping content close to code from a product owner’s perspective, while Barbara will focus on how creating content for Kyma changed a technical writer who, after a couple of years, left the structured and cozy DITA world.
4:35
5:00
Interactive API documentation | Code as content
▨ Jadwiga Sitnicka
▨ 25 min
Welcome to the backstage of API documentation for an IoT platform! You will get to know the IoT platform itself, tools used to create and maintain interactive documentation, and code examples generated automatically on the docs page.
This case study will also show challenges of shaping your own role as a writer in an innovative and ever-evolving project. The talk is a journey of a person with a corporate background among a startup environment.
5:05
5:30
Docs as code | We did it! Didn’t we?
▨ Rafał Pawlicki
▨ 25 min

This is a story about developers who dreamed of having great documentation. They’ve built and deployed a tool that implemented docs-as-code in their company. Did they think of everything? What did they miss? And what should you be aware of during your deployment process? Listen to a true story, and learn from our mistakes on how to avoid many problems that may come when you’ll start using docs-as-code.

5:30
8:00
Closing ceremony & networking at Manggha
8:00
on
After Party! Details TBD

coming soon

soap! conference | june 7

8:00
8:50
registration
9:00
9:10
warm welcome
9:10
9:35
What’s rhetoric gotta do with it?
▨ Lance Cummings
▨ 25 min

What does coding have to do with the Ancient Greek philosopher Aristotle? More than you might think! Since the invention of writing during Aristotle’s time, writing and technology have always been intertwined, especially in rhetorical studies. In most popular cultures today, though, rhetoric has a bad reputation, as it is often associated with political “bullshit.” Oh, that’s “just rhetoric” — it’s not really substance. Starting with ancient Greek thinkers like Aristotle, the field of rhetoric has a 2000 year history with many different definitions. Aristotle defined rhetoric as “the available means of persuasion.” Coding is certainly a part of today’s available means. Quintilian, a medieval rhetorician, defined rhetoric as “a good man speaking.” Coding and content management is not morally neutral, but has important ethical and cultural contexts to consider. This presentation will give a brief overview of modern approaches to rhetoric and how these apply to coding and content management. In the process, I will redefine rhetoric as the art of problem-solving and give attendees useful tools for thinking about how they approach content management and coding.

9:40
10:20
How to steal from developers and be praised for it: version control, continuous integration, and unit tests
▨ Aniko Sebestyen
▨ 40 min

Today, content is read by humans, but it is also processed by software and machines. The concept of content has evolved from help text or user documentation to other user assistance types as well, such as user interface text, training materials, art and even videos. Can all these different types of content be treated as code and if yes, how? How can we tap into the knowledge and expertise that is already available in developer teams? How can technical writers benefit from the techniques and tools that developers commonly use in Agile development environments? I will describe the main concepts behind treating your source files as code. I will provide real-life examples on how you can manage and test your content and how to flexibly enforce terminology, language and style-related rules while being consistent with the product.

10:25
10:50
The Brain API: Closing the gap between Machine Learning and Human Coding
▨ Ludovico Venturini
▨ 25 min
Documentation is code. This is the story of two converging parallels. There used to be a clean separation between language and binary code, until someone thought of using natural language to compile machine code.From typewriters and punch-cards to keyboards. From mysterious error codes to debuggers and CSH. From page design and word processors to re-usability and programming design
patterns.Nowadays writers and coders look very much alike: they encode information in various formats, using structured or unstructured languages, relying on standards and frameworks. But there is still one last node to resolve.
Machines are submissive: they do as told, and need very precise instructions. Humans are subversive: they lie, cheat, get bored, distracted, and simply make mistakes. Does it make sense to talk to humans as if they were machines? Is the left side of your brain really that good at procedural instructions?
What if we could tap into a human’s instincts, feelings, and emotional memory? Could we embrace a more holistic approach? What if… someone developed a brain API?
Augmented and virtual reality, wetware refactoring, AIs, emotional memories, industry 4.0 and IOT are all amazing tools, each one of them bringing disruption to the market but also to the ethics of content. In the era of machine learning, how far are we from human coding?
10:50
11:15
coffee break
11:20
11:45
TBD
▨ Stefan Gentz
11:50
12:20
Distributed content creation
▨ Anton Kolesnyk
▨ 40 min
My talk explores the similarities between our approach to content creation at Plarium and distributed computing. I compared our studios that are distributed across the world to a distributed computing system. With this in mind, I analyzed the features that can be used in Software Development as well as in Technical Communication.
12:25
12:50
Content creation in the multiverse of code – using diversity as an asset
▨ Christian Hamp & Pieterjan Benoit
▨ 25 min

We want to look at content as code in a broader context, more specifically how we can enrich the way content is created from two distinct perspectives:

  • Tools and workflows normally used in an IT environment
  • Working with people from different cultures
12:50
2:00
lunch break
2:00
2:40
Guides as a code without magic
▨ Gregory Brzeski & Adam Dobrawy
▨ 40 min
Technical writers every day face a challenge of maintaining guides while application is rapidly and continuously evolving. Tedious job of verifying flows and updating screenshots which doesn’t offer much reward and always seems as a never ending task.

We had a feeling that guides for a modern dynamically developed applications don’t fit into such dinosaur age documentation process. Therefore without any knowledge about technical writing we went to discover and explore new uncharted territories. Our goal was to create a fully automatic process based on application code, to generate guides, test them and what is more important generate screenshots as well as video for each guide.

We are going to share our experience from this latest journey. Talk about the process, our successes as well as failures, tools and methodologies which we have used in pursuit of our goal.

2:45
3:10
Micro-content, Chatbots, and Machine Learning – What do they mean for Technical Authoring?
▨ Mike Hamilton
▨ 25 min
In our high technology world the need for quality content is always growing. However, how that content is delivered or received is constantly evolving. In this session Mr. Hamilton will introduce the concepts around “Micro-content” and how it will impact traditional technical authoring. The session will cover how the content that you author can support your existing publishing requirements (PDF, HTML5, eBook, etc.) and be made micro-content compatible at the same time. This will prepare your content for use as source material for automated chat feeds, search result enhancements, bots, and other automated delivery techniques.
3:15
3:40
How to make your content more translatable
▨ Marcelina Haftka
▨ 25 min

If content authors and content translators work separately… things happen. When you think about the user and reader experience, a clear, coherent, and meaningful text is what makes your product success.
Learn how to prepare your documentation for a faster and more reliable translation process and how to ensure better quality and greater consistency of your localised content. And yes, your cooperation with translators and translation agencies can be easier and more profitable
for everyone.

3:40
4:05
coffee break
4:05
4:45
Me a coder? Hell no! Oh wait, well maybe
▨ Colum McAndrew
▨ 40 min
The days when standalone help systems were enough to deliver world class user assistance are over. These days content professionals must think outside the box to meet the changing needs of our users. They’re busy and don’t want to take time away from what they’re doing to discover what they need to do. This session demonstrates how by treating content as individual elements, you can deliver it where and when it is most needed. Whether it is embedded UI content, navigational aids, or wizards, you can deliver it whilst maintaining the advantages of a structured help system.
4:50
5:15
Don’t code the (eLearning) content – content the code instead!
▨ Gosia Pytel
▨ 25 min
So much pressure is put on programming these days, learning to code, “coding for girls,” clean code, coding rules… They even named this year’s soap “content as code”! I feel like we code the eLearning content as well – use ADDIE model, Bloom’s, have a certain way to write assessments – all that feels like we code the content. And we seem to be doing it subliminally, that’s even worse! How about an experimental switcharoo – what would “contenting” (air quotes) the code be like? I’d like to present a few ways of how to break free from the restraints of that – somewhat subconscious – code, and content the code of eLearning instead!
5:15
5:30
Closing ceremony
5:30
on
After party @ T.E.A. Time, Dietla 1 Street