Ivana Isadora Devcic

Biography

Ivana Isadora has written her way through various roles: from content marketing for FOSS communities and creating software reviews and tutorials as a tech journalist, to developing product documentation for enterprise security software and RESTful APIs as a technical writer. She has made it her mission to help people use software more efficiently and productively. Translator by trade, Ivana applies the principles of clear, precise, and truthful communication in her documentation work, and makes it a priority to convey audience-appropriate messaging. She tries to dedicate her free time to highbrow activities, but more often than not, the truth lies in the direction of memes.

Talk description

Most of us are not going to change the world. Don’t let that stop you. You can still change the way APIs are created in your community, and reap the benefits of the spec-first design approach. Be the hero your community needs and your APIs deserve.

Imagine a place where a lone technical writer is creating API specs by hand, from scratch, for a bunch of existing APIs. A place where developers don’t know if an API exists at all because there’s no documentation for it. Where product owners design new APIs in a single Excel spreadsheet.

Places like that exist; maybe you’ve experienced something similar first-hand. Perhaps you thought to yourself, “I wish I could turn this place around”. And you can. You’re not “just a technical writer” - your perspective, insight, and skills are crucial for not just documenting, but also designing and developing usable APIs.

In this talk, you will hear some ideas for what technical writers can do to make their job documenting APIs easier and collaboration with stakeholders stronger. We will look at the benefits of the spec-first approach, strategies for implementing it, and challenges you may encounter. A real-world example of building a spec-first API culture within a company will illustrate how long it took, what worked (and what didn’t), and where improvement is still needed.

The goal is to equip technical writers with advice and motivation to start influencing API design decisions in their community. Documentarians represent the voice of the user to a great extent, but this voice is not always heard. Luckily, it’s not too late to change that.