7 Values of Effective Tech Writing Teams

Not so long ago, designers were not part of the product development cycle. They were only called at the last minute, with the hopes they could help salvage the project. But by then they couldn't do much, since it's hard to backtrack from bad design decisions made early on.

Fortunately this has changed. Both management and developers now see the value of including designers as part of the development cycle.

The same has to happen with tech writers!

In this talk I'll share with you the 7 core values my tech writing team used at OutSystems, where we changed the company culture and won our place in the development cycle.

These values are also being useful to me at Docker, where I'm still learning about the product, the users, and the best way to ship documentation.

Write the Docs 2016


User Story Driven Docs

At OutSystems we make an awesome development platform, but our documentation wasn't that awesome. We focused on describing each button available on the user interface, and not the user intentions and goals.

A clear example of this, was that we had a full documentation page for the find text feature (CTRL+F). It described in excruciating detail every option available on the UI, but didn't told our users how they could actually find what they needed!

For us it was a nightmare to maintain the docs. Our development environment was constantly changing and we couldn't keep up with the changes.

More importantly, we weren't meeting the user needs. And that was clear from pages with a single-digit page view, and from the feedback we got from our customers.

Due to this approach, we also ended up having page titles that were feature-oriented, which is not the best for SEO. For instance, the doc page for the find text feature was called "Find Tool". Who in their right mind would search for that on Google?

In this talk I'll tell you the story of how we stopped trying to document the UI, and started creating user-story driven docs. We now focus on what the user wants to achieve and how to achieve it, independently of how many windows or buttons they need to go through.

I'll cover:

  • How you can check if you're documenting the UI, and why you should avoid doing it
  • Why users stories work better for our users
  • How focusing on user stories changed the culture of our team and allowed us to work on what really matters

I'll also share some unexpected outcomes, like how this lead us to work closer than ever with the development teams. Now our users get twice the cake: better features and better docs!

Write the docs 2015