soap! workshops | june 5 | coming soon
soap! conference | june 6
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.
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!
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.
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.
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
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.
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.
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?
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
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.
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