soap! workshops | june 5

Who can register for workshops?

▨ Anyone: If you don’t attend the soap! conference (June 6-7), you can still register for the workshop: “How to localize UI and documentation” by Marta Bartnicka.

How can I get the access code to register?

The code will be sent to you in the email that confirms your registration at the soap! conference. If you registered before April 23, the code will be sent to you in a separate email. If you can’t find the code, contact us at piotr.milewski@soapconf.com.
For those who don’t attend the conference, you can register for the workshop: “How to localize UI and documentation” by Marta Bartnicka without an access code.

What's the workshops venue?

This year, for the workshops (June 5) we’ll meet at Office&Cowork Center by Cystersów 20A.

sponge

8:30
11:30

The joy of SVG: Graphics as code

▨ Daniel Barrio Fierro, TechComms Manager at Dolby Labs

▨ 3 hours

I’ll teach you the basics of Scalable Vector Graphics, what they are, how they work, and why you’re missing out if you’re not using them. Next, we’ll cover the structure of SVG files to show you why it makes sense to treat your graphic assets as code. We’ll wrap up with a practical session where you’ll build your own SVG graphic from scratch — but not just any kind of graphic: you’ll also learn how to add interactivity and responsiveness to your image.

DITA is an extensible standard with extreme customization features. You can constrain the existing structure (disallow elements) or specialize (add your own elements) without breaking the standard. All DITA tools will work fine with your very own customized DITA topics.

In this workshop, Jang Graat from Smart Information Design and Stefan Gentz from Adobe will explain why customizing is necessary to leverage the full potential of DITA, and which types of customization are allowed.

Also, we will be showing an entirely visual step-by-step approach on how to customize and constrain DITA for the specific needs of you and your team with a visual DITA Customization Wizard hiding all the technical details under the hood.

If you are using DITA ‘out-of-the-box’ today, this workshop will be an eye-opener. It will bring a huge increase in consistency and productivity to tailor DITA to suit your content needs.

To get the most out of this workshop, it will be good to bring your own laptop with Adobe FrameMaker 2019 already installed. You can download a free and fully functional 30-day version here. Make sure to install it only a couple of days before the workshop, so that you can use the free 30-day trial fully.

foam

8:30
11:30

Code the Process with Design Thinking

▨ Gosia Pytel, Design Thinking Whiz

▨ 3 hours

Many a time was I a witness to a brainstorming session, a “meeting of minds” or some other collaboration event that lasted almost an eternity and achieved nothing. I finally decided to put a stop to it and research why that happens. Interviewing professionals and gathering corporate or startup info, I came up with a process – based on design thinking – that can put a structure to your meeting or session. Learn how to code your meetings for better time management, participation, and successful results. We will use design thinking as the coding language to achieve this.

Can I be innovative if I am not creative? Is a brilliant idea a stroke of fortune? How to get ahead of competitors? What to do when nothing works? My answers and experiences towards these questions (most of the time) are the same – experiment with Design Thinking.

Design Thinking doesn’t come from a one day workshop, a 30 minutes tutorial or by reading 3 books. You have to slowly change your mindset and the way you see the system that you work in. This method is not only for creative professions but for everyone in the organization, starting from testers, developers, business analysts up to entrepreneurs. Design Thinking combined with the Lean Startup’s speed of delivery, is a powerful tool that can make your business better and unleash unknown potential.

After the workshop, attendees will:

– understand the Design Thinking process,
– be able to use Design Thinking both in their professional and private life,
– learn how Design Thinking and Lean Startup can bring their business to the next level,
– discover tools that can apply for individuals, teams or even for the whole organization,
– be familiar with Design Thinking use cases in: tech startups, marketing campaigns, customer services, business’, company culture and many more.

soap! conference | june 6-7

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, Contract Technical Writer at Gregarious Mammal

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

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.

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.

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!

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.

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.

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.

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.

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 in a startup environment.

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.

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, Assistant Professor at University of North Carolina

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

How to steal from developers and be praised for it: version control, continuous integration, and unit tests

▨ Aniko Sebestyen, Senior Technical Writer at One Identity

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

The Brain API: Closing the gap between Machine Learning and Human Coding

▨ Ludovico Venturini, Technical Communicator at Writec

▨ 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?

Adobe CEO Shantanu Narayen recently said – “People buy experiences, not products”. Almost every large company has recognized that it is in the customer experience business. Understanding the customer journey and brand interactions across channels and platforms and their impact on customer experience is crucial for creating a unified CX strategy. But too often, marketing and technical communication content silos and a cluttered IT landscape create disconnected content worlds in voice and tone, visual consistency, and unified accessibility. It’s a complex system coming with a lot of challenges.

This presentation will discuss:
– How multiple brand touchpoints have a cumulative impact on the customer experience.
– How inconsistent content experiences throughout the customer journey create a fuzzy brand experience – and how to avoid this.
– Why technical communication plays an essential role in the customer experience and is crucial for creating high-quality brand experiences.

In this presentation, Stefan Gentz, Adobe Worldwide Technical Communication Evangelist, will dive with you into the world of customer experience strategy and how to blend technical communication seamlessly into the digital experience world of today’s customers.

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.

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.

Micro-content, Chatbots, and Machine Learning – What do they mean for Technical Authoring?

▨ Mike Hamilton, VP of Product Evangelism at MadCap Software

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

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.

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.

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!