NORDIC TechKomm Stockholm 2023 Field Notes
It was hard to choose which tech writing conference to go to this year. Our team decided to spend the 2023 budget on these 7 conferences. The first one is over! Let us share our experience – biased maybe, but hopefully useful to those who plan to attend next year.
Audience: There’s a whole world outside of IT
Nordic Techkomm is the first tekom conference we’ve attended. tekom is the largest professional association for technical communication in Europe, and they hold several events throughout the year. Stockholm’s Nordic Techkomm was the earliest, so we jumped in.
To our surprise, at least 50% of the ~200 attendees came from non-IT technical writing, like machinery and construction, electronics, and home appliances. In our software development bubble, we often forget that the world of technical documentation is much larger and includes people who describe physical objects.
- Virtual/Augmented reality
- Voice search
- AI and ChatGPT
- Help bots
- Smart content reuse
- Content consistency and correctness
- Corporate style guides
- Green Deal and product sustainability
Inspiring talks 💡
Fabrice Lacroix, Documentation on the Web
What are the specifics of online documentation we should address to create the best user experience?
- Content structure and granularity: An inconsistent navigation experience and various topic sizes are documentation problems that are not handled well with analytics, user feedback, or searches. The answer to these problems is dynamic granularity – a must-have feature for any documentation site.
- Content optimization: Why do we still have the navigation tree? Because of the lack of good searches. Generate pages based on searches, not vice versa.
- User journey mapping: Deliver docs in the right context.
- UI customization: Engaging with the content is not possible with web docs. With paper docs, people can use sticky notes or write on the margins. Why don’t we give them similar tools?
Olha Husarenko, Content structure and Documentation templates
Olha talked about content structure and templates. Templates are a technique we use and promote in our tool for technical writers, Writerside. It was great to listen to a like-minded colleague!
So, why structure? Why templates?
- The structure determines how we find, understand, use, and share information.
- Well-structured content is easy to find, read, and follow. It’s also easy to produce and maintain.
- To make content discoverable, make it logical for humans and readable for machines by adding metadata, sitemaps, tags, and labels.
- Check out Nielsen and Norman’s studies on how people read texts.
- Why are templates good for subject matter experts? They can focus on their expertise, get immediate guidance on structure, formatting, and writing style, and save time for review.
- For technical writers, templates remove barriers caused by writer’s block, help share knowledge among team members, save time for editing, and help other teams to create and maintain project documentation.
- With templates, it is easier to encourage developers to participate and contribute to docs.
Dr. Oliver Friese, UX-driven improvement of the installation guide
Taking a dishwasher to a UX lab was something we’d never seen before. Imagine half of your customers have problems with dishwasher installation. How do you learn what to improve in the instructions?
- Set up a testing area in the lab.
- Record how users use the instructions to install the dishwasher.
- Create a “heatmap” on paper instructions and locate problem areas.
- Run a workshop to brainstorm possible solutions.
- Select the best ideas using the dot-voting technique.
Use the results to drastically rework the installation instructions.
Modern content consists of many smaller reusable snippets. How can we build a content review process so that the reviewer sees the content as a whole, not piece by piece? How can we keep them from drowning in changes and commit messages?
Jang’s idea is to let reviewers edit the compiled HTML page. Thus they will have the full context and no need to learn another review tool.
The concept seems very attractive, but let’s wait for an implementation to see if it applies to complicated review processes.
Paula Stern, Lessons of a Documentation Project Gone Wrong
Here are some lessons learned from a project where documentation writing estimates were wrong by 6 times. As Paula put it, “A failed project isn’t a failed project at all if we learn something from it.” 👇
- Accept the insanity – anything could happen.
- Do not sacrifice quality – good enough is not good enough.
- Trust writers in their estimations.
- Plan ahead regarding who will provide what information (and when), and who will answer questions. Ideally, the same person will do both.
- Don’t forget to account for the work on extras like layout and the table of contents.
- Plan buffer time – you will need it.
- Have subject matter experts show you the project. Don’t document based on words alone!
The Future of Documentation – a workshop by Alina Terekhova, JetBrains
During the workshop, Alina presented an exciting challenge that had us all on the edge of our seats. She listed a few massive areas that could potentially impact the world of technical content and technology as a whole after listening to the talks and discussions on the first day. The areas were new technology, economics, health, law, and education. All are critical aspects of our lives and much bigger than producing technical content.
She then gave each team the task of brainstorming ways in which tech writers could respond to these areas and how they influence us. It was a lively workshop that got us all fired up and ready to tackle whatever challenges the world of tech (and non-tech) throws our way.
The outcomes brought more questions than answers, but it’s a good start and solid ground for further experiments and research.
- People are concerned about how to use the new LLMs to save time for more creative tasks and, simultaneously, how their focus might shift from creative work to producing structured machine-readable content.
- The future will bring more forms of technical content, including delivering instructions in Virtual/Augmented reality, conversational interfaces, video embeddings, gamification, and various new microlearning experiences.
- Some classical practices and principles will stay, including content granularity and re-use, visual aids, “write less, say more”, reducing the “input-to-insight” time, and the need to involve documentarians in the development process as early as possible.
NORDIC TechKomm was a great event that brought us new perspectives and food for thought. There’s one more tekom conference on our list of tech writing events in 2023 – the tcworld conference in Stuttgart, on November 22-23. See you there!
Subscribe to Blog updates
Thanks, we've got you!
Collaborating on Docs: Best Practices and Strategies From JetBrains Writers
Our first blog post on Git sparked discussions among different communities of tech writers. Many questioned the described workflow and highlighted that having to collaborate on the same file, pull and rebase changes daily, and resolve conflicts may be a sign of organizational and content management …
Harnessing the Power of the Kotlin DSL for Documentation
DSL? What DSL?The essence of the Kotlin DSLDemonstrationThree key strengths of our approachSeparation of ConcernsDocs-as-Code on a whole new levelExtensibilityWhy Kotlin?Do I need to be a coder to use the Kotlin DSL?Conclusion This material was initially presented at the API The Docs Conference i…
Field Notes: The Writerside Team at Write the Docs Portland and soap! Krakow
Write the Docs Portland Not that I can judge, as I'm not a frequent conference-goer, but Write the Docs (WTD) stands out from all others I have attended – the good, the bad, and the corporate. A friendly and open community was eager to accept anybody who writes docs, whatever their o…
Tech Writer’s Git Story: From Isolation To Collaboration
When I joined JetBrains back in 2014 as a senior technical writer, our team consisted of 5 documentarians covering 6 products. We sat together in a separate room and kept our door closed most of the time, rarely mingling with any developers. We’d see them at the daily IntelliJ IDEA standup,…