Last week I attended my first Write the Docs conference in Portland, OR. I decided to go because of the interesting session schedule and the rave reviews I heard from co-workers who attended in the past. Plus Portland is an amazing city that I love to visit.
This was one of the best conferences I’ve attended. I was so inspired and energized afterwards that I decided to start writing blog posts again (after a three-year hiatus) to share ideas about technical writing. For starters, here are six of my favorite Write the Docs takeaways and themes.
1. The Unconference was just as awesome as the conference
I usually attend UX and content strategy conferences where I feel like I’m the only
technical writer there. Being surrounded by tech writers and documentation enthusiasts (documentarians) was fantastic. I especially loved the Unconference.
The Unconference was located in a separate room, and anyone could sign up for a time slot to host a discussion about anything. I hosted a discussion on how to document walkthroughs (tutorials) and attended discussions on usability and content strategy. I learned so much from these sessions. It was exciting to talk with other smart tech writers facing the same challenges that I do. I’ll definitely try to attend more local writer meetups and discussion groups in Seattle.
2. UI text is also the tech writer’s domain
A main takeaway from the Copy That: Helping Writers Succeed with Effective Product Copy and Embed the Docs! sessions was that UI text (such as buttons, field labels, and messages) is documentation for users who don’t read documentation. Tech writers can influence UI text so it reveals workflows, informs the user about what to do on a page, and facilitates choices made by the user about which action to take. A small amount of copy can have a huge impact on the user experience (UX). Get embedded with the UI team and collaborate with designers and developers more closely during design and wireframing. I currently work closely with Web UI team at ExtraHop to suggest, review, and manage strings. I’ll post future blog posts about tips for how tech writers can effectively collaborate with UI teams.
3. Help readers connect with the docs
A constant challenge tech writers face is that no one wants to read docs. But people rely on docs when they’re stuck or need guidance. So how can tech writers make docs more engaging so users want to read them? The Documentation with Human Connection, Writing So Your Word Are Read, and What Writing Fiction Teaches You About Writing Documentation sessions took a look at this challenge and identified some core issues. For example, content is written in a way that can be either be too exclusive for a specialized audience or too ambiguous, lacking context. And technical content doesn’t generate emotions like success and satisfaction, which is what you want users to feel after reading documentation.
Some general takeaways from these sessions:
(1) Of course, avoid jargon. But also teach, don’t tell. When we’re unsure about who we’re writing to, it’s easy to be ambiguous and vague, and dump a lot of technical details into docs. We need to understand our audiences better, and approach help content from mulitple perspectives. By pretending you are sitting next to the user and explaining the concept, we can create content that is more engaging.
(2) Make concrete connections with the reader. An example for how to do this (for technical conceptual topics) is free writing. Free writing is an exercise where you write and write and write about a technical topic with no constraints, and then distil the main themes that really connect with you and your reviewers.
(3) One of the literary devices that generates emotion involves rising and falling action. Documenting a procedure creates rising action. But often there isn’t a confirmation about the procedure that gives the user insight into what they just accomplished. By adding this guidance and resolution (falling action), it can help users feel empowered.
4. Work with support
When documenting a product, it’s impossible to anticipate in advance all the questions that a customer might have. So it makes sense that tech writers work closely with Support. The support team encounters customer questions all day, every day. And just like customers, support teams rely on docs to answer those questions. A main takeaway from the Two Great Teams That Work Better Together: Bridging the Gap between Documentation and Support and Just-in-Time Documentation: Employing Agile Methodology to Create Living Documentation sessions was that writers should link up with support teams in a more systematic way. There shouldn’t be a wall between support and documentation teams. Support team members should be stakeholders in the document review process. Setting up an automated method for the support team to make doc requests in support tickets can also help with:
- Building specific, relevant documentation
- Reducing the time it takes for Support to answer common questions
- Helping doc teams learn more about customers.
5. Technical writers wear many hats these days
The tech industry is fast-moving and constantly changing, taking tech writers quickly downstream into uncharted waters. Product releases are getting faster and new tools are constantly popping up and being adopted. Tech writers aren’t just writers anymore. We’re adopting new identities to keep up with the pace. We have to also be content strategists, developers, UI designers, UX researchers, and data scientists. My favorite takeaway from the 7 Values of Effective Tech Writing Teams session: tech writers should see themselves as the CEO of docs. We need to establish a vision for documentation and share that with our company. It’s important to communicate the value of what tech writers do and how we contribute to the user experience, which drives sales and customer satisfaction.
6. The perception of doc quality goes beyond the words
The usability of the product in general, as well as the usability of the document design (including white space, headings, etc.), can positively or negatively impact how the user feels about your docs. In the CSAT – What’s That? session, it was discovered that the usability of the documentation website negatively impacted a doc rating. A research survey developed by the Google documentation team compared help content in two different layouts. The difference in layout correlated to a difference in perceived quality of the docs. Usability shouldn’t be confined to the realm of designers and product management. Technical writers have a stake in usability too.
More tips to share
There is so much more from the conference that I’ll try to cover in later posts. And I have many ideas to expand on and share. Moving forward, I’ll write blog posts with tips to help tech writers with the following topics:
- Conducting usability tests for documents
- Developing a content strategy that can help tech writers
- Using social media to increase visibility of tech content
- Collaborating with UI developers and designers
- Creating quick personas and journey maps
- Developing walkthroughs for onboarding and advanced users
If you have questions, please leave a comment.